Skip to content

Upgrade Guide

Jump to bottom
Will Luck edited this page Oct 17, 2026 · 9 revisions

Upgrade Guide

General Procedure

docker pull ghcr.io/will-luck/docker-sentinel:latest
docker stop sentinel && docker rm sentinel
# re-run with the same flags and volumes
docker run -d --name sentinel ... -v sentinel-data:/data ...

On startup, Sentinel automatically migrates the BoltDB schema to the current version.

Alternatively, use the Self-Update button on Settings > About. Sentinel pulls the new image and recreates itself via an ephemeral helper container.

Data Persistence

All state lives in the /data volume.

Path Contents
/data/sentinel.db BoltDB (containers, policies, hooks, settings)
/data/cluster/ mTLS certificates (server CA, agent certs)

Always use a named volume (-v sentinel-data:/data). Back up before a major upgrade:

docker cp sentinel:/data/sentinel.db ./sentinel-backup.db

Version History

3.1.0

  • Passkey RPID rule. SENTINEL_WEBAUTHN_RPID must be a hostname with a dot (for example sentinel.example.com) or localhost. An IP address never worked for passkeys, because browsers refuse it. A single-label name such as sentinel did work in 3.0 and is now refused, so passkeys registered under such a name stop working. With an RPID it cannot use, Sentinel starts with passkeys turned off and logs passkeys disabled: .... Password and SSO sign-in are not affected. To keep passkeys, set a hostname with a dot, open Sentinel under that name, and register your passkeys again.
  • Register a passkey again if passkey sign-in never worked with it. Earlier versions did not ask the authenticator to keep a discoverable passkey, so a security key could store one that Sentinel's passkey sign-in cannot find. Remove it on the My Account page (user menu) and register it again. Passkeys kept by a password manager or by the browser's own passkey store are discoverable already and keep working.
  • Rare key types: a stored passkey with an unusual key and algorithm pairing may no longer be accepted. Register it again.
  • Agents follow Docker events, so a container removed, renamed, stopped or started on an agent host shows on the server within seconds instead of at the next 5 minute resend. If the agent reaches Docker through a socket proxy, allow the events endpoint (on docker-socket-proxy that is EVENTS=1, its default). Without it the agent logs a warning and falls back to the 5 minute resend.

