Production deploy

api.nodetool.ai runs on the Docker host 46.224.131.110. Caddy routes traffic to app-1 and app-2 with cookie affinity. Both replicas use the same Supabase database, auth project, and storage buckets. Deployment configuration and the rolling release script live in the adjacent nodetool-deploy repository, checked out at /home/claude/nodetool-deploy on that host.

Resource changes between replicas

Set distinct NODETOOL_INSTANCE_ID values (app-1 and app-2) and provide DIRECT_URL on each replica for the shared Supabase database. The listener URL must use a direct or session-mode connection, not transaction-mode port 6543. The Docker host has no IPv6 route to Supabase’s direct endpoint, so a direct DIRECT_URL fails there and the replica listens on its session-mode DATABASE_URL instead, with a warning in its log. DATABASE_URL can continue to use transaction pooling for ordinary writes. Allow one additional database connection per replica and apply the resource_change_outbox migration before deploying the server. See configuration for payload limits, retention, and reconnect behavior.

After deployment, keep a browser on one replica and force an MCP client onto the other. Have the agent edit the open timeline while the browser has an unsaved edit to a different merge unit. Verify the agent edit merges without a reload, preserves the local draft, and arrives once. Repeat with an edit whose ops exceed 7500 bytes. This requires both replicas to run the new server.

Release chain

A push to main starts the Docker image build, User Journeys, and Test independently. The Deploy to Docker workflow runs when any of them completes. It deploys only when Docker and User Journeys have succeeded for that exact commit and Test has succeeded or has no run, because Test filters its push trigger by path. It counts only push runs. It does not wait: the last workflow to finish triggers the release. It rejects a commit superseded on main. It retains the historical filename fly-deploy.yml, but does not invoke Fly or use its credentials. Manual dispatch follows the same gates and uses the dispatch commit, never a mutable image tag. Its skip_test_gate input releases the current main commit when Test has failed or has not finished. Docker and User Journeys must still succeed, and the run logs a warning naming the Test result. The host’s forced command checks only Docker, User Journeys and the current main, so it accepts such a release.

The Deploy server job connects to the host over SSH and sends only the full commit SHA. A host-side forced command validates the SHA, rechecks the build gates and current main, and invokes the rolling script with ghcr.io/nodetool-ai/nodetool:main-<shortsha>. The host resolves this to an immutable digest. GitHub serializes release runs without cancelling a rollout in progress. The host script also takes a deployment lock.

web-deploy.yml follows Deploy to Docker and checks that its Deploy server job succeeded before releasing the same commit to Cloudflare Pages. A skipped or failed server release cannot promote the frontend. Cloudflare Pages credentials remain in web-production.

GitHub connection settings

Repository variables:

  • DOCKER_DEPLOY_HOST: the Docker host IP or hostname.
  • DOCKER_DEPLOY_USER: the SSH account that owns the deployment checkout.

Repository secrets:

  • DOCKER_DEPLOY_SSH_KEY: a dedicated Ed25519 private key.
  • DOCKER_DEPLOY_KNOWN_HOSTS: the host’s verified SSH public key entry.

The matching public key in authorized_keys uses restrict and forces /home/claude/nodetool-deploy/bootstrap/github-ssh-deploy.sh. It permits only a full release SHA or the read-only check probe, not shell commands, forwarding, or a terminal. The SSH client requires the pinned host key. Database credentials remain in the host’s mode-0600 .env and are not copied into Actions.

Rolling release

The script pulls the image and runs its database migrations once before changing either replica. It then verifies the peer is healthy, signals SIGUSR2 to drain the selected replica, waits for its turns and jobs to reach zero, and recreates it. Health must pass before the peer is drained. The saved image digest changes only after both replacements succeed. A failed migration or replacement stops the release. Migrations must remain compatible with the previous image during the handover.

Inspect the running deployment on the host:

cd /home/claude/nodetool-deploy
docker compose ps
node bootstrap/verify.mjs --public
docker compose logs --tail 100 app-1 app-2

For a manual rollback, review schema compatibility and run the rolling script on the host with a previously deployed immutable image digest. Rollbacks are not accepted by the restricted GitHub key, which only releases current main. Check game draft storage compatibility before choosing an image whose game reader predates the dotted draft version identifiers. Unchanged database schemas do not make those readers compatible.

The deployment setup guide covers DNS, trigger-dispatch handover, pool sizing, and affinity checks. The retained Fly guide covers legacy rollback operations, not the active GitHub release destination.

MCP connectors

claude.ai and other OAuth MCP clients need NODETOOL_ENABLE_MCP=1 and NODETOOL_PUBLIC_URL=https://api.nodetool.ai on both replicas. Without the public URL, /.well-known/oauth-authorization-server answers 404 and /mcp sends a 401 with no WWW-Authenticate challenge, so Claude cannot discover the authorization server. Set NODETOOL_WEB_URL=https://app.nodetool.ai too. The web app is served from that origin, so consent must open there for the browser to keep its session and return to Claude after sign-in. See Connect claude.ai.

Run history retention

The production image sets NODETOOL_STORAGE_AUTO_CLEANUP=1. The server sweeps run trace owners on startup and on its maintenance timer, using each account’s retention settings. Run content expires under runTraceRetentionDays and finished records under terminalJobRetentionDays. Keep automatic cleanup enabled on the hosted service to meet the privacy policy. Self-hosted operators can override the image setting when configuring their container. Local desktop installs keep the existing manual cleanup default.