Docker Labels

Docker Labels

Sentinel reads Docker labels prefixed with sentinel. to configure per-container behaviour. Labels are set at container creation time and take effect on the next scan.

---

Label Reference

Label	Values	Default	Description
sentinel.policy	auto, manual, pinned	Value of SENTINEL_DEFAULT_POLICY (default: manual)	Update policy for this container
sentinel.self	true	(absent)	Marks the Sentinel container itself. Updates are always queued, never auto-applied. Required for self-update via the dashboard
sentinel.maintenance	true	(absent)	Set automatically during updates; removed when complete. Docker-Guardian reads this to skip containers mid-update. Do not set manually
sentinel.helper	true	(absent)	Set on the ephemeral helper container during self-update. Managed automatically
sentinel.schedule	Cron expression (5-field)	(absent)	Per-container scan schedule. Container is only checked when the cron fires. Standard format: min hour dom month dow
sentinel.delay	Duration (1h, 30m, 7d)	0 (immediate)	Minimum time an update must be known before it is auto-applied. Prevents reacting to images that are republished or yanked shortly after release
sentinel.grace-period	Duration (10s, 5m)	Global SENTINEL_GRACE_PERIOD (default: 10s)	How long to wait after starting the new container before validating it. Capped at 1 hour
sentinel.pull-only	true	false	Pull the new image but do not restart the container. Useful for pre-staging images
sentinel.remove-volumes	true	false	Remove anonymous volumes when replacing the container during an update
sentinel.notify-snooze	Duration (6h, 1d)	0 (no snooze)	After sending a notification for this container, suppress repeat notifications for this duration. Resets when the remote digest changes
sentinel.semver	patch, minor, major, all	(inferred from tag)	Controls version scope for semver-tagged images. patch = same major.minor only. minor = same major only. major/all = any newer version
sentinel.include-tags	Regex	(absent)	Only consider tags matching this regex when checking for updates
sentinel.exclude-tags	Regex	(absent)	Ignore tags matching this regex when checking for updates
sentinel.depends-on	Comma-separated names	(absent)	Containers that this one depends on. When a dependency is updated, this container is restarted. Requires SENTINEL_DEPENDENCY_AWARE=true
sentinel.hook.pre-update	Shell command	(absent)	Command executed inside the old container before the update starts. Requires SENTINEL_HOOKS=true
sentinel.hook.post-update	Shell command	(absent)	Command executed inside the new container after the update succeeds. Requires SENTINEL_HOOKS=true
sentinel.hook.timeout	Integer (seconds)	30	Timeout for hook commands. Applies to both pre-update and post-update hooks on this container

---

Policy Details

Policy	Behaviour
auto	Updates applied automatically when detected (subject to delay, maintenance window, and grace period)
manual	Updates detected and queued; must be approved via the dashboard or API
pinned	Container is skipped entirely during scans. No registry checks, no notifications

Policy Resolution Order

Sentinel resolves the effective policy using this precedence:

1. Database override (set via dashboard or API, persisted in BoltDB)
2. Docker label (sentinel.policy)
3. Latest-tag auto-update (if SENTINEL_LATEST_AUTO_UPDATE=true and tag is :latest)
4. Global default (SENTINEL_DEFAULT_POLICY, default manual)

---

Semver Scope

When a container uses a semver-tagged image (e.g. nginx:1.25.3), Sentinel can detect newer versions by listing tags from the registry.

Scope	Behaviour	Example: current 1.25.3
patch	Same major.minor only	Accepts 1.25.4, rejects 1.26.0
minor	Same major only	Accepts 1.26.0, rejects 2.0.0
major / all	Any newer version	Accepts 2.0.0
(default)	Inferred from tag precision	1.25.3 infers patch-level; 1.25 infers minor-level

---

Tag Filtering

sentinel.include-tags and sentinel.exclude-tags accept Go regular expressions applied to tag names. When both are set, include is applied first, then exclude removes matches.

Example: only accept stable releases, skip release candidates:

sentinel.include-tags: "^v?[0-9]+\\.[0-9]+\\.[0-9]+$"
sentinel.exclude-tags: "rc|beta|alpha"

---

Duration Format

Labels that accept durations (sentinel.delay, sentinel.grace-period, sentinel.notify-snooze) support:

Suffix	Meaning	Example
s	Seconds	30s
m	Minutes	15m
h	Hours	6h
d	Days (24h)	7d

Standard Go duration strings are accepted (e.g. 1h30m). The d suffix is a Sentinel extension.

---

Standard Labels Read by Sentinel

Sentinel also reads these non-Sentinel labels:

Label	Purpose
com.docker.compose.project	Groups containers into stacks on the dashboard
com.docker.compose.project.working_dir	Used for compose file sync (when enabled)
com.docker.compose.project.config_files	Path to compose file for image tag sync
com.docker.compose.service	Service name within a compose project
com.docker.compose.depends_on	Compose dependency chain, read alongside sentinel.depends-on
com.docker.swarm.task	Filters Swarm task containers (updates handled at the service level instead)
org.opencontainers.image.version	Resolves the version behind mutable tags like :latest

---

Docker Compose Example

services:
  webapp:
    image: ghcr.io/myorg/webapp:1.5.0
    labels:
      sentinel.policy: "auto"
      sentinel.semver: "minor"
      sentinel.delay: "2h"
      sentinel.grace-period: "30s"
      sentinel.exclude-tags: "rc|beta"
      sentinel.hook.pre-update: "nginx -t"
      sentinel.hook.post-update: "curl -sf http://localhost/health"
      sentinel.hook.timeout: "60"
      sentinel.depends-on: "db,cache"

  db:
    image: postgres:16
    labels:
      sentinel.policy: "manual"
      sentinel.semver: "patch"
      sentinel.hook.pre-update: "pg_dump -U postgres mydb > /backups/pre-update.sql"
      sentinel.hook.timeout: "120"
      sentinel.notify-snooze: "1d"

  cache:
    image: redis:7
    labels:
      sentinel.policy: "auto"
      sentinel.remove-volumes: "true"

  monitoring:
    image: grafana/grafana:latest
    labels:
      sentinel.policy: "auto"
      sentinel.pull-only: "true"
      sentinel.schedule: "0 3 * * *"

  legacy:
    image: myorg/legacy-app:2.1.0
    labels:
      sentinel.policy: "pinned"

  sentinel:
    image: ghcr.io/will-luck/docker-sentinel:latest
    labels:
      sentinel.self: "true"
      sentinel.policy: "manual"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - sentinel-data:/data

---

Docker Run Example

docker run -d \
  --name webapp \
  --label sentinel.policy=auto \
  --label sentinel.semver=minor \
  --label sentinel.delay=2h \
  --label sentinel.grace-period=30s \
  --label "sentinel.hook.pre-update=nginx -t" \
  --label sentinel.hook.timeout=60 \
  --label sentinel.depends-on=db,cache \
  ghcr.io/myorg/webapp:1.5.0

docker run -d \
  --name sentinel \
  --label sentinel.self=true \
  --label sentinel.policy=manual \
  -v /var/run/docker.sock:/var/run/docker.sock:ro \
  -v sentinel-data:/data \
  -p 8080:8080 \
  ghcr.io/will-luck/docker-sentinel:latest