3.0.0

  • Portainer connector removed. Sentinel no longer scans or updates containers through the Portainer API, and the Portainer pages, settings and /api/portainer/* endpoints are gone. To keep monitoring those hosts, run a Sentinel agent on each one (see Cluster Mode). Saved Portainer settings stay in the database, so downgrading restores them. Queued Portainer updates are dropped at startup, and SENTINEL_PORTAINER_URL / SENTINEL_PORTAINER_TOKEN are ignored with a warning.
  • Give Sentinel time to finish an update when it stops: stop_grace_period: 2m in compose, or --stop-timeout 120 with docker run.
  • Built with Go 1.27.2. macOS binaries need macOS 13 or later, and Sentinel exits at startup if GODEBUG sets a setting Go 1.27 removed (tlsrsakex, tls10server, tls3des, tlsunsafeekm, x509keypairleaf, asynctimerchan, x509sha1) to its old value. Remove such a setting before upgrading.
  • Cluster mode: agents now renew their certificates. Upgrade the server first; agents older than v3.0.0 do not renew, so update them before their first year is up ("Auto-update agents" now works).
  • 2FA: if you turned on 2FA before this release, your recovery codes are unusable. Turn 2FA off and on again to get working ones.
  • remove_volumes now means "start the updated container on fresh anonymous volumes", like docker compose up -V. Off (the default) keeps them, with their data.
  • A value saved on the Settings page now overrides the environment for image backup, remove volumes and the rollback policy.
  • Single sign-on accounts are bound to the provider's issuer and subject. Nothing links to an existing account by username on its own any more, so users who signed in with SSO under an older version are told "This account is not linked to your sign-in provider yet". Link them with Allow SSO link on the user list, from the Account page, or with SENTINEL_OIDC_LINK_EXISTING=true (skips admins and accounts with 2FA or a passkey). If your admins only ever used SSO, set SENTINEL_OIDC_LINK_ADMIN=<username> once and restart. See Authentication and Security.
  • Keyless cosign verification needs a signer. Set cosign_identity and cosign_oidc_issuer (or SENTINEL_COSIGN_IDENTITY and SENTINEL_COSIGN_OIDC_ISSUER), otherwise keyless checks fail. With verification on enforce and no cosign available (the official image has none), updates are now refused instead of going ahead unchecked.
  • History is pruned after 90 days (SENTINEL_HISTORY_RETENTION_DAYS, 0 keeps everything). Records of applied updates and rollbacks are kept.
  • Behind a reverse proxy, set SENTINEL_TRUSTED_PROXIES to the proxy's address so failed logins are counted per client.
  • Enrolment tokens are longer: they end with the fingerprint of the server's CA. Copy the whole token. Agents before v3.0.0 can use the new tokens.
  • Cluster agents receive the server's settings (image cleanup, image backup, hooks, dependency awareness). An agent's own environment wins. The server's Remove volumes setting is sent to agents only if Remove volumes on agents too is turned on (off by default). Lifecycle hooks now run on agents.
  • New "Update Skipped" notification (a pre-update hook exited 75). It is on for channels that receive all events; a channel with a saved event list needs it ticked.
  • Self-update with two Sentinels on one host now refuses rather than guess which one to swap. If Sentinel cannot read its own container ID, set SENTINEL_SELF_CONTAINER.
  • Agents now validate and roll back a new container like the hub does (grace period, healthcheck), with SENTINEL_GRACE_PERIOD / sentinel.grace-period honoured on agents.
  • Self-update works with published ports (the Docker socket must be mounted in the Sentinel container).
  • Unreadable environment values are logged at start-up and the default is used. SENTINEL_CLUSTER_PORT is now honoured.
  • A container that had no hostname of its own gets a new one when updated (its own short ID), and compose depends_on dependents are restarted only with restart: true.

2.12.x

Breaking change:

  • Webhook secrets must use the X-Webhook-Secret header. Query-string authentication for the webhook endpoint has been removed because proxies and access logs record URLs verbatim, leaking the secret. Update any external integrations to send the secret in the X-Webhook-Secret HTTP header instead.

New features:

  • Multi-instance Portainer support (removed in v3.0.0) - configure and monitor multiple Portainer servers simultaneously. Instances can be added, removed, and toggled at runtime via the web UI or API.
  • Engine ID deduplication - Sentinel collects the Docker Engine ID from each source (local socket, cluster agents, Portainer endpoints) and automatically blocks duplicate scanning when two sources point at the same daemon.
  • SENTINEL_CLUSTER_ADVERTISE environment variable - add extra IPs or hostnames to the server TLS certificate SANs so agents can connect via Tailscale IPs, DNS names, or other addresses not auto-detected from host interfaces.
  • Stopped containers shown by default on the dashboard (configurable in Settings).

Bug fixes:

  • Fixed a data race on the Portainer instances slice when concurrent HTTP requests modified the list during a scan. The scan now snapshots the slice under a read lock.
  • Dashboard no longer gets stuck showing "Updating" after approving a queued update. The SSE reconnect handler catches up stale badges.
  • Swarm service task rows now use correct colspan values for proper column alignment.
  • Images page column alignment corrected in both normal and manage mode.

2.8.0

  • Removed the Actions column from the dashboard table
  • Status badges are now clickable: Update, Start, Stop actions inline
  • Column widths rebalanced for better Image and Ports display
  • Policy and Status columns centred for consistency

2.6.0

  • Version scope setting (relaxed/strict) for update filtering
  • Per-row removal in bulk queue actions without page reload

2.5.1

  • Fix multi-arch digest mismatch causing no-op updates
  • Agent auto-update setting for remote Sentinel agents
  • Remote containers included in dependency graph
  • GHCR switch available for remote containers
  • Hook and notification storage scoped by host for remote containers

2.5.0

  • Images page with manage mode and unused image cleanup
  • Local container updates now pull the target version correctly
  • SSE auto-refresh for remote container updates

2.4.0

  • Version constraint by tag precision scope (major, minor, patch)

2.3.5

  • Fall back to registry digest for swarm services without pinned digest

2.3.4

  • Queue accordion, account nav, self badge, logs overflow fixes
  • Cluster policy overrides, dashboard counts, digest-only display fixes
  • Cluster remote container actions and navigation fixes

2.3.3

  • Surface skipped containers in history and scan toast

2.3.2

  • Default to manual updates for safety
  • Registry test button no longer wipes unsaved credentials
  • Update-to-version for containers and self-update

2.3.1

  • Light theme and auto (system preference) mode
  • Scan gate: initial scan deferred until dashboard loads after fresh setup
  • Login page CSS moved to shared stylesheet with theme support

2.3.0

  • Daily digest notifications with configurable schedule
  • Per-container notification mode overrides
  • Dashboard banner for pending updates
  • Notification deduplication

2.2.0

  • Cluster mode with mTLS
  • Agent enrolment via PKCS#10 CSR
  • Autonomous agent mode
  • Setup wizard with role selection

2.1.0

  • Lifecycle hooks (pre/post-update)
  • Hook management UI
  • Exit code 75 skip semantics
  • Label persistence for hooks

2.0.0

  • Full rewrite with web dashboard
  • Authentication (password, WebAuthn, API tokens)
  • RBAC with 3 built-in roles
  • Docker Swarm support
  • Notification channels (7 providers)
  • GHCR alternative detection
  • Dependency-aware update ordering
  • Prometheus metrics

Breaking Changes

Version Change Migration
2.0.0 Complete rewrite Fresh install recommended. v1 config not compatible.

Cluster Upgrades

  1. Upgrade the server first.
  2. Upgrade each agent in turn.
  3. Agents reconnect automatically after restart. No re-enrolment required.
  4. mTLS certificates are preserved in the agent volume.

Docker Compose

docker compose pull
docker compose up -d

Compose handles the stop/remove/recreate cycle. The named volume is preserved automatically.

Swarm Service Update

docker service update --image ghcr.io/will-luck/docker-sentinel:latest sentinel

Home

Getting Started

Using Sentinel

Multi-Host

Security

Reference

Clone this wiki locally