Skip to content

README.md

Latest commit

 

History

History
165 lines (114 loc) · 4.37 KB

README.md

File metadata and controls

165 lines (114 loc) · 4.37 KB

Watchtower

Watchtower Logo

GitHub • Packages

Watchtower automatically updates your running Docker containers when new images are available. Set it and forget it — your containers stay up to date.

Note: This template uses the community-maintained fork by Nicholas Fedor, as the original project has been archived.

Features

  • Automatic Updates — Pulls new images and restarts containers
  • Label-Based Control — Choose which containers to update
  • Notifications — Email, Slack, Teams, and more
  • Cleanup — Removes old images after updates
  • Scheduling — Update on your preferred schedule
  • Private Registries — Support for authenticated registries

Prerequisites

  • Docker and Docker Compose

Quick Start

1. Configure Notifications (Optional)

Edit docker-compose.yml to enable email notifications:

environment:
  - WATCHTOWER_NOTIFICATION_EMAIL_FROM=watchtower@example.com
  - WATCHTOWER_NOTIFICATION_EMAIL_TO=admin@example.com
  - WATCHTOWER_NOTIFICATION_EMAIL_SERVER=smtp.example.com
  - WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT=587
  - WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER=your-user
  - WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD=your-password

2. Deploy

docker compose up -d

Watchtower will now check for updates every 24 hours (default).

Configuration

Environment Variables

Variable Description Default
WATCHTOWER_CLEANUP Remove old images true
WATCHTOWER_INCLUDE_RESTARTING Update restarting containers true
WATCHTOWER_INCLUDE_STOPPED Update stopped containers true
WATCHTOWER_REVIVE_STOPPED Start stopped containers after update true
WATCHTOWER_LABEL_ENABLE Only update labeled containers true
WATCHTOWER_NOTIFICATIONS Notification type email

Update Interval

The --interval flag sets how often Watchtower checks for updates (in seconds):

command: --interval 86400  # 24 hours

Common intervals:

  • 3600 — 1 hour
  • 21600 — 6 hours
  • 86400 — 24 hours (recommended)
  • 604800 — 1 week

Label-Based Updates

This template uses WATCHTOWER_LABEL_ENABLE=true, meaning only containers with the label will be updated.

Add this label to containers you want Watchtower to update:

labels:
  - "com.centurylinklabs.watchtower.enable=true"

All templates in this repository include this label by default.

Notification Options

Email

- WATCHTOWER_NOTIFICATIONS=email
- WATCHTOWER_NOTIFICATION_EMAIL_FROM=watchtower@example.com
- WATCHTOWER_NOTIFICATION_EMAIL_TO=admin@example.com
- WATCHTOWER_NOTIFICATION_EMAIL_SERVER=smtp.example.com
- WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PORT=587
- WATCHTOWER_NOTIFICATION_EMAIL_SERVER_USER=user
- WATCHTOWER_NOTIFICATION_EMAIL_SERVER_PASSWORD=password

Slack

- WATCHTOWER_NOTIFICATIONS=slack
- WATCHTOWER_NOTIFICATION_SLACK_HOOK_URL=https://hooks.slack.com/services/xxx

Discord

- WATCHTOWER_NOTIFICATIONS=shoutrrr
- WATCHTOWER_NOTIFICATION_URL=discord://token@webhookid

Data Persistence

Path Description
/var/run/docker.sock Docker socket (required)
/etc/timezone Host timezone (read-only)

Manual Update Trigger

To manually trigger an update check:

docker exec watchtower /watchtower --run-once

Excluding Containers

To prevent a container from being updated, either:

  1. Don't add the Watchtower label, or
  2. Add the disable label:
labels:
  - "com.centurylinklabs.watchtower.enable=false"

Monitoring Watchtower

Check Watchtower's logs:

docker logs watchtower

Support the Project

License

Watchtower is released under the Apache-2.0 License.