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 your session backend code and Dockerfile

Let's create the following files for our session backend.

You can use any language or framework in a session backend. If you can run it in a Docker container, you can run it on Jamsocket.

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${PORT}/`)

To package your session backend into a container, write a Dockerfile that Jamsocket can use to build and push your session backend code.

FROM node:18-slim
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.


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).

Build and push your session backend code to Jamsocket

You can build your session backend docker image and push to Jamsocket's container registry with a single command:

npx jamsocket push my-hello-world --dockerfile ./Dockerfile

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 "{}" \

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.