Distribution : déployer une registry privée on-premise (ex Docker Registry)

Vous voulez héberger vos images Docker en interne sans dépendre de Docker Hub ou Quay.io ? Distribution (anciennement Docker Registry v2) est le projet CNCF officiel pour créer une registry privée on-premise. Léger, stateless et compatible OCI, il se déploie en quelques minutes avec Docker Compose.

Ce que vous allez apprendre

Ce guide couvre le déploiement complet d’une registry privée, de l’installation basique jusqu’à la configuration production avec TLS et authentification.

• Déployer une registry avec Docker ou Docker Compose
• Configurer TLS avec Let’s Encrypt ou certificats auto-signés
• Ajouter l’authentification htpasswd ou token
• Configurer le stockage : filesystem, S3, Azure, GCS
• Exécuter le garbage collection pour libérer l’espace disque
• Intégrer avec Kubernetes et vos pipelines CI/CD

Prérequis

Comprendre les registries de conteneurs Vocabulaire, fonctionnement de docker pull/push, standards OCI

Docker : installation et premiers pas Installer Docker Engine sur votre serveur

Qu’est-ce que Distribution ?

Distribution est le projet open source officiel de la CNCF (Cloud Native Computing Foundation) pour implémenter une registry de conteneurs. C’est le même code qui propulse Docker Hub, GitHub Container Registry et de nombreuses registries cloud.

Un peu d’histoire

Le projet a connu plusieurs noms au fil du temps, ce qui peut prêter à confusion :

Période	Nom	Notes
2013-2015	Docker Registry v1	Format propriétaire, abandonné
2015-2020	Docker Registry v2	Nouveau format, base du standard OCI
2020-présent	CNCF Distribution	Projet transféré à la CNCF, image registry:2
2024-présent	Distribution 3.0	Version majeure avec support OCI natif amélioré

Glissez pour voir

Quelle version utiliser ?

L’image Docker s’appelle toujours registry:2 (ou registry:3 pour la v3). Le projet GitHub est distribution/distribution. Dans ce guide, nous utilisons Distribution 2.8+ (stable) avec des notes pour la v3 quand pertinent.

Distribution vs alternatives

Quand utiliser Distribution plutôt qu’une solution plus complète comme Harbor ?

Critère	Distribution	Harbor	Quay (self-hosted)
Complexité	Très simple	Moyenne	Élevée
Ressources	~50 MB RAM	~2 GB RAM	~4 GB RAM
Interface web	❌ Non	✅ Oui	✅ Oui
Scan de sécurité	❌ Non	✅ Trivy/Clair	✅ Clair
RBAC avancé	❌ Non	✅ Oui	✅ Oui
Réplication	❌ Non	✅ Oui	✅ Oui
Cas d’usage	Dev, CI/CD, petit cluster	Entreprise	Entreprise Red Hat

Glissez pour voir

En résumé : Distribution est idéal pour les environnements où vous avez besoin d’une registry simple, rapide à déployer, sans interface graphique ni fonctionnalités avancées. Pour la production enterprise, préférez Harbor.

Déployer une registry basique

Commençons par le déploiement le plus simple : une registry locale sans authentification ni TLS. Parfait pour le développement ou les tests.

Avec Docker (une commande)

# Lancer une registry sur le port 5000
docker run -d \
  --name registry \
  --restart always \
  -p 5000:5000 \
  -v registry-data:/var/lib/registry \
  registry:2

# Vérifier que la registry fonctionne
curl http://localhost:5000/v2/
# Résultat attendu : {}

Tester avec une image

# Taguer une image existante pour la registry locale
docker pull alpine:3.19
docker tag alpine:3.19 localhost:5000/alpine:3.19

# Pousser vers la registry
docker push localhost:5000/alpine:3.19

# Vérifier la présence
curl http://localhost:5000/v2/_catalog
# {"repositories":["alpine"]}

# Supprimer l'image locale et la retirer
docker rmi localhost:5000/alpine:3.19
docker pull localhost:5000/alpine:3.19

Localhost uniquement

