All jobs

Add a Dockerfile to a Socket.IO Chat Server

Yes. An agent writes a two-stage Dockerfile for a clustered Socket.IO server with native sqlite3, makes workers and the database path configurable, and opens a PR.

Run this on RushOpens the console with this prompt ready to send, in a Project that has your repository.

What the agent does

The agent reads the server before it writes an image, because a Socket.IO app that forks workers and opens a SQLite file has two things a container has to be told about. In an app laid out like socketio/chat-example, package.json is an ES module with one start script, node index.js, and depends on socket.io ^4.7.2, express ^4.18.2, @socket.io/cluster-adapter ^0.2.2, sqlite ^5.0.1 and sqlite3 ^5.1.6, the last of which package-lock.json marks hasInstallScript: it downloads a prebuilt binary for the running Node release or compiles one with python3, make and g++. index.js checks cluster.isPrimary, forks one worker per availableParallelism() with PORT set to 3000 + i, and calls setupPrimary(); each worker opens chat.db in the working directory, creates the messages table with a unique client_offset, builds the Server with connectionStateRecovery and the cluster adapter, serves index.html at / and listens on its own port. .gitignore excludes node_modules and chat.db, and the only container hint is a .codesandbox/Dockerfile that says FROM node:20 and nothing else.

Two small code changes make the image usable, and the pull request keeps them separate from the Dockerfile. The worker count becomes Number(process.env.WORKERS) || availableParallelism(), because a container that forks a worker per host CPU opens as many ports as the host has cores while Docker publishes one; with WORKERS=1 the single worker listens on 3000 and the cluster adapter still works. The database path becomes process.env.DB_PATH ?? 'chat.db', so the file can live on a volume instead of in the image's writable layer, where it would vanish with the container. Nothing else in index.js changes, and the default behaviour outside Docker is what it was.

The Dockerfile has two stages on node:22-bookworm-slim. The deps stage copies package.json and package-lock.json, installs python3, make and g++ only there, and runs npm ci --omit=dev, so sqlite3 either fetches its prebuilt binary for Node 22 or compiles against the toolchain that stage has; the final stage copies node_modules from deps with no compiler in it, copies index.js and index.html, sets NODE_ENV=production, WORKERS=1, DB_PATH=/data/chat.db and PORT left to the primary, declares VOLUME /data and EXPOSE 3000, switches to the node user that the base image provides after chown on /data, and ends with CMD ["node", "index.js"]. A HEALTHCHECK runs node -e with a fetch of http://localhost:3000/ and exits non-zero on anything but a 2xx, since the slim image has no curl. A .dockerignore lists node_modules, chat.db, .git and .codesandbox, so the build context carries only the source.

The sandbox has no Docker, so the agent installs it first with sudo apt-get install -y docker.io, starts dockerd, then runs docker build -t chat . and keeps the build log that shows which path sqlite3 took. It runs the image with -p 3000:3000 and a named volume on /data, waits for the health check to report healthy in docker ps, and sends two requests: curl -s localhost:3000/ to show index.html comes back, and a curl to /socket.io/?EIO=4&transport=polling to show the Engine.IO handshake answers with a session id, which proves the worker and the adapter are up. It stops the container, starts a second one on the same volume and runs the handshake again to show chat.db survived. The .codesandbox/Dockerfile is left alone, with a line in the pull request saying it serves the sandbox and not production.

Start it with one API call

POST https://api.phoenix.so/o/{org}/sessions with this body:

{
  "agent": "claude",
  "input": "Add a production Dockerfile to this Socket.IO chat server. Read package.json, package-lock.json, index.js, index.html, .gitignore and .codesandbox/Dockerfile first. Make the number of cluster workers configurable with a WORKERS environment variable that defaults to the current behaviour, and the SQLite file path configurable with DB_PATH defaulting to chat.db. Write a two-stage Dockerfile on a slim Node 22 image where only the first stage has python3, make and g++ for the sqlite3 native module, the final stage runs as the node user with NODE_ENV=production, WORKERS=1, DB_PATH on a /data volume, EXPOSE 3000 and a HEALTHCHECK that uses node fetch rather than curl, plus a .dockerignore. Install Docker in the sandbox, build the image, run it with a named volume, show the home page and the Engine.IO polling handshake answer, then restart the container on the same volume and show the handshake again. Open a pull request that explains why WORKERS defaults to 1 in the image and how to run several workers behind a proxy.",
  "resources": [
    {
      "url": "https://github.com/your-org/your-app"
    }
  ]
}
  1. Get an API key. In the console, open Settings, then API keys, and create a key for your org. Send it in the Authorization header as a Bearer token.
  2. Send the request. POST the body in request.json to https://api.phoenix.so/o/{org}/sessions, with your repository as the resources URL. The run starts in its own cloud sandbox.
  3. Read what came back. Follow the run on its live stream or wait for the run.completed webhook, then read the result and its trajectory.

