Construir una imagen es solo la mitad del trabajo: para que otros (tu equipo, tus servidores de producción, tus pipelines de despliegue) puedan usarla, hay que publicarla en un registro. Antes de publicar, conviene etiquetarla correctamente siguiendo convenciones claras. En esta lección aprenderemos las convenciones de tagging (nombre:tag), el comando docker tag, cómo autenticarte con docker login, cómo publicar con docker push en Docker Hub o en un registro privado, el versionado semántico de imágenes y las buenas prácticas para que tu flujo de publicación sea ordenado y reproducible.

El nombre completo de una imagen sigue una estructura precisa. Entenderla evita la mayoría de errores al publicar:

Ejemplos según el destino:

• miusuario/api-pagos:1.0 → publicación en Docker Hub bajo tu cuenta.
• ghcr.io/miorganizacion/api-pagos:1.0 → publicación en GitHub Container Registry.
• registro.miempresa.com:5000/api-pagos:1.0 → publicación en un registro privado propio en el puerto 5000.

Puntos clave:

• Para publicar en Docker Hub, el repositorio debe incluir tu usuario: nginx (sin usuario) está reservado a imágenes oficiales y no podrás hacer push ahí.
• Si no indicas registro, Docker usa Docker Hub automáticamente.
• Si no indicas tag, se asume latest, pero conviene ser explícito.

Cuando construyes una imagen, le asignas un nombre con -t. Pero a menudo necesitas añadir otro nombre o tag a una imagen ya existente, por ejemplo para prepararla para un registro concreto. Eso lo hace docker tag.

• miapp:1.0: la imagen de origen (la que ya tienes en local).
• miusuario/miapp:1.0: el nuevo nombre, ahora con tu usuario, listo para publicar en Docker Hub.

docker tag no copia ni duplica la imagen: solo crea un nombre adicional que apunta a la misma imagen (mismo IMAGE ID). Puedes comprobarlo:

• Ambas entradas comparten IMAGE ID: son la misma imagen con dos nombres.

También sirve para marcar la misma imagen con varios tags, por ejemplo una versión concreta y latest:

Para publicar en un registro necesitas autenticarte primero. En Docker Hub:

• Pide tu usuario y contraseña (o, mejor, un token de acceso) de Docker Hub.
• Tras un inicio de sesión correcto, tus credenciales se guardan localmente y podrás hacer push sin volver a autenticarte hasta que cierres sesión.

Para un registro distinto de Docker Hub, indica su dominio:

• Te autentica contra GitHub Container Registry. Cada registro mantiene su propia sesión.

Para cerrar sesión:

Buena práctica de seguridad: usa tokens de acceso personal en lugar de tu contraseña, sobre todo en pipelines automatizados. Un token puede revocarse de forma independiente sin afectar a tu contraseña principal. En entornos de integración continua, suministra el token mediante una variable de entorno secreta y autentícate de forma no interactiva:

• --password-stdin: lee la credencial de la entrada estándar en lugar de escribirla en la línea de comandos, evitando que quede registrada en el historial.

Una vez autenticado y con la imagen correctamente etiquetada, la publicas con docker push:

• Docker sube las capas de la imagen al registro. Las capas que el registro ya tenga no se vuelven a subir, lo que acelera publicaciones sucesivas.

La salida muestra el progreso capa por capa:

• Pushed: capa subida por primera vez.
• Layer already exists: capa que ya estaba en el registro y no hace falta volver a subir.

Si quieres publicar también el tag latest, debes hacer push de cada tag por separado:

Para publicar en un registro privado, el nombre de la imagen debe incluir el dominio del registro:

• Primero etiquetamos la imagen con el dominio del registro privado, y luego hacemos push. Docker deduce a qué registro subir a partir del prefijo del nombre.

Etiquetar todas tus imágenes como latest es cómodo al principio, pero es una mala práctica en cuanto el proyecto crece: no sabes qué versión está realmente en producción ni puedes volver atrás. La solución es el versionado semántico (SemVer), con el formato MAYOR.MENOR.PARCHE:

