Configuration reference

This is the single source of truth for everything freshdock reads. Environment variables are the primary way to configure a deployment and override the file per field, so a container never has to mount a freshdock.toml. The one thing they can’t express is a registry whose host has dots in it, since that name can’t be spelled as an env-var name.

New here? Start with the quickstart. For the command flags, see the CLI reference.

Contents

• Labels
• Compose projects
• Watching every container
• Environment variables
• The optional freshdock.toml file
• [settings]
• [registry.<name>]
• [notifications.<name>]
• A complete example

Labels

freshdock is opt-in: a container with no freshdock.enable=true is ignored entirely. (That default can be inverted fleet-wide, see watching every container.) All behaviour is driven by these Docker labels, set in compose under labels: or with docker run --label.

Values are case-insensitive and tolerate surrounding whitespace. An invalid value is reported with the offending label named.

Notes:

• Watchtower labels are read too: com.centurylinklabs.watchtower.enable, com.centurylinklabs.watchtower.monitor-only, and the watchtower lifecycle.pre-update/post-update hook labels (whose timeouts are in minutes) are honoured as fallbacks, so a migrated fleet needs no relabelling. A freshdock.* label always wins over its watchtower counterpart. See coming from Watchtower.
• With freshdock.enable=true and no freshdock.mode, the mode is watch (detect and notify, never mutate). Change that fleet-wide fallback with [settings] default_mode or FRESHDOCK_DEFAULT_MODE; an explicit freshdock.mode label always wins.
• freshdock.schedule refines only the calendar modes (nightly / weekly / monthly). live and watch are polled on the daemon’s run --interval instead and ignore the label. See scheduling.
• The post-update health timeout and the grace period for containers without a healthcheck are hardcoded: not configurable by label, file, or env. See health & rollback: timings.
• A container whose image is pinned to a digest (repo@sha256:...) has no moving tag to follow. freshdock reports it as pinned (no check) and never updates it.

Compose projects

A container in a multi-service Docker Compose project is not updated on its own. freshdock reads the project’s com.docker.compose.* labels, re-runs the one-shots the project waits on (condition: service_completed_successfully) first, then updates the rest in depends_on order. A failed one-shot aborts the rollout. The label gate still applies, with one exception: an unlabelled one-shot that the project waits on is re-run anyway. Explicit opt-outs and watch mode still win.

On by default; [settings] compose_aware = false or FRESHDOCK_COMPOSE_AWARE=false turns it off. [settings] one_shot_timeout (FRESHDOCK_ONE_SHOT_TIMEOUT) sets how long a one-shot may run, default 600 seconds. Full rules in Compose projects.

Watching every container

[settings] watch_all (or FRESHDOCK_WATCH_ALL=true) inverts the opt-in gate, the way Watchtower worked: every running container counts as enabled unless it opts out. An absent freshdock.enable label then means enabled, not ignored. The default is false.

Three labels opt a container back out:

A container enabled this way takes its mode from default_mode (FRESHDOCK_DEFAULT_MODE), or watch when that is unset. Turning watch_all on therefore never restarts anything by itself; it starts updating once default_mode names an updating mode. Explicit labels always win: a container with freshdock.mode=live keeps live, and freshdock.enable=true behaves as it did before.

freshdock skips its own container when it enables containers this way, so the daemon never tries to update itself. It recognises itself by the Docker default hostname (the short container id). If you give the freshdock container a custom hostname, add freshdock.mode=off to it, or set freshdock.enable=true and an updating freshdock.mode on it if you do want it updated. The same applies when freshdock runs with network_mode: container:<name>: it then carries the namespace owner’s hostname, so label both containers explicitly in that setup. The skip is evaluated per invocation, so a freshdock check run outside the daemon’s container still shows a row for it.

freshdock recreate <name> follows the same rules: with watch_all on, an unlabelled container passes the gate, while freshdock.enable=false and freshdock.mode=off are still refused.

A runnable stack is in watch-all.yml.

Environment variables

Environment variables override the file per field: a _TOKEN variable on its own replaces the file token while keeping the file username. For registry and notification targets, <NAME> is the table name, upper-cased, with - replaced by _.

freshdock --help prints the same override list (after_long_help).

The optional freshdock.toml file

freshdock runs without a file. Reach for one only when you need something environment variables can’t express:

1. Registry credentials for a custom host with dots (e.g. registry.example.com), whose name can’t be spelled as an env-var name.
2. A notification target you’d rather keep in a file, though these can be declared from the environment too (see FRESHDOCK_NOTIFY_<NAME>_URL and Declaring targets from the environment).

When present, it is resolved in this order:

1. --config <path> flag
2. $FRESHDOCK_CONFIG
3. ./freshdock.toml in the working directory

