Ejecutar tu propia Docker Registry

Qué cubre este artículo sobre Docker Registry

• Qué es una Docker Registry y cuándo vale la pena tener la propia.
• Cómo ejecutar la Registry oficial de Docker.
• Cómo hacer push y pull de imágenes.
• Autenticación, TLS y seguridad.
• Consejos para backups y mantenimiento.

Introducción: ejecutar tu propia Docker Registry

Una Docker Registry es un repositorio de almacenamiento para imágenes Docker. Por defecto, las imágenes provienen de Docker Hub, pero a veces necesitas distribuir imágenes personalizadas de forma local o dentro de tu red corporativa. Una Registry propia resulta útil para CI/CD, entornos aislados, privacidad de datos o cuando Docker Hub no debe estar disponible.

Este artículo te muestra cómo ejecutar la Registry oficial de Docker en local o en tu homelab.

Conceptos clave

• Registry: almacenamiento de imágenes Docker.
• Repository: colección de imágenes bajo un mismo nombre.
• Tag: identificador de versión de una imagen.
• Push: subida de una imagen a la Registry.
• Pull: descarga de una imagen desde la Registry.
• TLS: cifrado de la conexión.
• Basic Auth: usuario y contraseña para el acceso.
• Garbage Collection: limpieza de capas no referenciadas.

Cuándo tiene sentido una Registry propia

• Distribuir imágenes personalizadas dentro de la red interna.
• Acelerar pipelines de CI/CD.
• Eludir las limitaciones de Docker Hub.
• Evitar almacenar datos en registries públicas.
• Abastecer entornos aislados (air-gapped).
• Compartir caché de construcción entre hosts.

Iniciar la Registry

La Registry oficial se ejecuta como un contenedor simple:

docker run -d -p 5000:5000 --name registry registry:2

Prueba:

curl http://localhost:5000/v2/_catalog

Etiquetar e subir una imagen

Renombra una imagen existente y súbela:

docker tag mein-image:latest localhost:5000/mein-image:latest
docker push localhost:5000/mein-image:latest

Descargar una imagen

docker pull localhost:5000/mein-image:latest

Persistencia con volúmenes

docker run -d -p 5000:5000 --name registry \
  -v registry-data:/var/lib/registry \
  registry:2

Activar TLS

Para producción o acceso remoto, la Registry debe estar protegida con TLS. Puedes usar un certificado de una CA o un certificado autofirmado.

Certificado autofirmado

mkdir -p certs
openssl req -newkey rsa:4096 -nodes -sha256 -keyout certs/registry.key -x509 -days 365 -out certs/registry.crt

Registry con certificado:

docker run -d -p 5000:5000 --name registry \
  -v $(pwd)/certs:/certs \
  -v registry-data:/var/lib/registry \
  -e REGISTRY_HTTP_TLS_CERTIFICATE=/certs/registry.crt \
  -e REGISTRY_HTTP_TLS_KEY=/certs/registry.key \
  registry:2

En el cliente, el certificado debe ser aceptado:

mkdir -p /etc/docker/certs.d/localhost:5000
cp registry.crt /etc/docker/certs.d/localhost:5000/ca.crt

Autenticación

Una autenticación Basic Auth sencilla con htpasswd:

mkdir auth
docker run --rm --entrypoint htpasswd httpd:2 -Bbn admin meinpasswort > auth/htpasswd

Registry con autenticación:

docker run -d -p 5000:5000 --name registry \
  -v $(pwd)/auth:/auth \
  -e REGISTRY_AUTH=htpasswd \
  -e REGISTRY_AUTH_HTPASSWD_REALM="Registry Realm" \
  -e REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd \
  -v registry-data:/var/lib/registry \
  registry:2

Inicia sesión:

docker login localhost:5000

Registry con Compose

services:
  registry:
    image: registry:2
    container_name: registry
    ports:
      - "127.0.0.1:5000:5000"
    volumes:
      - registry-data:/var/lib/registry
      - ./certs:/certs
      - ./auth:/auth
    environment:
      - REGISTRY_HTTP_TLS_CERTIFICATE=/certs/registry.crt
      - REGISTRY_HTTP_TLS_KEY=/certs/registry.key
      - REGISTRY_AUTH=htpasswd
      - REGISTRY_AUTH_HTPASSWD_REALM=Registry Realm
      - REGISTRY_AUTH_HTPASSWD_PATH=/auth/htpasswd
    restart: unless-stopped

volumes:
  registry-data:

Garbage Collection

Las capas no referenciadas pueden ocupar espacio en disco. Ejecuta una limpieza:

docker exec registry bin/registry garbage-collect /etc/docker/registry/config.yml

Backup

Los datos de la Registry se encuentran en /var/lib/registry. Un backup simple:

docker run --rm -v registry-data:/data -v $(pwd):/backup alpine tar -czf /backup/registry-backup.tar.gz -C /data .

Seguridad

• Usa siempre TLS para acceso remoto.
• Activa autenticación.
• Nunca expongas la Registry públicamente en internet.
• Limita el acceso mediante VPN o Tailscale.
• Aplica backups y actualizaciones de forma regular.
• Habilita logging.

Problemas comunes

• Sin TLS: Docker bloquea registries inseguras en versiones recientes.
• Registry insegura: es posible, pero no recomendado.
• Nombres de tags incorrectos: el nombre de la imagen debe incluir el host de la Registry.
• Autenticación no configurada: el push se rechaza sin credenciales.
• Disco lleno: falta realizar Garbage Collection.
• Certificado no confiable: el cliente necesita el certificado CA.

Enlaces y recursos adicionales

• BotServ.de Comandos Docker
• BotServ.de Volúmenes Docker
• BotServ.de Backup Docker
• BotServ.de Seguridad Docker
• BotServ.de Fundamentos de Tailscale

FAQ: Docker Registry

¿Necesito una Registry propia? Si distribuyes muchas imágenes personalizadas internamente, sí. Para imágenes ocasionales, Docker Hub es suficiente.

¿Puedo hacerla pública? Solo con TLS, autenticación y rate limiting. Es mejor mantenerla interna.

¿Es escalable la Registry? Para configuraciones pequeñas, un contenedor único es suficiente. Para escenarios más grandes, existen Distribution o Harbor.

¿Cómo elimino imágenes antiguas? A través de la API o Garbage Collection. Los tags individuales se pueden eliminar mediante la API de la Registry.

¿Qué es Harbor? Un proyecto open-source de Registry avanzada con interfaz gráfica, autenticación y escaneo de seguridad.

Fuentes y lecturas recomendadas

• Docker Registry: https://distribution.github.io/distribution/
• Imagen de Docker Registry: https://hub.docker.com/_/registry
• Harbor: https://goharbor.io/

Resumen: ejecutar tu propia Docker Registry

Una Docker Registry propia te permite distribuir imágenes de forma local o dentro de tu red corporativa. Se inicia rápidamente como contenedor, pero para producción o acceso remoto debe estar protegida con TLS y autenticación. Son importantes los nombres de tags limpios, backups periódicos, Garbage Collection y acceso restringido a la red. Si operas la Registry correctamente, ahorras ancho de banda, aceleras deployments y mantienes el control sobre tus imágenes personalizadas.