β¨ Features
π Automatic Updates
- Image Updates: Automatically detect and pull new Docker images
- Smart Detection: Digest-based comparison for accurate update detection
- Concurrent Processing: Leverages Go's native goroutines for parallel container updates
- Rolling Updates: Update containers gracefully with configurable strategies
- Scheduled Updates: Cron-style scheduling with timezone support
- Auto Cleanup: Remove old images after update (enabled by default)
π₯ Health Monitoring
- Health Checks: Monitor container health status continuously
- Auto-Restart: Automatically restart unhealthy containers (up to 5 attempts)
- Smart Recovery: Stops retry attempts after 5 failures until new image version arrives
- Dependency Awareness: Restart containers in the correct order
π Web Dashboard
- Real-time UI: Beautiful dark-mode dashboard built with Gin, HTMX, and Tailwind CSS
- Live Updates: Stats and container status refresh automatically every 5 seconds
- Container Management: Restart containers directly from the web interface
- Prometheus Metrics: Built-in metrics endpoint for monitoring
π Security First
- Docker Secrets: Native support for Docker secrets (no config.json mounting!)
- Minimal Permissions: Optional socket proxy support for least-privilege access
- Read-Only Mode: Run with read-only root filesystem
- Modern API: Uses latest Docker Engine API
π’ Notifications
- Discord webhooks (with rich embeds)
- Slack webhooks
- Telegram bots
- Gotify, Ntfy
- Generic JSON webhooks
π Observability
- Prometheus metrics endpoint (
/metrics)
- Structured JSON logging
- REST API for integration
- Health check endpoint
π Quick Start
Basic Usage
docker run -d \
--name dockwarden \
--restart unless-stopped \
-v /var/run/docker.sock:/var/run/docker.sock \
emon5122/dockwarden
That's it! DockWarden will:
- Check for updates every 1 minute
- Pull latest images and recreate containers
- Clean up old images automatically
- Monitor container health and restart unhealthy ones (up to 5 times)
- Use Asia/Dhaka timezone by default
With Web Dashboard
docker run -d \
--name dockwarden \
--restart unless-stopped \
-v /var/run/docker.sock:/var/run/docker.sock \
-p 8080:8080 \
-e DOCKWARDEN_API_ENABLED=true \
emon5122/dockwarden
Access the dashboard at http://localhost:8080
With Docker Compose
services:
dockwarden:
image: emon5122/dockwarden:latest
container_name: dockwarden
restart: unless-stopped
ports:
- "8080:8080"
volumes:
- /var/run/docker.sock:/var/run/docker.sock
environment:
- DOCKWARDEN_API_ENABLED=true
- DOCKWARDEN_NOTIFICATION_URL=https://discord.com/api/webhooks/...
- TZ=Asia/Dhaka
With Docker Secrets (Recommended)
services:
dockwarden:
image: emon5122/dockwarden:latest
container_name: dockwarden
restart: unless-stopped
volumes:
- /var/run/docker.sock:/var/run/docker.sock
secrets:
- registry_auth
environment:
- DOCKWARDEN_REGISTRY_SECRET=/run/secrets/registry_auth
secrets:
registry_auth:
file: ./secrets/registry-auth.json
π₯οΈ Web Dashboard
DockWarden includes a beautiful, real-time web dashboard built with modern technologies:
- Gin - High-performance Go web framework
- HTMX - Dynamic updates without writing JavaScript
- Tailwind CSS - Modern, responsive styling
Features:
- π Live container statistics
- π One-click update trigger
- π Restart containers from UI
- π± Responsive design for mobile
- π Dark mode by default
Enable with --api-enabled flag or DOCKWARDEN_API_ENABLED=true environment variable.
π Documentation
βοΈ Configuration
Default Behavior
DockWarden comes with sensible defaults:
| Setting |
Default |
Description |
| Interval |
1 minute |
Time between update checks |
| Cleanup |
true |
Automatically remove old images |
| Health Watch |
true |
Monitor and restart unhealthy containers |
| Max Restart Attempts |
5 |
Give up after 5 restart failures |
| Timezone |
Asia/Dhaka |
Default timezone |
Environment Variables
| Variable |
Default |
Description |
DOCKWARDEN_INTERVAL |
1m |
Check interval (e.g., 1m, 5m, 1h) |
DOCKWARDEN_SCHEDULE |
- |
Cron expression (e.g., 0 0 4 * * *) |
DOCKWARDEN_CLEANUP |
true |
Remove old images after update |
DOCKWARDEN_LABEL_ENABLE |
false |
Only manage labeled containers |
DOCKWARDEN_HEALTH_WATCH |
true |
Enable health monitoring |
DOCKWARDEN_HEALTH_ACTION |
restart |
Action on unhealthy: restart or notify |
DOCKWARDEN_API_ENABLED |
false |
Enable web UI and REST API |
DOCKWARDEN_API_PORT |
8080 |
Web UI and API port |
DOCKWARDEN_METRICS |
false |
Enable Prometheus metrics |
DOCKWARDEN_NOTIFICATION_URL |
- |
Discord/Slack/Telegram webhook URL |
DOCKWARDEN_LOG_LEVEL |
info |
Log level (debug/info/warn/error) |
TZ |
Asia/Dhaka |
Timezone |
Container Labels
labels:
- "dockwarden.enable=true"
- "dockwarden.update.enable=true"
- "dockwarden.watch.enable=true"
- "dockwarden.stop-signal=SIGTERM"
- "dockwarden.stop-timeout=30"
- "dockwarden.scope=production"
See full configuration documentation for all options.
π’ Notifications
DockWarden supports multiple notification providers:
Discord
DOCKWARDEN_NOTIFICATION_URL=https://discord.com/api/webhooks/xxx/yyy
Sends rich embeds with container info, update status, and health alerts.
Slack
DOCKWARDEN_NOTIFICATION_URL=https://hooks.slack.com/services/xxx/yyy/zzz
Telegram
DOCKWARDEN_NOTIFICATION_URL=telegram://BOT_TOKEN@telegram?chats=CHAT_ID
Generic Webhook
Any URL will receive a JSON payload:
{
"source": "dockwarden",
"type": "container_updated",
"message": "Container nginx has been updated",
"container_name": "nginx",
"image": "nginx:latest",
"timestamp": "2026-01-31T14:30:00Z"
}
π Security Best Practices
Using Docker Socket Proxy
For enhanced security, use a socket proxy to limit DockWarden's access:
services:
dockwarden:
image: emon5122/dockwarden:latest
environment:
- DOCKER_HOST=tcp://socket-proxy:2375
depends_on:
- socket-proxy
socket-proxy:
image: tecnativa/docker-socket-proxy
privileged: true
environment:
- CONTAINERS=1
- IMAGES=1
- POST=1
volumes:
- /var/run/docker.sock:/var/run/docker.sock:ro
Using Docker Secrets Instead of config.json
β Old way (Watchtower):
volumes:
- /root/.docker/config.json:/config.json # Exposes credentials!
β
New way (DockWarden):
secrets:
- registry_auth
environment:
- DOCKWARDEN_REGISTRY_SECRET=/run/secrets/registry_auth
π Prometheus Metrics
Enable metrics with DOCKWARDEN_METRICS=true:
Available metrics:
dockwarden_containers_total - Total number of containers
dockwarden_containers_running - Running containers
dockwarden_containers_unhealthy - Unhealthy containers
dockwarden_updates_total - Total updates performed
dockwarden_update_failures_total - Failed updates
dockwarden_restarts_total - Health-triggered restarts
dockwarden_check_duration_seconds - Check duration
π Migrating from Watchtower
DockWarden is designed as a drop-in replacement:
# Replace this:
image: containrrr/watchtower
# With this:
image: emon5122/dockwarden:latest
Key differences:
- Default interval is 1 minute (not 5 minutes)
- Cleanup is enabled by default
- Health monitoring is built-in
- Web UI available with
--api-enabled
- Default timezone is Asia/Dhaka
Environment variable mapping:
WATCHTOWER_CLEANUP β DOCKWARDEN_CLEANUP
WATCHTOWER_SCHEDULE β DOCKWARDEN_SCHEDULE
WATCHTOWER_POLL_INTERVAL β DOCKWARDEN_INTERVAL
WATCHTOWER_LABEL_ENABLE β DOCKWARDEN_LABEL_ENABLE
See the Migration Guide for detailed instructions.
ποΈ Building from Source
# Clone the repository
git clone https://github.com/emon5122/dockwarden.git
cd dockwarden
# Build
go build -o dockwarden ./cmd/dockwarden
# Build Docker image
docker build -t emon5122/dockwarden:local -f build/Dockerfile .
π€ Contributing
Contributions are welcome! Please see our Contributing Guide for details.
- Fork the repository
- Create a feature branch (
git checkout -b feature/amazing-feature)
- Commit your changes (
git commit -m 'Add amazing feature')
- Push to the branch (
git push origin feature/amazing-feature)
- Open a Pull Request
π License
This project is licensed under the MIT License - see the LICENSE file for details.
π Acknowledgments
DockWarden builds upon the excellent work of:
Special thanks to all contributors of these projects!