An explicit path (flag or env) that doesn’t exist is an error; a missing default ./freshdock.toml is fine (you get an empty config). Secrets in the file are redacted in all log output, even at RUST_LOG=trace. Registry tokens, Telegram bot tokens, and SMTP passwords can come from environment variables instead; a webhook or Discord URL stays in the file unless the whole target is declared with FRESHDOCK_NOTIFY_<NAME>_URL.

The file has three top-level tables, all optional: [settings], [registry.*], and [notifications.*]. A key freshdock does not know is a startup error naming the key and its line, so a typo like watch_al cannot silently turn a setting off. The environment layer is more forgiving: an unrecognised FRESHDOCK_* variable is a startup warning naming the variable, and freshdock carries on.

[settings]

Fleet-wide defaults. Every key is optional, and each has an environment variable that overrides it.

[settings]
default_mode   = "watch"   # fallback mode; invalid value falls back to watch
watch_all        = false   # true: every running container counts as enabled unless it opts out
                           # (enable=false, watchtower enable=false, mode=off)
compose_aware    = true    # roll a Compose project out as one unit
one_shot_timeout = 600     # seconds a compose one-shot may run before the rollout gives up
cleanup          = false   # remove the replaced image after a healthy update
prune_dangling   = false   # daemon-wide dangling-image prune after each update (no per-container label)

[registry.<name>]

One table per registry. <name> may be a friendly alias (dockerhub, ghcr, quay, lscr) or a literal host ("registry.example.com"); both fold onto the same registry as the matching image reference. For the four aliases you can skip the file entirely and set FRESHDOCK_REGISTRY_<NAME>_TOKEN (and optionally _USERNAME) instead.

[registry.ghcr]
username = "octocat"          # any non-empty value works for a GHCR PAT
token    = "ghp_xxx"          # personal access token (read:packages for GHCR)

[registry.dockerhub]
username = "myuser"           # required for Docker Hub
token    = "dckr_pat_xxx"

[registry."registry.example.com"]
token    = "..."              # username optional

For per-registry guidance (PAT scopes, the alias list, a smoke test, and what’s out of scope), see registry-auth.md.

[notifications.<name>]

One table per target, selected by type. A target can equally be declared from the environment with FRESHDOCK_NOTIFY_<NAME>_URL; the file form below is for when you’d rather keep it in config. Every target may set an optional triggers list to subscribe to a subset of events; omit it (or use []) to receive all three (available, succeeded, failed). Payload formats and the event/mode matrix are documented in notifications.md.

[notifications.ops-webhook]
type = "webhook"
url  = "https://example.com/hooks/freshdock"
# triggers omitted: all of available, succeeded, failed

[notifications.discord]
type        = "discord"
webhook_url = "https://discord.com/api/webhooks/123/abc"
triggers    = ["succeeded", "failed"]

[notifications.tg]
type      = "telegram"
bot_token = "123456:ABC-DEF"          # or FRESHDOCK_NOTIFY_TG_BOT_TOKEN
chat_id   = "987654321"
triggers  = ["failed"]

[notifications.email]
type     = "smtp"
host     = "smtp.example.com"
port     = 587                        # optional; defaults per tls: 587/465/25
username = "[email protected]"    # username + password together, or neither
password = "s3cr3t"                   # or FRESHDOCK_NOTIFY_EMAIL_PASSWORD
from     = "[email protected]"
to       = ["[email protected]"]      # non-empty list
tls      = "starttls"                 # starttls (default) | implicit (465) | none
triggers = ["succeeded", "failed"]

Per-type keys:

All targets also accept triggers = ["available", "succeeded", "failed"] (subset allowed).

A complete example

File-free (environment only)

A deployment with a private GHCR image, cleanup on, and no notifications needs no file:

FRESHDOCK_DEFAULT_MODE=nightly
FRESHDOCK_CLEANUP=true
FRESHDOCK_REGISTRY_GHCR_USERNAME=octocat
FRESHDOCK_REGISTRY_GHCR_TOKEN=ghp_xxx

(Set these under environment: in compose, Environment= in a systemd unit, or export in a shell.)

With a file (for notifications)

To keep a notification target in the file instead of a FRESHDOCK_NOTIFY_<NAME>_URL, declare it there and keep the secret in the environment:

# freshdock.toml
[settings]
default_mode   = "watch"
cleanup        = true
prune_dangling = false

[registry.ghcr]
username = "octocat"
token    = "ghp_xxx"

[notifications.discord]
type        = "discord"
webhook_url = "https://discord.com/api/webhooks/123/abc"
triggers    = ["succeeded", "failed"]

A copy-paste starting point with every section commented out lives at freshdock.toml.example in the repository root. Runnable compose stacks live in examples/compose/.