# Updating Sentinel

> **Sentinel v2 (beta):** This page documents Sentinel v2, a beta rewrite that may change before the stable release. It does not apply to Sentinel v1, the current stable version: see the [Sentinel v1 documentation](/docs/sentinel.md).

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](/docs/sentinel/v2/install/#container-image).

<Callout type="warning" title="No latest tag for v2 during the beta">

During the beta, `latest` points to Sentinel v1. Never deploy v2 with `latest`, or an image pull can replace v2 with v1.

## Before you update

1. **Read the release notes** of every version between yours and the target in [Releases](/docs/sentinel/releases/). Look for configuration keys that changed, and for releases marked as critical or security updates.

2. **Take a snapshot** of the database, or back up the database with its own tools. See [Snapshots & backups](/docs/sentinel/v2/operations/snapshots/).

3. **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 `doctor` in a one-off container of the new image, with the same config, secret, and data mounts as the server:

```bash
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> doctor
```

`doctor` never changes the schema. With automatic migrations, `storage.schema` reports how many schema changes the new version will apply at startup. A `FAIL` line names the key or check and the reason, and the command exits with code `1`. See [`doctor`](/docs/sentinel/v2/reference/cli/#doctor).

## 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](/docs/sentinel/v2/operations/schema-migrations/#apply-a-migration).

## Update a single instance

With Docker, as installed in [Docker](/docs/sentinel/v2/install/docker/):

1. **Pull the new image:**

```bash
docker pull ghcr.io/altcha-org/sentinel:<new-version>
```

2. **Replace the container** with the same options and the new tag:

```bash
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`.

3. **Check the startup log** for the migration and the license:

```bash
docker logs sentinel
```

```text
INFO 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](/docs/sentinel/v2/operations/clustering/#instance-slots). 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, `maxSurge` at 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_LIMIT` until a regular slot frees up.

A Kubernetes Deployment strategy for a license with up to 10 instances (1 burst slot):

```yaml
strategy:
type: RollingUpdate
rollingUpdate:
maxSurge: 1
maxUnavailable: 0
```

During 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](/docs/sentinel/v2/operations/clustering/#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](/docs/sentinel/v2/operations/snapshots/).

## 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:

```toml
[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 calling `GET /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]`, or `UPDATE RECOMMENDED`.
- Without internet access, set `enabled = false`, or point `url` at a mirror of the feed. Requests honor `HTTPS_PROXY`; see [Outbound proxy & air-gapped deployments](/docs/sentinel/v2/configure/air-gapped/).

Two [alert rules](/docs/sentinel/v2/operations/alerts/) 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:

```bash
curl -H 'Authorization: Bearer <jwt>' https://sentinel.example.com/v2/releases
```

```json
{
"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](/sentinel-api-docs-v2.html#tag/releases/GET/v2/releases).

## Related

- [Releases](/docs/sentinel/releases/)
- [Schema migrations](/docs/sentinel/v2/operations/schema-migrations/)
- [Clustering & high availability](/docs/sentinel/v2/operations/clustering/)
- [Snapshots & backups](/docs/sentinel/v2/operations/snapshots/)
- [`[releases]`](/docs/sentinel/v2/reference/configuration/#releases) in the Configuration reference
- [Alerts](/docs/sentinel/v2/operations/alerts/)
