Updating Sentinel
A Sentinel update is a new container image. The new version migrates the database when it starts, so most updates are: read the release notes, check the new image against your configuration, and replace the containers. This page covers single-node and rolling updates, rollback, and how Sentinel tells you that an update is available.
Versions and image tags
Sentinel v2 is published as ghcr.io/altcha-org/sentinel for amd64 and arm64:
| Tag | Contents |
|---|---|
2.0.0-beta.x (e.g. 2.0.0-beta.1) | A release. Includes every database backend except Oracle. |
2.0.0-beta.x-oracle | The same release plus the Oracle Instant Client, for Oracle databases. |
Pin an exact tag in your deployment and change it on purpose. If you use the -oracle image, stay on the -oracle tag of each new release. More on the images is in Container image.
Before you update
Read the release notes of every version between yours and the target in Releases. Look for configuration keys that changed, and for releases marked as critical or security updates.
Take a snapshot of the database, or back up the database with its own tools. See Snapshots & backups.
Check your configuration with the new image. Unknown or invalid keys stop the server at startup, so validate the config with the version you're about to run. Run
doctorin a one-off container of the new image, with the same config, secret, and data mounts as the server:docker run --rm \ -v "$PWD/sentinel.toml:/home/nonroot/sentinel.toml:ro" \ -v "$PWD/secrets:/run/secrets:ro" \ -v sentinel-data:/home/nonroot/data \ ghcr.io/altcha-org/sentinel:<new-version> doctordoctornever changes the schema. With automatic migrations,storage.schemareports how many schema changes the new version will apply at startup. AFAILline names the key or check and the reason, and the command exits with code1. Seedoctor.
Schema migrations
Every version brings its own schema. By default ([database] auto_migrate = true), the first replica of the new version adds the missing tables, columns, and indexes at startup, under a database lock, before it serves requests. Migrations only add, never drop or rename, so replicas of the old version keep working against the migrated database. That's what makes rolling updates and rollbacks possible.
With [database] auto_migrate = false (or [clickhouse] auto_migrate = false), the server doesn't change the schema and refuses to start until it's current. Generate the migration with the new image, have a database administrator apply it, and only then roll out the new version. The steps are in Apply a migration.
Update a single instance
With Docker, as installed in Docker:
Pull the new image:
docker pull ghcr.io/altcha-org/sentinel:<new-version>Replace the container with the same options and the new tag:
docker stop sentinel && docker rm sentinel docker run -d --name sentinel \ -p 3000:3000 \ -p 127.0.0.1:3002:3002 \ -v "$PWD/sentinel.toml:/home/nonroot/sentinel.toml:ro" \ -v "$PWD/secrets:/run/secrets:ro" \ -v sentinel-data:/home/nonroot/data \ ghcr.io/altcha-org/sentinel:<new-version>The data volume carries over: with embedded SQLite, it holds the database and, with generated secrets,
secrets.json.Check the startup log for the migration and the license:
docker logs sentinelINFO altcha_sentinel: schema migrations complete applied=… INFO exotdb_license_runtime: licensed to "Example Inc." (…), valid until 2026-12-16, instances 1/3 INFO altcha_sentinel: listening addr=0.0.0.0:3000 tls=false
A single instance is unavailable between stopping the old container and the new one listening: a few seconds plus the migration. Challenges and verifications requested in that window fail. To avoid the gap, run two replicas and update them one at a time.
Rolling update
With several replicas, replace them one at a time. Old and new versions can run side by side: the database is migrated by the first new replica, and the old replicas keep working against it.
A new replica needs an instance slot. When you already run as many replicas as the license allows, the new one starts on a burst slot and moves to a regular slot as soon as an old replica stops. A license has max(1, ceil(instances / 10)) burst slots, so:
- start at most that many extra replicas at once: in Kubernetes,
maxSurgeat or below the burst slot count; - finish the rollout within 30 minutes per replica; a replica that holds a burst slot longer answers
503 LICENSE_INSTANCE_LIMITuntil a regular slot frees up.
A Kubernetes Deployment strategy for a license with up to 10 instances (1 burst slot):
strategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 1
maxUnavailable: 0During the rollout, the Cluster page and GET /v2/cluster/replicas show each replica's version, so you can follow the update replica by replica. See List the replicas.
Probe readiness with GET / (or the image's healthcheck), not GET /.health: a replica starts listening only after migrations and its license slot, and /.health reflects shared storage, which would fail every replica at once.
Roll back
Because migrations only add, you can usually go back to the previous image after an update: the older version ignores the tables and columns it doesn't know. Roll back the same way you updated, with the previous tag.
- Data written by the newer version stays in the database. If a release changes how existing data is stored, its release notes say so; follow them.
- With
[database] auto_migrate = false, the older version's startup check passes, because it ignores tables and columns it doesn't declare. - As a last resort, restore the snapshot you took before the update. A restore replaces the data, including every change made since the snapshot. See Snapshots & backups.
Release feed and update alerts
Each replica reads the Sentinel release feed and tells root users when a newer version is out. It's on by default:
[releases]
enabled = true # false: no fetches, no release_* alerts
url = "https://altcha.org/sentinel-releases.xml" # RSS 2.0
interval = "6h" # fetch and alert check (1h–7d)- The feed is fetched at startup and then every
interval. Opening the Releases page (or callingGET /v2/releases) also starts a fetch in the background when the last attempt is over an hour old. - A release is newer when its version, taken from the title (
2.0.0-beta.2: …), is above the running version. The feed also lists v1 releases, which are never newer than a v2 version. - The default feed lists stable releases only. To be alerted about beta versions too, set
url = "https://altcha.org/sentinel-releases.xml?beta=true". - A release is critical when its title or description contains
[Critical],[Security], orUPDATE RECOMMENDED. - Without internet access, set
enabled = false, or pointurlat a mirror of the feed. Requests honorHTTPS_PROXY; see Outbound proxy & air-gapped deployments.
Two alert rules use the feed:
| Rule | Severity | Raised when |
|---|---|---|
release_critical | high | A newer release is critical. |
release_outdated | medium | Newer releases have been out longer than [alerts.release_outdated] max_age (default 14d), counted from the oldest newer release. |
Root users see the feed on the Releases page of the admin UI, or through the API with a session token:
curl -H 'Authorization: Bearer <jwt>' https://sentinel.example.com/v2/releases{
"data": {
"enabled": true,
"currentVersion": "2.0.0-beta.1",
"feedUrl": "https://altcha.org/sentinel-releases.xml",
"fetchedAt": "2026-11-19T09:29:45.218956+00:00",
"checkedAt": "2026-11-19T09:29:45.218956+00:00",
"error": null,
"releases": [
{
"version": "1.43.0",
"title": "1.43.0: Security Updates and HIS v2",
"link": "https://altcha.org/docs/sentinel/releases#1.43.0",
"publishedAt": "2026-11-18T00:00:00+00:00",
"description": "<div class=\"prose …\">…</div>",
"critical": false,
"newer": false
},
…
]
}
}error holds the last failed fetch's reason and is null after a success; the releases from the last successful fetch stay listed. With [releases] enabled = false, the response has "enabled": false, feedUrl: null, and no releases. The endpoint needs a root user's session. The schema is in the API reference.
Related
- Releases
- Schema migrations
- Clustering & high availability
- Snapshots & backups
[releases]in the Configuration reference- Alerts