Upgrade Guide

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

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