Deploying the web app on N0
Documentation / Web setup · Accounts · Contributing
What ships is the web app (apps/web) and nothing else. The CLI, the
gateway and trazum serve are loopback-only by design — a cost oracle on a
network interface is an attack surface — and they belong on the machines
where your agents run, next to the logs they read. Deploying the web app
changes none of that: trazum profile usage.jsonl and the store still live
wherever the calls happen.
The pieces in this repository#
| File | Job |
|---|---|
Dockerfile | Builds @trazum/core, then the web app with Next's standalone output — the runtime image carries the traced server and static assets, nothing else. |
n0-app.json | The N0 manifest: a db (Postgres 16), a migration service that applies apps/web/db/*.sql and stops on error, and the web entrypoint. The SQL is embedded because the platform writes config_files before the container starts — and packages/core/test/n0-manifest.test.js holds the embedded copy byte-identical to apps/web/db, both directions, so it cannot drift. |
.gitea/workflows/build-and-push.yml | Runs inside the N0 workspace's Gitea: builds the image and pushes :latest, the commit SHA and any release tag to the workspace registry. N0 never builds images itself. |
.github/workflows/mirror-to-n0.yml | The bridge for updates: on every push to main here, mirrors the repository into the workspace's Gitea — which triggers the build above. Does nothing (and says so) until the three N0_* secrets exist, so a repository that has not opted in loses nothing. |
One-time setup#
- In N0: Developer Settings → API Tokens ("Build an app with Claude")
gives
N0_API_BASEandN0_API_TOKEN. - Mint a Gitea token from the API (
POST …/workspaces/{ws}/gitea/token/), create thetrazumrepo there, and storeN0_GITEA_HOST,N0_GITEA_USER,N0_GITEA_TOKENas GitHub repository secrets — that arms the mirror workflow. - Replace the
webservice's placeholder image inn0-app.jsonwith the workspace registry path (gitea-<workspace>.apps.<domain>/<org>/trazum). The placeholder is loud on purpose: the manifest guard requires it until a real workspace exists. - Import and deploy:
POST …/apps/definitions/with the repo URL, thenPOST …/apps/with{"app_type": "trazum"}. SetPOSTGRES_PASSWORDandTRAZUM_DATABASE_URLtogether in the app's Secrets UI — the second embeds the first, which is why neither is auto-generated. Without a database URL the app runs on the memory store, which forgets on restart and says so in its own documentation.
How an update travels#
Merge to main here → GitHub mirrors to the workspace Gitea → Gitea Actions
builds and pushes the image tagged with the commit SHA → pin that SHA in
n0-app.json's web image, re-import the definition, redeploy. Two rules
learned from the platform, worth keeping:
:latestdoes not update a running app. The cluster caches an unchanged tag; a redeploy with the same image reference serves the old build. Pin the SHA — the same reasoning as this repository's own Action pins in the README.- Test with a preview, not with production.
POST …/apps/{id}/previewswith the new tag deploys a second instance at<subdomain>-pv-1with empty data; verify it, thenpromote— the parent redeploys with exactly the tested snapshot, and the preview is destroyed.
What this deliberately does not do#
No automatic deploy on merge: the mirror and the build are automatic, the deploy is a decision — pin, re-import, redeploy (or preview → promote), each a single API call, each leaving a record. And nothing here touches the provider-credential arcs (1.54.0, 1.57.0) or turns the policy into a server: the config stays a file in this repository, deployed with the app.