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 downloads over days, weeks and a year, per registry and for the 10 most downloaded packages, both registries combined or apart.
• Lists every package's downloads in the selected period, the packages whose downloads moved most, the latest pushes and the packages nobody pulled.
• Lights a dashboard tile only while something needs you, such as a stopped collector, a registry whose checks keep failing or a count that went down.
• 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/.