Stars
Forks
Watchers
Developer links
Cup
A fast, read-only radar for outdated Docker images. Cup reads the images behind your running Docker or Podman containers, asks each registry whether a newer digest or tag exists, and flags every result as a major, minor, or patch bump, a plain digest change, or up to date. Docker Hub, ghcr.io, Quay, lscr.io, and Gitea-style registries are supported, private ones through token authentication, and checks are designed not to exhaust registry rate limits. The browser dashboard on port 8000 counts monitored, outdated, up-to-date, and unknown images, adds search and filters, and opens any image to show its update type, check time, and a copyable pull command. Prefer automation? Schedule refreshes with a cron expression, trigger one through the API, or run the cup check command from a cronjob for table or JSON output. Rules in cup.json exclude images, ignore registries, and skip chosen update types, even per image. The JSON API feeds Homepage widgets, Home Assistant, and custom dashboards, one dashboard can aggregate several Cup servers, and agent mode serves the API without the interface. Cup only reports, so deciding when to update stays with you. Running on a dedicated VPS on RepoCloud with guaranteed CPU, RAM, and SSD, full root SSH access, and a browser serial console. AGPL-3.0 licensed.
Benefits
- Know What Is Outdated Instantly
- The maintainer measured 58 images checked in 3.7 seconds on a Raspberry Pi 5, so even sizeable home servers get a full update sweep almost instantly.
- No Registry Rate Limit Surprises
- Cup is designed not to exhaust registry rate limits, which matters as Docker Hub tightens unauthenticated pull limits, and it covers Docker Hub, ghcr.io, Quay, lscr.io, and Gitea registries.
- One Dashboard For Every Server
- Add other Cup servers to cup.json and their results merge into a single dashboard, while agent mode exposes only the API on machines that need no interface.
- Updates Stay Entirely Your Decision
- Cup only reports what is outdated and offers a copyable pull command, so nothing restarts unexpectedly; ignore rules silence unwanted major bumps globally or per image.
Features
- Multi-Registry Update Detection
- Compares local image digests and version tags with Docker Hub, ghcr.io, Quay, lscr.io, and Gitea-style registries, classifying results as major, minor, patch, or digest updates.
- Web Dashboard on Port 8000
- The cup serve command hosts a React dashboard with summary counters, search, filters, version badges, a refresh button, light and dark modes, and per-image pull commands.
- JSON API and Refresh
- GET /api/v3/json returns metrics and per-image results for dashboards and webhooks, and GET /api/v3/refresh triggers a fresh check on demand.
- Scheduled Refresh via Cron
- Set refresh_interval to a six-field cron expression, and use the TZ variable so schedules such as daily at 6 AM follow your own timezone.
- Flexible Filtering Rules
- cup.json can exclude or add images, ignore registries, accept insecure registries, and skip major, minor, or patch update types, including per-image overrides.
- Docker, Podman, and Binary
- Run the ghcr.io/sergi0g/cup image with the Docker socket mounted, point it at a Podman socket, or install the standalone binary instead.