Qué es un registro Docker privado

Un registro es el servidor que guarda las imágenes de contenedor y las sirve cuando alguien ejecuta docker pull. Docker Hub es el registro público por defecto. En cuanto necesitas controlar dónde viven tus imágenes, por cumplimiento normativo, por ancho de banda o simplemente para no depender de un tercero, montas el tuyo. La implementación de referencia es la del proyecto Distribution, empaquetada en la imagen registry:3.

Cómo se etiqueta y se sube una imagen

El nombre de una imagen lleva el registro codificado delante: host:puerto/repositorio:etiqueta. docker tag alpine:3.21 registry.lab:5000/alpine:mine no copia nada, solo crea un alias local que apunta al mismo ID de imagen; es docker push el que envía las capas al registro. Puedes repasar la sintaxis exacta en la referencia oficial de docker tag.

Asegurar el registro con htpasswd y TLS

Un registro sin autenticación es un cubo abierto: cualquiera con red hasta el puerto 5000 puede subir o descargar imágenes. En este laboratorio lo cerramos de verdad. Generamos una CA propia y un certificado para registry.lab, creamos el fichero htpasswd con hash bcrypt y arrancamos registry:3 con REGISTRY_HTTP_TLS_CERTIFICATE, REGISTRY_AUTH=htpasswd y REGISTRY_AUTH_HTPASSWD_PATH.

El cliente Docker confía en el certificado porque copiamos la CA a /etc/docker/certs.d/registry.lab:5000/ca.crt, como explica la documentación de Docker sobre certificados de registro. El resultado se ve en la terminal: sin credenciales, la API responde 401 y el push falla. Tras docker login, el push y el pull funcionan por HTTPS. El usuario y la contraseña (changeme) son de prueba: en producción usa una contraseña fuerte y un certificado de una CA reconocida.

Si vas a exponer el registro bajo tu propio dominio, nuestra guía de Nginx Proxy Manager con Docker resuelve la parte del certificado TLS delante de cualquier contenedor. Para entender el resto de la red que toca este laboratorio tenemos guías dedicadas sobre redes en Docker y sobre volúmenes y bind mounts. Y si prefieres una guía escrita paso a paso sin vídeo, la versión larga está en cómo montar un registro privado de imágenes Docker. Este y el resto de nuestros laboratorios prácticos siguen la misma regla: todo lo que ves se ejecutó de verdad.

Preguntas frecuentes

¿Qué imagen oficial se usa para montar un registro Docker privado?

La imagen registry:3, mantenida por el proyecto Distribution (la implementación de referencia del registro de contenedores). Sustituye a la antigua registry:2, que sigue funcionando pero ya no recibe las últimas correcciones.

¿Cómo le indico a Docker que use mi registro en vez de Docker Hub?

Anteponiendo el host y el puerto del registro al nombre de la imagen: registry.lab:5000/alpine:mine en vez de alpine:mine. Ese prefijo es lo único que distingue una imagen de Docker Hub de una de tu propio registro.

¿Es seguro dejar un registro Docker sin autenticación ni TLS?

No para producción. Sin autenticación, cualquiera con red hasta el puerto 5000 puede subir o descargar imágenes; sin TLS, las credenciales viajan en claro. En este laboratorio activamos las dos cosas: el registro sirve HTTPS con un certificado de una CA propia y exige usuario y contraseña, así que sin credenciales la API responde 401 y tanto el push como el pull fallan.

¿Qué diferencia hay entre docker tag y docker push?

docker tag no mueve ni un byte: crea un alias local nuevo que apunta al mismo ID de imagen. docker push es el que de verdad envía las capas de la imagen al registro de destino codificado en ese alias.

¿Cómo hago que Docker confíe en el certificado de mi registro privado?

Copia el certificado de la CA que lo firmó a /etc/docker/certs.d/<host>:<puerto>/ca.crt en cada máquina cliente, por ejemplo /etc/docker/certs.d/registry.lab:5000/ca.crt. Docker lee ese directorio en cada conexión, sin reiniciar el demonio, y la confianza se limita a ese registro.