Updates
Self-hosted Atrium instances receive software updates through the Update Agent — a dedicated container in the stack that checks for updates, downloads new container images, and applies them.
Update modes
The update behavior is controlled by the ATRIUM_UPDATE_MODE environment variable:
| Mode | Behavior | Use case |
|---|---|---|
notify (default) | Updates are detected and shown in the admin dashboard. You must explicitly approve each update. Images are pre-downloaded in the background. | Self-hosted deployments where you want control over when updates are applied. |
auto | Updates are applied automatically when detected. No admin approval needed. | Deployments where you trust the update pipeline and want zero-touch maintenance. |
disabled | No update checks. The instance runs on the current version indefinitely. | Air-gapped or fully manual deployments. |
How updates work
Detection
The Update Agent periodically checks in with the Control Plane (default: every 5 minutes). The check-in response includes an update manifest if a new version is available on your release channel.
Download
When an update is available, the Update Agent downloads new container images by digest (not by tag). Digest-based pulls ensure you get exactly the tested image, not a tag that might have been overwritten. If the update includes a new Docker Compose template, that's downloaded too.
Downloads happen in the background — they don't affect your running instance.
Approval (notify mode)
In notify mode, the admin dashboard shows a notification:
- The current version and the available version.
- A summary of what changed (release notes).
- An "Apply Update" button.
Clicking "Apply Update" triggers the update process. The Update Agent applies the update during a brief maintenance window (typically 30–60 seconds of downtime).
Application
The Update Agent:
- Writes the updated Compose file (if changed).
- Runs
docker compose up -d --remove-orphans— this pulls new images and restarts changed containers. - The application runs database migrations automatically on startup.
- Performs health checks on all containers.
- Reports the result to the Control Plane.
If health checks fail, the Update Agent rolls back: restores the previous Compose file and runs docker compose up -d with the previous configuration.
Release channels
Your instance is assigned to a release channel that determines which versions you receive:
| Channel | Description |
|---|---|
stable | Production-ready releases. This is the default for all self-hosted customers. |
beta | Pre-release versions for customers who want early access to new features. |
Channel assignment is configured in the Control Plane. Contact support to change your channel.
Version information
The admin dashboard shows:
- Current version — The platform version currently running.
- Available update — If a newer version is available on your channel.
- Update mode — Whether updates are automatic, require approval, or are disabled.
- Last check-in — When the instance last communicated with the Control Plane.
Manual updates
If the Update Agent is disabled or you prefer fully manual updates:
- Check for the latest version on your release channel.
- Update the image tags in your Docker Compose file.
- Pull new images:
docker compose pull - Apply:
docker compose up -d - Run migrations if needed:
docker compose exec -T backend node dist/cli/migrate.js up
This bypasses the Update Agent entirely. You're responsible for version compatibility and rollback.