Quickstart

Quickstart

💡

Note: we'll be using Docker's command-line tool (opens in a new tab) and NodeJS (>=18) (opens in a new tab), so get those installed if you haven't already.

Write a simple session backend

Write a simple NodeJS HTTP server by creating a server.js file with the following code:

server.js
const http = require('http')
const PORT = process.env.PORT || 8080 // Your session backend must run on port 8080 for Jamsocket to find it.
 
const server = http.createServer((req, res) => {
  console.log('Received a request!')
  res.end('Hello World')
})
 
server.listen(PORT, () => {
  console.log(`Server running at http://0.0.0.0:${PORT}/`)
})

Create a Docker image

To package your session backend into a container, write a Dockerfile that Jamsocket can use in the next step.

Dockerfile
FROM node:18-slim
WORKDIR /app
COPY server.js .
CMD ["node", "server.js"]

Developing your code locally

Run the Dev CLI

npx jamsocket dev --dockerfile ./Dockerfile --watch .

npx jamsocket dev will start a Jamsocket dev server at localhost:8080. Check out the Dev CLI for more details on how the Dev CLI works.

Spawn session backends locally

The same spawn endpoint /user/:username/service/:service/spawn (opens in a new tab) can be used to spawn a session backend in development and production. To spawn a session backend locally, try running:

curl -X POST http://localhost:8080/user/my-account/service/my-hello-world/spawn

A successful JSON response will include a connection url that looks like this "url": "http://localhost:9090/tYVHfS4PKgufdhwGCnn6LLfAaCo_iAHitbw4Bg8ETjA/". Use this URL to access your session backend API.

Connect to your session backend API

Once you've made a spawn request, you should see logs in the Dev CLI that show a backend Ready status. This means that a backend has been successfully spawned and is ready to receive connections.

Curl the url from the spawn request to hit the server running in your session backend. Doing so should return the Hello World string from the backend.

curl URL_FROM_SPAWN_REQUEST

Deploy to Jamsocket

Login to Jamsocket

npx jamsocket login

Create a service

npx jamsocket service create my-hello-world

You should see the service appear on your Jamsocket dashboard (opens in a new tab).

Upload your session backend code to your service

Build your Docker image with the Docker CLI.

docker build --platform linux/amd64 --tag hello-world-image .

Push your session backend image to Jamsocket via the CLI.

npx jamsocket push my-hello-world hello-world-image

Using the HTTP API in production

In an production setting, you can use the HTTP API to spawn backends. Create an API token from the Jamsocket dashboard (opens in a new tab). In the same Settings page, you'll find your account name, which must be provided in the spawn url.

A request to spawn a backend will look like this:

curl \
  -X POST \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d "{}" \
  https://api.jamsocket.com/user/ACCOUNT_NAME/service/my-hello-world/spawn

See your session backend's logs

Finally, you can view logs from your session backends with the Jamsocket CLI.

npx jamsocket logs {BACKEND_NAME}

Or view logs from your dashboard (opens in a new tab) when you click on the backend name in the Service page.

Next Steps

Jamsocket is built by Drifting in Space.