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.