Deployments

Deploy from your checkout

Run these commands from the directory containing atrium.yaml:

atrium validate
atrium deploy

The CLI previews the plan and asks for confirmation. A confirmed deploy packages local source, uploads it, and requests a managed build. Eligible uncommitted files are included: a commit SHA alone does not describe a dirty checkout. Review source and ignore rules before confirming.

Packaging uses .gitignore, .dockerignore, and built-in private/build-directory exclusions. Keep credentials, local environment files, generated artifacts, and large datasets out of deployment source; do not assume every untracked file is excluded. The compressed upload limit is 200 MiB. The CLI checks the uploaded source checksum before submitting the deployment.

atrium deploy --no-follow
atrium deploy --follow-timeout 1200
atrium deploy --format json

These are alternative invocations, not consecutive steps. Following defaults to 600 seconds; 0 waits for a terminal event. --no-follow returns after submission. Stopping the follower or reaching its timeout does not cancel the server-side build. Use --yes only after reviewing the intended inputs.

Understand the stages

Source-backed deployments run managed Cloud Build stages. You do not need cloud-provider credentials or direct infrastructure commands for the developer deployment workflow.

Stage	What to check
Source upload	The intended checkout and its checksum were accepted.
Build and push	Service Dockerfiles, dependencies, and build commands succeed.
Database migrations	The Hasura project's migrations apply to the configured database.
Hasura metadata	Metadata is compatible with the migrated schema.
Service updates	Application services update after database steps succeed.
Completion	A successful deployment publishes routes. Test the returned URLs.

Database stages apply when a Hasura service is declared. See Databases and migrations for prerequisites and ordering. Terminal results are SUCCEEDED, FAILED, or CANCELED.

Validation and preflight report configuration and prerequisites. They do not execute the full build or prove that health checks pass, source files are present, or a database exists. Registration and service-bootstrap metadata are not provisioning success.

An integration submitting a deployment without uploaded source can use a configured external worker. That request may remain queued when no worker is available. This is a fallback, not the normal source-upload workflow. If it happens unexpectedly, keep the deployment ID and contact Atrium.

Find a deployment

atrium status
atrium deployments --limit 10
atrium deployments --before "2026-09-20T12:00:00Z" --limit 10

Use the next-page timestamp from the previous history page instead of the illustrative timestamp. History shows previous requests; status describes current resolved app state. Deployment detail provides the result and events belonging to one specific request.

In Studio, open the app's Deployments tab, then a deployment. Review its source commit/branch and dirty indicator when available, per-service phases, and events. CLI output includes a Studio link. The API reference covers history and detail requests.

Follow events and read logs

atrium logs frontend --lines 100
atrium logs frontend --follow

Use a service key from your manifest. Recent reads can include runtime logs and deployment events. Following streams stored deployment events for that service; it is not an indefinite tail of every runtime log line. Repeat a recent-log read when diagnosing new runtime activity.

For a deployment event stream, use the API directly:

curl --no-buffer --fail-with-body \
  -H "Authorization: Bearer $ATRIUM_ACCESS_TOKEN" \
  "https://api.atrium.st/v0/platform/deployments/$DEPLOYMENT_ID/events?format=sse"

Supply an authorized workspace token securely as ATRIUM_ACCESS_TOKEN. DEPLOYMENT_ID comes from submission/history. JSON reads return events and a cursor. Reconnect with cursor=<last-received-cursor> to continue after the last event. The endpoint also supports format=ndjson and stream=true. Process replayed events idempotently.

The service logs API uses limit, while the CLI uses --lines. API callers can also supply cursor and deployment to inspect a specific request. Streaming is available.

Diagnose failures

1. Open the failed deployment, not only the latest app status.
2. Find the first failed service/phase and read its events or recent logs.
3. For build errors, reproduce the service build with the same inputs.
4. For database errors, check migration/metadata ordering, service key, access, and existing schema.
5. Correct the cause, review the source, and submit another deployment deliberately.

Failure preserves the published route set, but does not automatically undo SQL or already-updated services. Do not assume a retry is harmless after a partial migration. Delayed events can leave visible state behind the build; refresh the same deployment before submitting another. Share its ID and a redacted error excerpt with support, never credentials.

Completion emails

When delivery is enabled, completion emails report success, failure, or cancellation and link to Studio. CLI and Studio requests identify the initiating developer as recipient; configured GitHub-triggered deployments currently use the app creator. A verified email address is required.

Email may be delayed or skipped and does not determine deployment success. Deployment detail is the authoritative result. Messages are summaries, not a replacement for events or service logs.