Publicar tu imagen en Docker Hub significa subirla a un registro público en la nube para que cualquier servidor, compañero o servicio pueda descargarla con un solo comando.
El día que tu imagen viajó sola
Imagina que construiste una aplicación para calcular precios con IVA para una tienda en línea estilo Liverpool. Funciona perfecto en tu laptop. Tu compañero la necesita urgente desde Monterrey. ¿Qué haces? ¿Le mandas un ZIP por WhatsApp? Hay una mejor forma: publicas tu imagen en Docker Hub y él solo ejecuta docker pull. Listo.
Eso es exactamente lo que aprenderás en esta lección.
El Flujo CONSTRUIR → ETIQUETAR → PUBLICAR
Publicar una imagen sigue siempre el mismo proceso de tres pasos. Llámalo el Flujo CEP: Construir, Etiquetar, Publicar. Si memorizas este orden, nunca te perderás.
- Construir: generas la imagen desde tu
Dockerfile. - Etiquetar: le asignas un nombre con tu usuario de Docker Hub incluido.
- Publicar: la subes al registro con
docker push.
Cada paso depende del anterior. No puedes publicar sin etiquetar, y no puedes etiquetar sin construir.
Paso 1 — Crea tu cuenta en Docker Hub
Entra a hub.docker.com y regístrate gratis. Elige un nombre de usuario corto y sin espacios. Ese nombre será parte de todas tus imágenes públicas, así que piénsalo bien.
Por ejemplo, si tu usuario es devbimbo, tus imágenes tendrán este formato:
devbimbo/nombre-imagen:etiqueta
Una vez registrado, confirma tu correo. Docker Hub te da acceso ilimitado a imágenes públicas y un repositorio privado gratuito.
Paso 2 — Inicia sesión desde tu terminal
Antes de subir cualquier imagen, debes autenticarte. Abre tu terminal y ejecuta:
docker login
Docker te pedirá tu usuario y contraseña de Docker Hub. Si todo va bien, verás:
Login Succeeded
Si usas una computadora compartida en tu oficina, cierra sesión al terminar con docker logout. Nunca dejes tus credenciales activas en equipos de acceso público.
Paso 3 — Construye tu imagen
Supon que tienes el siguiente Dockerfile para una API sencilla de consulta de precios:
FROM python:3.11-slim
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt
COPY . .
CMD ["python", "main.py"]
Construye la imagen con este comando. Sustituye devbimbo con tu usuario real:
docker build -t devbimbo/api-precios:1.0 .
El punto al final indica que el contexto de construcción es el directorio actual. La etiqueta 1.0 identifica la versión. Siempre versiona tus imágenes; nunca dependas solo de latest.
Paso 4 — Verifica la imagen antes de subir
Antes de publicar, confirma que la imagen existe y se llama correctamente:
docker images
Deberías ver algo así:
REPOSITORY TAG IMAGE ID SIZE
devbimbo/api-precios 1.0 a3f8c21d09e1 145MB
Si el nombre no incluye tu usuario de Docker Hub, el push fallará. Este es el error más común entre principiantes.
Paso 5 — Publica con docker push
Con la imagen verificada, súbela con:
docker push devbimbo/api-precios:1.0
Verás las capas subiendo una por una:
The push refers to repository [docker.io/devbimbo/api-precios]
5f3b2d1c4a08: Pushed
9a1e7f2b3c44: Pushed
1.0: digest: sha256:abc123... size: 1234
Cuando termine, entra a tu perfil en Docker Hub y verás el repositorio creado automáticamente. Cualquier persona en el mundo puede descargar tu imagen con:
docker pull devbimbo/api-precios:1.0
Etiquetar una imagen ya existente
A veces construyes una imagen sin el nombre correcto y necesitas renombrarla después. Usa docker tag:
docker tag api-precios:local devbimbo/api-precios:1.0
Esto no copia la imagen. Solo crea un alias que apunta a los mismos datos. Es como poner una etiqueta nueva en el mismo producto de Bimbo: el pan es el mismo, pero ahora tiene el nombre correcto para salir al anaquel.
Versiones múltiples: cómo organizar tus publicaciones
Si corriges un error o agregas funcionalidad, publica una nueva versión sin borrar la anterior:
docker build -t devbimbo/api-precios:1.1 .
docker push devbimbo/api-precios:1.1
También puedes mover la etiqueta latest para apuntar a tu versión más reciente:
docker tag devbimbo/api-precios:1.1 devbimbo/api-precios:latest
docker push devbimbo/api-precios:latest
En un equipo como el de desarrollo de FEMSA, cada versión publicada corresponde a una entrega. El servidor de producción siempre jala una versión fija, nunca latest. Así evitas sorpresas cuando alguien actualiza la imagen sin avisar.
Repositorios privados vs. públicos
Cuando creas un repositorio en Docker Hub, tienes dos opciones:
| Tipo | ¿Quién puede hacer pull? | ¿Requiere login para push? |
|---|---|---|
| Público | Cualquier persona | Sí |
| Privado | Solo tú y colaboradores | Sí |
Usa repositorios públicos para proyectos open source o materiales de práctica. Usa privados para código de negocio. Si trabajas en una empresa como Mercado Libre, seguramente usarán un registro privado propio (Amazon ECR, Google Artifact Registry o Azure Container Registry) en lugar de Docker Hub público.
La cuenta gratuita de Docker Hub incluye un repositorio privado. Si necesitas más, los planes de pago arrancan alrededor de $5 USD al mes.
Errores comunes al publicar imágenes
Error 1 — "denied: requested access to the resource is denied"
Este error aparece cuando no has iniciado sesión o el nombre de la imagen no coincide con tu usuario. Verifica con docker login y revisa el nombre exacto de la imagen.
Error 2 — La imagen pesa demasiado
Si tu imagen tiene más de 500 MB, tardará mucho en subirse y descargarse. Revisa tu Dockerfile. ¿Estás copiando archivos innecesarios? Usa un archivo .dockerignore para excluir carpetas como node_modules, __pycache__ o .git:
.git
__pycache__
node_modules
*.log
.env
Una imagen más ligera no solo sube más rápido, sino que también se despliega más rápido en tu servidor. Un desarrollador en Ciudad de México con internet de $299 al mes nota la diferencia entre una imagen de 120 MB y una de 800 MB.
Error 3 — Subir el archivo .env con contraseñas
Si tu .env tiene credenciales del SAT, del IMSS o contraseñas de base de datos, y lo incluyes en la imagen, cualquiera que haga docker pull podrá verlas. Agrega .env a tu .dockerignore siempre. Las variables de entorno deben inyectarse en tiempo de ejecución, no en tiempo de construcción.
Error 4 — Publicar con la etiqueta latest sin versión fija
Si solo publicas latest sin una etiqueta de versión como 1.0 o 2.3, pierdes trazabilidad. Mañana alguien hace docker pull y no sabe qué versión está corriendo. Siempre publica primero con versión y luego mueve latest.
Ejemplo completo: del código al registro
Aquí está el flujo completo en cinco comandos para una API de inventario:
# 1. Construir
docker build -t devbimbo/api-inventario:2.0 .
# 2. Verificar
docker images | grep api-inventario
# 3. Iniciar sesión
docker login
# 4. Publicar versión fija
docker push devbimbo/api-inventario:2.0
# 5. Mover latest
docker tag devbimbo/api-inventario:2.0 devbimbo/api-inventario:latest
docker push devbimbo/api-inventario:latest
Con estos cinco comandos, tu imagen está disponible en cualquier servidor del mundo. Un ingeniero en Guadalajara puede desplegarla en segundos sin pedirte nada más.
Cómo conectar esto con Docker Compose
En la lección anterior viste cómo definir servicios en docker-compose.yml. Ahora puedes reemplazar imágenes construidas localmente por imágenes publicadas en Docker Hub:
services:
api:
image: devbimbo/api-inventario:2.0
ports:
- "8000:8000"
Cualquier persona del equipo ejecuta docker compose up -d y Docker descarga automáticamente la imagen correcta. No necesita el código fuente ni el Dockerfile. Solo necesita el archivo YAML y acceso a Docker Hub.
Este es el poder real de publicar imágenes: separa el proceso de desarrollo del proceso de despliegue.
Cuando publicas una imagen bien etiquetada en Docker Hub, conviertes tu trabajo en una pieza reutilizable que puede desplegarse en cualquier servidor del mundo con un solo comando.