🐳 Docker Registry API

A lightweight Go API that queries container registries (Docker Hub, GHCR, etc.) to expose raw Docker/OCI registry data. Acts as a proxy so your client application can handle caching, version parsing, and business logic.

---

Quick Start

Using Docker Compose (recommended)

services:
  registry-api:
    image: ghcr.io/slimani-dev/registry-api:main
    container_name: registry-api
    restart: unless-stopped
    ports:
      - "8080:8080"
    environment:
      - REDIS_ADDR=redis:6379
    depends_on:
      redis:
        condition: service_healthy

  redis:
    image: redis:alpine
    container_name: registry-api-redis
    restart: unless-stopped
    volumes:
      - redis-data:/data
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]
      interval: 5s
      timeout: 3s
      retries: 3

volumes:
  redis-data:

docker compose up -d

The API will be available at http://localhost:8080.

For Private Registries

Mount your Docker config to allow pulling from authenticated registries:

services:
  registry-api:
    volumes:
      - ~/.docker/config.json:/root/.docker/config.json:ro

Building from Source

git clone https://github.com/slimani-dev/registry-api.git
cd registry-api
docker compose up -d --build

---

Endpoints

1. GET /tags — List Tags

Lists all available tags for a given repository.

curl "http://localhost:8080/tags?image=ghcr.io/immich-app/immich-server"

{
    "image": "ghcr.io/immich-app/immich-server",
    "tags": ["latest", "v1.104.0", "v1.103.1"]
}

---

2. GET /digest — Get Exact Digest

Fast HEAD request to get the manifest digest.

curl "http://localhost:8080/digest?image=ghcr.io/immich-app/immich-server&reference=v1.104.0"

{
    "image": "ghcr.io/immich-app/immich-server",
    "reference": "v1.104.0",
    "digest": "sha256:e6a6298e..."
}

---

3. GET /config — Image Configuration

Returns Env, Cmd, Labels, ExposedPorts, etc.

curl "http://localhost:8080/config?image=ghcr.io/immich-app/immich-server&reference=latest"

---

4. GET /manifest — Raw Manifest

Returns the raw OCI/Docker manifest with layer sizes.

curl "http://localhost:8080/manifest?image=ghcr.io/immich-app/immich-server&reference=v1.104.0"

---

5. GET /index — Multi-Architecture Index

Returns the multi-arch manifest list. Returns 404 if single-architecture.

curl "http://localhost:8080/index?image=ghcr.io/immich-app/immich-server&reference=latest"

---

6. GET /latest — Expanded Helper

Finds newest tag, fetches digest, and pulls summary metadata.

curl "http://localhost:8080/latest?image=ghcr.io/immich-app/immich-server"

---

7. GET /health — Health Check

curl "http://localhost:8080/health"

{ "status": "ok", "redis": "connected" }

---

Smart Caching

The API uses Redis to automatically learn which images are slow and adapts its behavior:

How it works:

1. Every request is fetched from the registry and timed
2. If a request takes longer than 10 seconds, the image is flagged as "slow"
3. Future requests for slow images return cached data instantly and trigger a silent background refresh
4. Fast images are never served from cache — always fresh

Cached responses include X-From-Cache: true header so your client knows.

---

Architecture

┌─────────────┐     ┌──────────────────┐     ┌───────────────┐
│   Client     │────▶│  Registry API    │────▶│  Redis Cache  │
│  (PHP/curl)  │◀────│  (Go, port 8080) │◀────│  (alpine)     │
└─────────────┘     └──────────────────┘     └───────────────┘
                            │
                            ▼
                    ┌──────────────────┐
                    │  GHCR / Docker   │
                    │  Hub / Quay.io   │
                    └──────────────────┘

Environment Variables