Cette configuration ne fonctionne que depuis la machine locale. Docker refuse de pousser vers une registry HTTP distante (non sécurisée). Pour un accès réseau, vous devez configurer TLS ou déclarer la registry comme “insecure” (non recommandé en production).

Déployer avec Docker Compose (production)

Pour un déploiement plus robuste avec TLS et authentification, utilisez Docker Compose avec un fichier de configuration dédié.

Structure des fichiers

registry/
├── docker-compose.yml
├── config.yml
├── auth/
│   └── htpasswd
└── certs/
    ├── domain.crt
    └── domain.key

Configuration de la registry

Créez config.yml avec les paramètres de votre registry :

version: 0.1
log:
  level: info
  formatter: text
  fields:
    service: registry

storage:
  filesystem:
    rootdirectory: /var/lib/registry
  delete:
    enabled: true
  cache:
    blobdescriptor: inmemory

http:
  addr: :5000
  headers:
    X-Content-Type-Options: [nosniff]
  tls:
    certificate: /certs/domain.crt
    key: /certs/domain.key

auth:
  htpasswd:
    realm: Registry Realm
    path: /auth/htpasswd

health:
  storagedriver:
    enabled: true
    interval: 10s
    threshold: 3

Docker Compose

Créez docker-compose.yml :

services:
  registry:
    image: registry:2.8
    container_name: registry
    restart: always
    ports:
      - "5000:5000"
    environment:
      REGISTRY_STORAGE_DELETE_ENABLED: "true"
    volumes:
      - ./config.yml:/etc/docker/registry/config.yml:ro
      - ./auth:/auth:ro
      - ./certs:/certs:ro
      - registry-data:/var/lib/registry

volumes:
  registry-data:

Configurer TLS

Une registry de production doit être protégée par TLS. Docker refuse par défaut de communiquer avec une registry HTTP non sécurisée (sauf localhost).

Option 1 : Let’s Encrypt avec Traefik

La solution la plus simple pour obtenir un certificat valide automatiquement. Traefik gère le renouvellement et le reverse proxy.

services:
  traefik:
    image: traefik:v3.0
    command:
      - "--api.insecure=true"
      - "--providers.docker=true"
      - "--entrypoints.websecure.address=:443"
      - "--certificatesresolvers.letsencrypt.acme.tlschallenge=true"
      - "--certificatesresolvers.letsencrypt.acme.email=admin@example.com"
      - "--certificatesresolvers.letsencrypt.acme.storage=/letsencrypt/acme.json"
    ports:
      - "443:443"
    volumes:
      - /var/run/docker.sock:/var/run/docker.sock:ro
      - letsencrypt:/letsencrypt

  registry:
    image: registry:2.8
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.registry.rule=Host(`registry.example.com`)"
      - "traefik.http.routers.registry.entrypoints=websecure"
      - "traefik.http.routers.registry.tls.certresolver=letsencrypt"
    volumes:
      - registry-data:/var/lib/registry

volumes:
  registry-data:
  letsencrypt:

Option 2 : Certificat auto-signé

Pour les environnements internes sans accès Internet, générez un certificat auto-signé. Les clients devront faire confiance à ce certificat.

1. Générer le certificat

   # Créer le répertoire des certificats
   mkdir -p certs
   
   # Générer une clé privée et un certificat (valide 365 jours)
   openssl req -x509 -nodes -days 365 -newkey rsa:4096 \
     -keyout certs/domain.key \
     -out certs/domain.crt \
     -subj "/CN=registry.local" \
     -addext "subjectAltName=DNS:registry.local,DNS:localhost,IP:192.168.1.100"

2. Configurer Docker pour faire confiance au certificat

   Sur chaque machine cliente :

   # Créer le répertoire de certificats pour la registry
   sudo mkdir -p /etc/docker/certs.d/registry.local:5000
   
   # Copier le certificat
   sudo cp certs/domain.crt /etc/docker/certs.d/registry.local:5000/ca.crt
   
   # Redémarrer Docker
   sudo systemctl restart docker

3. Tester la connexion

   docker login registry.local:5000
   # Username: admin
   # Password: ********
   # Login Succeeded