What comes back

What comes back is a pull request that adds Dockerfile and .dockerignore and changes index.js for the two environment variables, with a README.md section that shows the docker build and docker run lines and the three variables. The description pastes the build log line where sqlite3 resolved its binary, the docker ps line showing healthy, the curl of the home page and the two Engine.IO handshake answers across the restart.

There is no workflow in this repository, so no check runs on the pull request; the run's record is the evidence, and it keeps the Docker install, the build and every curl in order. The pull request names the add-docker-publish-workflow job as the next step for building the image on each push.

Before merging, a reviewer decides whether the image should pin a Node 22 patch release rather than the floating tag, whether WORKERS should default to more than one behind their load balancer, and whether the SQLite file should move to a shared database once the app runs on more than one host. The agent changes no Socket.IO event handler.

Run it on every Node service without an image

A team with several Socket.IO services starts one run per repository from its own server: one POST /o/{org}/sessions each, with the repository in resources and a request_id that is a UUID v5 of the repository's full name, so a retried call returns the run already started. Each run reads its own index.js, so a service on the Redis adapter gets a REDIS_URL variable and no volume, and one that already has a Dockerfile gets a pull request that reviews it against the same checklist instead of a second one.

After that, an automation in the Project with a github trigger on pull_request.opened and pull_request.synchronize and the prompt "if this pull request adds a dependency with an install script or a file the server reads at runtime, check the Dockerfile's build stage and copy list still cover it, and say so in a comment" keeps the image buildable. The trigger adds the pull request after the prompt and fires only for work by owners, members and collaborators.

The use case this job follows, with its automation and trigger: Hand off a long task.

Why run it on Rush?

A Dockerfile written without building it fails in ways a reviewer cannot see: a slim final stage that still carries a compiler because the stages were not split, a sqlite3 install that compiled nothing and crashes on first import, a database written into the container layer and lost on restart, or a cluster that opens eight ports behind one published one. The agent builds the image, runs it twice on the same volume and reads the real handshake answers in its sandbox before it opens the pull request.

Every command stays with the run, from the Docker install to the second handshake, and the pull request quotes them. Building images for a dozen small Node services at once costs no more attention than one, because each run has its own machine, its own record and its own pull request.

Frequently asked questions

Why does the image default to one worker?

Because index.js gives each worker its own port, 3000 + i, and a container publishes the ports you name. With one worker everything is on 3000 and docker run -p 3000:3000 reaches it. To run several, a proxy inside or in front of the container has to route to each port with sticky sessions, which the pull request describes; for most deployments running several single-worker containers behind the Redis adapter is simpler, and that is the add-redis-adapter job.

Does sqlite3 compile in the image?

Only if it has to. Its install script first tries a prebuilt binary for the running Node release and architecture, and compiles with node-gyp when there is none, which is why the deps stage carries python3, make and g++. The final stage copies the finished node_modules and has no compiler, and the build log in the pull request shows which path the install took.

Where do the messages go when the container is replaced?

To the /data volume. DB_PATH points chat.db there, and the agent proves it by stopping the container, starting a new one on the same named volume and showing the Engine.IO handshake again. A bind mount or a managed volume works the same way; the pull request also notes that SQLite on a volume serves one host, so a multi-host deployment needs a server database.

Why not the official node:20 image the CodeSandbox file uses?

That file exists to give the online sandbox a Node runtime and installs nothing else, so it says little about production. The pull request uses the slim variant to leave out the full image's build tools and documentation, picks an active LTS line, and leaves .codesandbox/Dockerfile as it is so the sandbox keeps working.

More Socket.IO jobs

The same job on other stacks

Keep reading