Hands-on Lab

Cómo montar un registro Docker privado y autoalojado

17 de julio de 2026 3 min 1

0 / 7

Chuleta

¿Te ha servido? No te pierdas el próximo lab

0:00 / 0:00

Descargamos alpine:3.21 desde Docker Hub: una imagen minúscula (menos de 8 MB) que nos sirve como conejillo de indias para todo el ciclo push/pull de este laboratorio. Fijamos la versión en vez de usar latest para que el comando sea exactamente reproducible.

docker pull alpine:3.21

Lo hice yo

Comprobamos que la imagen quedó en el almacén local de Docker antes de seguir: aparece con su ID y su tamaño real en disco.

docker images alpine:3.21

Levantamos el registro oficial. -d lo deja en segundo plano, -p 5000:5000 publica su puerto HTTP en el host, --restart=always hace que sobreviva a un reinicio del daemon, y registry:3 es la imagen actual del proyecto Distribution (sucesora de la antigua registry:2).

docker run -d -p 5000:5000 --restart=always --name registry registry:3

Lo hice yo

Comprobamos dos cosas a la vez: que el contenedor está en marcha y publica el puerto 5000, y que la API del registro responde. GET /v2/ es el endpoint de comprobación mínimo de la especificación: si el registro está sano y accesible, devuelve un objeto JSON vacío ({}).

docker ps --filter name=registry --format 'table {{.Names}}\t{{.Status}}\t{{.Ports}}'; for i in $(seq 1 30); do curl -fsS http://localhost:5000/v2/ >/dev/null 2>&1 && break; sleep 1; done; curl -s http://localhost:5000/v2/

docker tag crea un alias local nuevo, localhost:5000/alpine:mine, que apunta al mismo ID de imagen que alpine:3.21: no copia ni un byte. docker push sí mueve datos de verdad: sube las capas de la imagen a nuestro registro en el puerto 5000, usando el host:puerto del alias para saber a dónde enviarlas.

docker tag alpine:3.21 localhost:5000/alpine:mine && docker push localhost:5000/alpine:mine

Lo hice yo

Preguntamos al propio registro qué tiene guardado, sin pasar por el cliente Docker. GET /v2/_catalog lista los repositorios (debe aparecer «alpine») y GET /v2/alpine/tags/list lista sus etiquetas (debe aparecer «mine»): la prueba definitiva de que el push llegó a su destino.

for i in $(seq 1 30); do curl -fsS http://localhost:5000/v2/ >/dev/null 2>&1 && break; sleep 1; done; curl -s http://localhost:5000/v2/_catalog | jq .; curl -s http://localhost:5000/v2/alpine/tags/list | jq .

Borramos las dos etiquetas locales que apuntan a esta imagen. Con esto el registro pasa a ser la única copia que existe en todo el laboratorio: cualquier docker pull posterior tendrá que traerla de vuelta desde el puerto 5000, no de una caché local.

docker rmi localhost:5000/alpine:mine alpine:3.21

Lo hice yo

Confirmamos que ninguna de las dos etiquetas queda en el almacén local: ambos comandos devuelven solo la cabecera, sin filas. La imagen ya no existe en esta máquina.

docker images alpine:3.21; docker images localhost:5000/alpine:mine

El momento de la verdad: recuperamos la imagen, pero esta vez desde nuestro propio registro en vez de Docker Hub. El prefijo localhost:5000/ es lo único que cambia respecto a un docker pull normal.

docker pull localhost:5000/alpine:mine

Lo hice yo

No nos basta con que docker pull haya funcionado: arrancamos un contenedor real desde la imagen recién descargada y leemos /etc/os-release dentro de él. Ver «Alpine Linux» en la salida prueba que la imagen que viajó por nuestro registro es una imagen completa y funcional, no solo metadatos.

docker run --rm localhost:5000/alpine:mine cat /etc/os-release

Generamos el fichero de credenciales que exige el modo de autenticación htpasswd del registro. -B fuerza el hash bcrypt (el único formato que registry:3 acepta), -b pasa la contraseña en la propia línea de comandos y -n imprime el resultado en vez de escribir directamente en un fichero existente, así que lo redirigimos nosotros a /auth/htpasswd. changeme es un valor de prueba: en un registro real se sustituye por una contraseña generada y se borra del historial de la shell.

mkdir -p /auth && htpasswd -Bbn registryadmin changeme > /auth/htpasswd

Lo hice yo

Comprobamos que el fichero se generó con el formato correcto: una línea usuario:hash donde el hash empieza por $2y$, la marca de bcrypt. Es justo el fichero que se monta con -v en el contenedor del registro y se referencia con REGISTRY_AUTH_HTPASSWD_PATH para activar la autenticación de verdad.

cat /auth/htpasswd

Limpieza final: paramos y borramos el contenedor del registro, borramos la imagen que recuperamos en el paso anterior y eliminamos el fichero de credenciales de prueba. Nada de esto queda en la máquina al terminar el laboratorio.

docker rm -f registry && docker rmi -f localhost:5000/alpine:mine && rm -rf /auth

Lo hice yo

Comprobación final: ni el contenedor del registro, ni la imagen recuperada, ni el directorio /auth siguen existiendo. Los tres comandos vuelven vacíos o confirman que el directorio ya no está, dejando la máquina limpia.

docker ps -a --filter name=registry; docker images localhost:5000/alpine:mine; ls /auth 2>&1 || echo 'auth dir removed'

1 vista

¿Te ha sido útil este lab? Puntúalo:

Click to rate this post!

[Total: 0 Average: 0]

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, pero 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 con la implementación de referencia 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 localhost: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. La imagen registry:3 admite autenticación básica (usuario y contraseña con hash bcrypt, vía htpasswd) y TLS delante del puerto 5000; en producción van siempre juntas, porque Docker solo envía credenciales en claro a hosts marcados como «inseguros», que por defecto es únicamente localhost. En este laboratorio generamos el fichero htpasswd con un usuario y una contraseña de prueba (changeme) para ver el formato bcrypt que exige el registro; para activarlo de verdad solo falta añadir REGISTRY_AUTH=htpasswd, REGISTRY_AUTH_HTPASSWD_PATH y un certificado en REGISTRY_HTTP_TLS_CERTIFICATE al arrancar el contenedor.

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: localhost: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, Docker solo envía credenciales en claro a hosts marcados como inseguros (por defecto, solo localhost). El registro admite ambos a la vez: htpasswd para autenticación y un certificado para cifrar el tráfico.

¿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.

Chuleta

```
docker pull alpine:3.21
```

docker run -d -p 5000:5000 --restart=always --name registry registry:3

docker tag alpine:3.21 localhost:5000/alpine:mine && docker push localhost:5000/alpine:mine

docker rmi localhost:5000/alpine:mine alpine:3.21

```
docker pull localhost:5000/alpine:mine
```

mkdir -p /auth && htpasswd -Bbn registryadmin changeme > /auth/htpasswd

docker rm -f registry && docker rmi -f localhost:5000/alpine:mine && rm -rf /auth

¿Te ha servido? No te pierdas el próximo lab

Suscríbete a la newsletter

Qué es un registro Docker privado

Cómo se etiqueta y se sube una imagen

Asegurar el registro con htpasswd y TLS

Preguntas frecuentes

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

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

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

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

Chuleta