Alternative : registry insecure

Pour le développement uniquement, vous pouvez déclarer la registry comme “insecure” dans /etc/docker/daemon.json :

{
  "insecure-registries": ["registry.local:5000"]
}

Ne jamais utiliser en production — les credentials transitent en clair.

Configurer l’authentification

Distribution supporte plusieurs méthodes d’authentification. La plus simple est htpasswd, suffisante pour la plupart des cas d’usage.

Authentification htpasswd

L’authentification htpasswd utilise un fichier de mots de passe hashés, comme Apache. Simple à mettre en place, mais sans gestion fine des permissions (tout ou rien).

1. Créer le fichier htpasswd

   # Créer le répertoire auth
   mkdir -p auth
   
   # Créer le premier utilisateur (bcrypt)
   docker run --rm --entrypoint htpasswd \
     httpd:2-alpine -Bbn admin motdepasse_securise > auth/htpasswd
   
   # Ajouter d'autres utilisateurs
   docker run --rm --entrypoint htpasswd \
     httpd:2-alpine -Bbn ci_user autre_motdepasse >> auth/htpasswd

2. Configurer la registry

   Dans config.yml :

   auth:
     htpasswd:
       realm: Registry Realm
       path: /auth/htpasswd

3. Tester l’authentification

   # Sans auth : erreur 401
   curl https://registry.local:5000/v2/
   # {"errors":[{"code":"UNAUTHORIZED",...}]}
   
   # Avec auth : succès
   curl -u admin:motdepasse_securise https://registry.local:5000/v2/
   # {}

Authentification par token (avancé)

Pour une gestion plus fine des permissions (lecture seule, écriture, par repository), utilisez un serveur d’authentification externe compatible avec le protocole Docker Registry Token.

Des projets comme Cesanta Docker Auth ou Portus implémentent ce protocole et permettent de définir des ACL granulaires.

Configurer le stockage

Par défaut, Distribution stocke les images sur le filesystem local. Pour la production, vous pouvez utiliser un stockage objet (S3, GCS, Azure Blob).

Stockage filesystem (défaut)

Configuration simple pour un serveur unique. Le stockage est dans un volume Docker ou un répertoire local.

storage:
  filesystem:
    rootdirectory: /var/lib/registry
  delete:
    enabled: true

Stockage S3 (AWS ou compatible)

Pour la haute disponibilité et la scalabilité, utilisez un stockage objet S3. Compatible avec MinIO, Ceph, Wasabi et tout service S3-compatible.

storage:
  s3:
    accesskey: AKIAIOSFODNN7EXAMPLE
    secretkey: wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY
    region: eu-west-1
    bucket: my-registry-bucket
    rootdirectory: /registry
    encrypt: true
    secure: true
    v4auth: true
  delete:
    enabled: true
  cache:
    blobdescriptor: inmemory

Credentials S3

Ne mettez jamais les credentials S3 en dur dans le fichier de configuration en production. Utilisez des variables d’environnement ou un gestionnaire de secrets :

storage:
  s3:
    accesskey: ${AWS_ACCESS_KEY_ID}
    secretkey: ${AWS_SECRET_ACCESS_KEY}

Stockage Azure Blob

storage:
  azure:
    accountname: myaccount
    accountkey: ${AZURE_STORAGE_KEY}
    container: registry
    realm: core.windows.net

Stockage Google Cloud Storage

storage:
  gcs:
    bucket: my-registry-bucket
    keyfile: /path/to/keyfile.json
    rootdirectory: /registry

Garbage Collection

Les images Docker sont composées de layers (blobs) partagés entre images. Quand vous supprimez un tag, les blobs ne sont pas automatiquement supprimés — ils peuvent encore être référencés par d’autres images.

Le garbage collection (GC) identifie et supprime les blobs orphelins pour récupérer l’espace disque.

Supprimer un tag

Avant le GC, vous devez supprimer les tags que vous ne voulez plus conserver.

# Lister les tags d'une image
curl -u admin:password https://registry.local:5000/v2/myapp/tags/list

