---

Why freshdock instead of Watchtower? See the side-by-side comparison.

What it does

freshdock watches your running containers, notices when a newer image is published, and updates them safely: a broken new image rolls back automatically instead of leaving you with a dead service.

freshdock is opt-in: it ignores every container until you set freshdock.enable=true, and an enabled container with no explicit mode defaults to watch (detect and notify, never restart). One narrow exception: inside a Compose project, an unlabelled one-shot that another service waits on is re-run as part of the rollout. An explicit opt-out still wins. See Compose projects. To include every container unless it opts out, see watching every container.

Quickstart

Label a container to opt it in, then watch it with a read-only socket:

# docker-compose.yml
services:
  web:
    image: nginx:1.27
    labels:
      - "freshdock.enable=true"      # opt in; mode defaults to watch

  freshdock:
    image: ghcr.io/turbootzz/freshdock:latest
    command: ["run"]
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
    restart: unless-stopped

freshdock check    # read-only: which containers have updates available?

To let it update something, switch to freshdock.mode=nightly and give the daemon a writable socket. Full walkthrough in the Quickstart.

Install

# crates.io
cargo install freshdock

# container image (multi-arch: amd64, arm64, armv7)
docker run -d --name freshdock --restart unless-stopped \
  -v /var/run/docker.sock:/var/run/docker.sock \
  ghcr.io/turbootzz/freshdock:latest run

Prebuilt static-musl binaries (amd64, arm64, armv7) are attached to each release, with a SHA256SUMS file to verify them (sha256sum -c SHA256SUMS). From source: clone the repo and run just build (binary at target/release/freshdock).

Update modes

Set the mode (and an optional cron override) with labels:

    labels:
      - "freshdock.enable=true"
      - "freshdock.mode=weekly"
      - "freshdock.schedule=0 2 * * 1"   # 02:00 every Monday (overrides the default)

Full label vocabulary and cron syntax: Configuration and Scheduling.

Documentation

Runnable example stacks: examples/compose/. A commented config template: freshdock.toml.example.

Why freshdock

Watchtower was the de-facto Docker auto-updater for years. Its maintainers archived it on 17 December 2025, and it shipped an embedded Docker SDK (API 1.25) incompatible with Docker Engine 29+. The community has forks, but none combine what matters for a small homelab:

1. Modern Docker API: the API version is negotiated with your daemon at connect time via bollard, so freshdock speaks the newest API that daemon supports.
2. Safe updates: a broken new image rolls back automatically instead of leaving a dead container.
3. Small footprint: a single static binary, not a 100+ MB image to manage your other containers.

Compatibility

Socket discovery order, Podman paths, and the Docker API 1.44 floor for containers on more than one network are covered in Deployment.

Status & roadmap

Phases 0-7 are complete and freshdock has been stable since 1.0.0. The full plan and architecture live in the roadmap; release mechanics in RELEASE.md; per-version notes in CHANGELOG.md.

Contributing

Contributions are welcome. See CONTRIBUTING.md for local setup, the quality gates, and dependency hygiene. Security reports: SECURITY.md.

Support

freshdock is free and open source. If it keeps your homelab up to date, you can support its development through GitHub Sponsors. Sponsoring is optional; stars, bug reports, and pull requests help just as much.

License

freshdock is licensed under the Apache License 2.0.

Acknowledgements

• Watchtower for being the standard for ten years and shaping the design space.
• bollard for the Rust Docker SDK that makes any of this possible.