cplieger/registry-stats repository overview

⁠registry-stats

registry-stats graphs the pull counts that Docker Hub and GitHub Container Registry report for your public images, on a ready-made Grafana dashboard. Your Prometheus server scrapes the current counts and keeps the history, so the graphs begin on the day you start registry-stats.

⁠What it does

registry-stats helps you follow the pull counts of your published images over time:

• Graphs each package's downloads over days, weeks and a year, both registries combined or apart.
• Lists packages missing from a registry, latest pushes and tag counts.
• Picks up an owner's public images with owner/* on every check, new ones included, up to 198 Docker Hub repositories or 50 GHCR listing pages per owner.
• Ships alert rules for a stopped collector, a failing registry and a pull count that drops.

⁠Who it is for

registry-stats is built for people who publish public container images. It checks the registries every hour by default and needs no registry login.

Its graphs and five alerts come from your Prometheus-compatible server, such as Prometheus or Mimir, with Grafana and Alertmanager, and three from Loki. The monitoring guide⁠ sets them up. registry-stats reads public images only. Keep its port on your own network, because the metrics endpoint has no login.

One other project suits a different need. Consider ghcr-badge⁠ if you only want a README badge with a GHCR package's download count. It is an API service that returns the count as JSON and as a shields.io badge.

registry-stats is free software under the GPL-3.0-or-later license.

⁠Pull

docker pull cplieger/registry-stats:latest

Also published to ghcr.io/cplieger/registry-stats with identical images and tags. Release versions are tagged vX.Y.Z alongside latest.

⁠Quick start

# Example compose for registry-stats. See the README for all configuration options and hardening.
services:
  registry-stats:
    image: ghcr.io/cplieger/registry-stats:latest
    container_name: registry-stats
    restart: unless-stopped

    environment:
      # Set at least one of the two lists before the first start, or the container turns unhealthy after its first check.
      DOCKERHUB_REPOS: ""  # owner/repo or owner/*, comma-separated
      GHCR_REPOS: ""  # owner/package or owner/*, comma-separated
      POLL_INTERVAL_HOURS: "1"  # 0 = check once, then keep serving the counts

    ports:
      # The metrics endpoint has no login, so this example publishes it to this host only.
      # For a collector on another host, publish it on a trusted address such as "192.0.2.10:9100:9100", never "9100:9100".
      - "127.0.0.1:9100:9100"

⁠Documentation

• Full documentation⁠ — configuration, behavior, security
• Configuration⁠
• Security⁠
• How registry-stats works⁠
• Monitoring and alerts⁠
• Contributing⁠
• Releases and changelog⁠

⁠License

GPL-3.0-or-later. See LICENSE⁠. The image carries the license text of every bundled component under /usr/share/licenses/.