# Récupérer le digest d'un tag
DIGEST=$(curl -s -u admin:password \
  -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
  https://registry.local:5000/v2/myapp/manifests/v1.0.0 \
  -I | grep -i docker-content-digest | awk '{print $2}' | tr -d '\r')

# Supprimer le manifest (soft delete)
curl -u admin:password -X DELETE \
  https://registry.local:5000/v2/myapp/manifests/$DIGEST

Exécuter le garbage collection

Le GC doit être exécuté registry arrêtée ou en mode read-only pour éviter les corruptions.

# Arrêter la registry
docker stop registry

# Dry-run : voir ce qui serait supprimé
docker run --rm \
  -v registry-data:/var/lib/registry \
  -v $(pwd)/config.yml:/etc/docker/registry/config.yml \
  registry:2 garbage-collect --dry-run /etc/docker/registry/config.yml

# Exécution réelle
docker run --rm \
  -v registry-data:/var/lib/registry \
  -v $(pwd)/config.yml:/etc/docker/registry/config.yml \
  registry:2 garbage-collect /etc/docker/registry/config.yml

# Redémarrer la registry
docker start registry

GC automatique

Planifiez le GC régulièrement avec un cron job, par exemple chaque nuit :

0 3 * * * /usr/local/bin/registry-gc.sh >> /var/log/registry-gc.log 2>&1

Intégration Kubernetes

Pour utiliser votre registry privée avec Kubernetes, créez un Secret de type docker-registry et référencez-le dans vos Pods.

Créer le Secret

kubectl create secret docker-registry registry-credentials \
  --docker-server=registry.local:5000 \
  --docker-username=admin \
  --docker-password=motdepasse_securise \
  --docker-email=admin@example.com \
  -n default

Utiliser dans un Pod

apiVersion: v1
kind: Pod
metadata:
  name: myapp
spec:
  containers:
    - name: app
      image: registry.local:5000/myapp:v1.0.0
  imagePullSecrets:
    - name: registry-credentials

Configurer containerd pour TLS

Si vous utilisez un certificat auto-signé, configurez containerd sur chaque nœud Kubernetes pour faire confiance à votre registry.

# Créer le répertoire de configuration
sudo mkdir -p /etc/containerd/certs.d/registry.local:5000

# Créer hosts.toml
cat << 'EOF' | sudo tee /etc/containerd/certs.d/registry.local:5000/hosts.toml
server = "https://registry.local:5000"

[host."https://registry.local:5000"]
  capabilities = ["pull", "resolve", "push"]
  ca = "/etc/containerd/certs.d/registry.local:5000/ca.crt"
EOF

# Copier le certificat CA
sudo cp domain.crt /etc/containerd/certs.d/registry.local:5000/ca.crt

# Redémarrer containerd
sudo systemctl restart containerd

Automatiser avec GitHub Actions

Voici un workflow pour pousser vos images vers votre registry privée depuis GitHub Actions.

Pourquoi piner les actions par SHA ?

Les tags comme @v4 peuvent être déplacés par le mainteneur de l’action. En pinant par SHA, vous utilisez une version immuable — le code ne peut pas changer sans que le SHA change.

Configurer les secrets GitHub

Créez des secrets pour l’authentification à votre registry privée :

Secret	Valeur
REGISTRY_URL	registry.example.com:5000
REGISTRY_USERNAME	ci_user
REGISTRY_PASSWORD	Mot de passe htpasswd

Glissez pour voir

Workflow GitHub Actions

name: Build and Push to Private Registry

on:
  push:
    branches: [main]
    tags: ['v*']

env:
  IMAGE_NAME: myapp

