ouroboros

Ouroboros

Automatically update your running Docker containers to the latest available image.

Ouroboros will monitor your running Docker containers and update them to the latest available image — similar to Watchtower but with additional features like Prometheus metrics, notifications, and flexible scheduling.

Features

• 🔄 Automatically pull latest images and recreate containers
• 📊 Prometheus metrics endpoint
• 🔔 Notifications via Apprise (Slack, Discord, Email, etc.)
• 🏷️ Monitor specific containers or all running containers
• ⏱️ Configurable polling interval or cron-style scheduling
• 🔒 Support for private registries with authentication
• 📝 Structured logging

Quick Start

Docker Run

docker run -d --name ouroboros \
  -v /var/run/docker.sock:/var/run/docker.sock \
  pyouroboros/ouroboros

Docker Compose

version: '3'
services:
  ouroboros:
    image: pyouroboros/ouroboros
    container_name: ouroboros
    restart: unless-stopped
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock
    environment:
      - CLEANUP=true
      - INTERVAL=600
      - LOG_LEVEL=info
      - SELF_UPDATE=true
      - NOTIFIERS=

Personal note: I changed INTERVAL to 600 (10 minutes) in the example above. The default 5-minute polling felt too aggressive for my home setup and was generating unnecessary registry traffic.

Configuration

Ouroboros can be configured via environment variables or command-line arguments.

Environment Variable	CLI Flag	Default	Description
INTERVAL	--interval	300	Polling interval in seconds
CRON	--cron	None	Cron expression for scheduling
LOG_LEVEL	--log-level	info	Logging level (debug/info/warn/error)
SELF_UPDATE	--self-update	False	Update ouroboros itself
CLEANUP	--cleanup	False	Remove old images after update
MONITOR	--monitor	[]	Containers to monitor (default: all)
IGNORE	--ignore	[]	Containers to ignore
NOTIFIERS	--notifiers	[]	Apprise notification URLs
REPO_USER	--repo-user	None	Registry username
REPO_PASS	--repo-pass	None	Registry password
METRICS_PORT	--metrics-port	8080	Prometheus metrics port

See .env.example for a full list of configuration options.

Metrics

When enabled, Ouroboros exposes a Prometheus metrics endpoint at http://localhost:8080/metrics.

Available metrics:

• containers_updated_total — Total number of container updates
• containers_scanned_total — Total number of containers scanned
• ouroboros_up — Whether Ouroboros is running

Notifications

Ouroboros uses Apprise for notifications. Set the NOTIFIERS envi