Aller au contenu

Pousser votre première image de conteneur

Ce que vous allez apprendre :

  • Comment vous connecter au registre OCI intégré de Repod avec le CLI Docker standard
  • Comment taguer et pousser (push) une petite image
  • Comment confirmer qu'elle est bien arrivée, et la récupérer (pull)

Durée : ~10 minutes Prérequis : Repod démarré en local avec l'overlay du registre OCI activé (docker compose -f docker-compose.yaml -f docker-compose.oci.yml up -d — voir Registre de conteneurs si ce n'est pas encore en place), Docker installé en local, curl, jq

Étape 1 — Pointer Docker vers le registre de Repod

Le registre de Repod (Zot, en interne) écoute sur son propre port, distinct de l'API (8000) et du serveur de dépôt APT/RPM. Dans une installation locale par défaut, c'est le port 5000 (OCI_REGISTRY_PORT dans votre .env, mappé directement sur le conteneur depot-oci).

docker login refuse le simple HTTP par défaut, donc pour des tests en local (pas encore de TLS), indiquez au démon Docker de faire confiance à cet hôte :

/etc/docker/daemon.json
{ "insecure-registries": ["YOUR_HOST:5000"] }

Redémarrez Docker après avoir modifié ce fichier (sudo systemctl restart docker sous Linux, ou redémarrez Docker Desktop). Remplacez YOUR_HOST par localhost si vous exécutez tout sur la même machine.

Vous passez en production ?

Ne déployez jamais insecure-registries sur un vrai environnement. Ajoutez docker-compose.tls.yml et utilisez le port TLS dédié :5443 à la place — voir la section « Déploiement » de Registre de conteneurs.

Connectez-vous maintenant avec votre compte Repod habituel :

docker login YOUR_HOST:5000 -u admin -p YourPassword1!

Sortie attendue : 

Login Succeeded

Sous le capot, le CLI Docker a appelé GET /v2/token sur le backend Repod, qui a validé vos identifiants et renvoyé un token bearer signé à courte durée de vie — le même protocole utilisé par Docker Hub et GHCR. Rien à configurer manuellement.

Étape 2 — Construire une image minuscule

N'importe quelle image fonctionne, mais voici une image minimale pour que ce tutoriel ne dépende de rien d'autre à installer :

Dockerfile
FROM alpine:3.19
CMD ["echo", "Hello from Repod's container registry!"]

mkdir -p ~/hello-repod-oci && cd ~/hello-repod-oci
cat > Dockerfile << 'EOF'
FROM alpine:3.19
CMD ["echo", "Hello from Repod's container registry!"]
EOF

docker build -t hello-repod:1.0.0 .

Étape 3 — Taguer et pousser

docker tag hello-repod:1.0.0 YOUR_HOST:5000/hello-repod:1.0.0
docker push YOUR_HOST:5000/hello-repod:1.0.0

Sortie attendue (les digests seront différents) : 

The push refers to repository [YOUR_HOST:5000/hello-repod]
...
1.0.0: digest: sha256:xxxxxxxx... size: 1234

Le dépôt (hello-repod) n'avait pas besoin d'exister au préalable — il est créé automatiquement au premier push réussi, le même modèle de dépôt dynamique que Repod utilise pour Maven, PyPI et npm.

Comptes SaaS

Sur Repod SaaS, le registre est une adresse unique partagée par toutes les organisations, donc votre nom d'utilisateur de connexion et le nom de votre image portent tous deux le slug de votre organisation (YOUR_ORG_SLUG+YOUR_USERNAME pour la connexion, YOUR_ORG_SLUG/hello-repod pour le nom de l'image). Voir les notes « Comptes SaaS » dans Registre de conteneurs pour la syntaxe exacte. En on-premise/CE, utilisez un nom d'utilisateur et un nom d'image simples comme montré ci-dessus.

Ce push n'est pas scanné immédiatement

Contrairement à un upload .deb/.rpm ou à une image importée (voir ci-dessous), le CLI Docker parle directement au registre — le backend n'est pas dans le chemin des données pour un docker push natif, donc il n'y a pas d'étape ClamAV/CVE synchrone ici. Si votre déploiement a le scan OCI rétroactif activé (settings.json["oci_retroactive_scan"], opt-in), les images poussées nativement sont balayées et scannées selon le calendrier propre à ce job. Si vous voulez voir le pipeline validé complet (antivirus + CVE + politique CVE) s'exécuter de manière synchrone, utilisez l'Importeur du registre plutôt que docker push — c'est exactement ce que fait Parcourir une remédiation de CVE.

Étape 4 — Vérifier qu'elle est bien arrivée

TOKEN=$(curl -s -X POST http://YOUR_HOST:8000/api/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"username":"admin","password":"YourPassword1!"}' \
  | jq -r .access_token)

curl -s -H "Authorization: Bearer $TOKEN" \
  http://YOUR_HOST:8000/api/v1/oci/repositories/hello-repod | jq .

Réponse attendue : 

{
  "name": "hello-repod",
  "tag_count": 1,
  "tags": [
    {
      "tag": "1.0.0",
      "digest": "sha256:xxxxxxxx...",
      "size_bytes": 3400000,
      "created": "2026-08-20T10:00:00Z"
    }
  ]
}

Ou dans l'interface web : Registre de conteneurs, cliquez sur hello-repod.

Étape 5 — Récupérer l'image (pull)

Retirez d'abord votre copie locale, pour être sûr que le pull provient bien de Repod, et non du cache local de Docker :

docker rmi YOUR_HOST:5000/hello-repod:1.0.0 hello-repod:1.0.0

docker pull YOUR_HOST:5000/hello-repod:1.0.0
docker run --rm YOUR_HOST:5000/hello-repod:1.0.0

Sortie attendue : 

Hello from Repod's container registry!

Le pull n'a nécessité aucune connexion : par défaut, tout dépôt est ouvert au pull. Voir « Contrôle d'accès » ci-dessous si vous devez restreindre cela.

Contrôle d'accès (optionnel)

Par défaut, tout nom de dépôt est ouvert au push pour les comptes uploader/maintainer/admin, et ouvert au pull pour tout le monde. Pour restreindre hello-repod à un rôle ou groupe spécifique, utilisez POST /api/v1/oci/repositories/hello-repod/access (admin uniquement) — voir Registre de conteneurs.

Résolution de problèmes

docker login échoue avec 'server gave HTTP response to HTTPS client'

Docker tente du HTTPS contre un registre en simple HTTP. Assurez-vous que insecure-registries dans /etc/docker/daemon.json inclut bien votre host:port exact, et que vous avez redémarré le démon Docker après modification.

docker push échoue avec 'unauthorized: authentication required'

Votre connexion a expiré, ou visait le mauvais hôte/port — les tokens Docker émis par GET /v2/token ont une courte durée de vie (OCI_TOKEN_TTL_SECONDS, 300s par défaut). Relancez docker login juste avant de pousser.

Le push réussit mais le dépôt n'apparaît pas dans GET /oci/repositories

Les noms de dépôts sont filtrés par RBAC selon l'utilisateur — assurez-vous d'interroger avec le même compte (ou un compte admin) que celui qui a effectué le push, et que le rôle du compte n'a pas été restreint après coup par des règles de type distribution_access.

Ce que vous venez de faire

  • Configuré Docker pour faire confiance au registre de Repod pour des tests en local
  • Poussé une image via le protocole standard docker push — aucun outillage spécifique à repod requis
  • Confirmé l'image via l'API et l'interface web
  • Récupéré l'image et l'avez exécutée

Étapes suivantes