jobs:
  build-and-push:
    runs-on: ubuntu-latest

    steps:
      - name: Checkout code
        uses: actions/checkout@11bd71901bbe5b1630ceea73d27597364c9af683 # v4.2.2

      - name: Set up Docker Buildx
        uses: docker/setup-buildx-action@988b5a0280414f521da01fcc63a27aeeb4b104db # v3.6.1

      - name: Login to Private Registry
        uses: docker/login-action@9780b0c442fbb1117ed29e0efdff1e18412f7567 # v3.3.0
        with:
          registry: ${{ secrets.REGISTRY_URL }}
          username: ${{ secrets.REGISTRY_USERNAME }}
          password: ${{ secrets.REGISTRY_PASSWORD }}

      - name: Extract metadata
        id: meta
        uses: docker/metadata-action@8e5442c4ef9f78752691e2d8f8d19755c6f78e81 # v5.5.1
        with:
          images: ${{ secrets.REGISTRY_URL }}/${{ env.IMAGE_NAME }}
          tags: |
            type=ref,event=branch
            type=semver,pattern={{version}}
            type=sha,prefix=

      - name: Build and push
        uses: docker/build-push-action@263435318d21b8e681c14492fe198d362a7d2c83 # v6.18.0
        with:
          context: .
          push: true
          tags: ${{ steps.meta.outputs.tags }}
          labels: ${{ steps.meta.outputs.labels }}

API REST de la registry

Distribution expose une API REST standard (OCI Distribution Spec) pour interagir programmatiquement avec la registry.

Endpoints principaux

Endpoint	Méthode	Description
/v2/	GET	Vérifier que la registry fonctionne
/v2/_catalog	GET	Lister tous les repositories
/v2/{name}/tags/list	GET	Lister les tags d’une image
/v2/{name}/manifests/{ref}	GET	Récupérer un manifest
/v2/{name}/manifests/{ref}	DELETE	Supprimer un manifest
/v2/{name}/blobs/{digest}	GET	Télécharger un blob

Glissez pour voir

Exemples d’utilisation

# Lister tous les repositories
curl -u admin:password https://registry.local:5000/v2/_catalog
# {"repositories":["alpine","myapp","nginx"]}

# Lister les tags d'une image
curl -u admin:password https://registry.local:5000/v2/myapp/tags/list
# {"name":"myapp","tags":["v1.0.0","v1.1.0","latest"]}

# Récupérer le manifest d'un tag
curl -u admin:password \
  -H "Accept: application/vnd.docker.distribution.manifest.v2+json" \
  https://registry.local:5000/v2/myapp/manifests/v1.0.0

Dépannage

Voici les erreurs les plus fréquentes lors du déploiement d’une registry Distribution et leurs solutions.

Symptôme	Cause probable	Solution
http: server gave HTTP response to HTTPS client	Registry non TLS	Configurer TLS ou ajouter à insecure-registries
x509: certificate signed by unknown authority	Certificat auto-signé non reconnu	Copier le CA dans /etc/docker/certs.d/
unauthorized: authentication required	Credentials incorrects	Vérifier htpasswd et docker login
manifest unknown	Tag inexistant	Vérifier le nom exact avec l’API /tags/list
denied: requested access is denied	Permissions insuffisantes	Vérifier la config auth dans config.yml
Espace disque plein	Blobs orphelins	Exécuter le garbage collection

Glissez pour voir

À retenir

1. Distribution est la registry officielle CNCF, le même code qui propulse Docker Hub. Simple, léger (~50 MB RAM), idéal pour le dev et les petits clusters.

2. TLS est obligatoire pour un accès réseau. Utilisez Let’s Encrypt avec Traefik ou des certificats auto-signés avec configuration des clients.

3. L’authentification htpasswd suffit pour la plupart des cas. Pour du RBAC avancé, passez à Harbor ou utilisez un serveur de tokens externe.

4. Le garbage collection libère l’espace des blobs orphelins. Planifiez-le régulièrement, registry arrêtée ou en read-only.

5. Pour la production enterprise, préférez Harbor : interface web, scan de sécurité, réplication, RBAC. Distribution reste excellent comme registry cache ou pour le dev.

Prochaines étapes

Harbor : registry enterprise Interface web, scan Trivy, RBAC et réplication

Docker Hub : registry publique La registry cloud la plus utilisée

Quay.io : registry Red Hat Alternative avec scan Clair intégré

Trivy : scanner de vulnérabilités Scanner vos images avant déploiement

×

📖 Voir la documentation →