Una práctica muy habitual es publicar la misma imagen con varios tags a la vez para dar flexibilidad a quien la consume:

• 1.2.3: versión exacta e inmutable en la práctica; ideal para producción reproducible.
• 1.2: apunta siempre a la última parche de la rama 1.2.
• 1: apunta a la última versión de la rama mayor 1.
• latest: la última publicada, cómoda para pruebas pero no recomendada en producción.

Así, un usuario que quiera estabilidad fija 1.2.3, y uno que quiera recibir parches automáticamente puede usar 1.2.

• Fija versiones explícitas en producción: nunca despliegues latest en producción; usa una versión concreta como 1.2.3 para saber exactamente qué corre y poder revertir.
• Etiqueta con metadatos útiles: además de la versión SemVer, muchos equipos añaden tags con el hash de Git del commit (miapp:git-a1b2c3d) para trazabilidad total.
• Automatiza el etiquetado en CI/CD: deja que el pipeline genere los tags a partir de la versión del proyecto o del tag de Git, evitando errores manuales.
• Usa tokens, no contraseñas: y suminístralos como secretos, nunca escritos en el código o el historial.
• No reutilices un tag de versión: una vez publicado 1.2.3, no lo sobrescribas con otro contenido; publica 1.2.4 en su lugar. Así garantizas reproducibilidad.
• Verifica el destino antes del push: comprueba que el nombre incluye el usuario o el dominio correcto para no publicar en el sitio equivocado.

• Intentar push sin tu usuario en el nombre: docker push miapp:1.0 falla porque miapp no incluye tu cuenta. Debe ser miusuario/miapp:1.0.
• Olvidar docker login: el push devuelve un error de autenticación. Inicia sesión primero.
• Creer que docker tag duplica la imagen: solo crea un nombre adicional; no consume espacio extra.
• Publicar solo latest: dificulta saber qué versión hay desplegada y revertir cambios. Usa SemVer.
• Pensar que un solo push sube todos los tags: cada tag se publica por separado.
• Escribir el token en la línea de comandos: usa --password-stdin para no dejarlo en el historial.
• Consejo: tras publicar, valida descargando la imagen en otra máquina con docker pull para confirmar que está accesible y completa.

Tienes una imagen local tienda:build. Etiquétala para tu cuenta de Docker Hub (miusuario) como versión 1.0.0 y también como latest, y publica ambos tags.

Explica por qué docker push miapp:1.0 falla al intentar publicar en Docker Hub y cómo lo corregirías.

Quieres permitir que los consumidores fijen tanto la versión exacta 2.1.0 como la rama menor 2.1. Indica qué tags crearías y publicarías.

Solución 1

Se crean dos nombres para la misma imagen, se inicia sesión y se publica cada tag por separado.

Solución 2

Falla porque miapp no incluye tu usuario, y los nombres sin usuario están reservados a imágenes oficiales en Docker Hub, donde no tienes permisos de publicación. Para corregirlo, etiqueta la imagen con tu cuenta y publícala:

Solución 3

Crearías y publicarías dos tags apuntando a la misma imagen:

2.1.0 es la versión exacta para quien quiera estabilidad total, y 2.1 se reasignará a la última parche de esa rama, de modo que quien lo use reciba automáticamente correcciones compatibles.

En esta lección hemos cerrado el ciclo de trabajo con imágenes: las convenciones de tagging [registro/]usuario/repositorio:tag, el uso de docker tag para añadir nombres, la autenticación con docker login (preferiblemente con tokens), la publicación con docker push en Docker Hub y en registros privados, el versionado semántico con múltiples tags y las buenas prácticas para un flujo reproducible y seguro. Con esto dominas el ciclo completo: buscar, construir, gestionar, etiquetar y publicar imágenes.

Con esta lección concluimos el Módulo 2: Trabajando con Imágenes Docker. En el Módulo 3 pondremos el foco en los contenedores en sí, empezando por Ejecutando Contenedores, donde aprenderemos a lanzar, configurar y controlar contenedores a partir de las imágenes que ahora ya sabes crear y publicar.