Subir imágenes a Docker Hub

Autenticación y etiquetas

La publicación de imágenes en Docker Hub requiere dos elementos fundamentales: estar autenticado con una cuenta válida y aplicar un etiquetado correcto que incluya el namespace del usuario. Sin estos requisitos, no es posible compartir nuestras imágenes personalizadas con otros desarrolladores o equipos.

Autenticación con Docker Hub

El comando docker login establece la conexión segura entre nuestro entorno local y Docker Hub. Este proceso almacena las credenciales de forma cifrada en nuestro sistema, permitiendo realizar operaciones de push y pull en repositorios privados.

docker login

Al ejecutar este comando, Docker solicitará las credenciales de acceso:

Username: tu-usuario-dockerhub
Password: tu-token-acceso

Es importante destacar que Docker Hub recomienda utilizar tokens de acceso personal en lugar de contraseñas directas. Estos tokens ofrecen mayor seguridad y control granular sobre los permisos:

• 1. Crear un token de acceso: Desde la configuración de cuenta en Docker Hub
• 2. Configurar permisos específicos: Lectura, escritura o administración de repositorios
• 3. Usar el token como contraseña: En el proceso de login

# Verificar el estado de autenticación
docker system info | grep Username

La información de login se almacena en el archivo ~/.docker/config.json en sistemas Unix, o en %USERPROFILE%\.docker\config.json en Windows.

Sistema de etiquetado y namespace

El etiquetado correcto es esencial para organizar y versionar las imágenes en Docker Hub. El formato estándar sigue la estructura namespace/repository:tag, donde cada componente tiene un propósito específico.

Estructura del namespace:

usuario-dockerhub/nombre-imagen:etiqueta

• Usuario: Corresponde al nombre de usuario en Docker Hub
• Nombre de imagen: Identifica el proyecto o aplicación
• Etiqueta: Especifica la versión o variante

Ejemplo práctico con una aplicación web:

# Etiquetar una imagen local para Docker Hub
docker tag mi-app:latest miusuario/mi-app:1.0.0

# Verificar el etiquetado
docker images miusuario/mi-app

Buenas prácticas de etiquetado

Un versionado semántico facilita la gestión y actualización de imágenes en entornos empresariales. Las etiquetas deben ser descriptivas y seguir patrones consistentes.

Patrones recomendados:

• 1. Versionado semántico: 1.0.0, 2.1.3, 3.0.0-beta

docker tag nginx:alpine miusuario/mi-nginx:1.2.0
docker tag nginx:alpine miusuario/mi-nginx:1.2
docker tag nginx:alpine miusuario/mi-nginx:1

• 2. Etiquetas descriptivas: stable, dev, production

docker tag mi-app:latest miusuario/mi-app:stable
docker tag mi-app:dev miusuario/mi-app:development

• 3. Etiquetas por entorno: staging, prod, test

docker tag postgresql:15 miusuario/mi-db:prod-v2.1
docker tag postgresql:15 miusuario/mi-db:staging-v2.1

Gestión de múltiples etiquetas

Una imagen puede tener múltiples etiquetas que apunten al mismo contenido, facilitando diferentes estrategias de despliegue y versionado.

# Crear múltiples etiquetas para la misma imagen
docker tag mi-app:build-123 miusuario/mi-app:1.5.0
docker tag mi-app:build-123 miusuario/mi-app:1.5
docker tag mi-app:build-123 miusuario/mi-app:latest
docker tag mi-app:build-123 miusuario/mi-app:stable

Verificar todas las etiquetas:

docker images miusuario/mi-app

Este enfoque permite que los equipos de desarrollo utilicen latest para pruebas rápidas, mientras que producción puede anclar versiones específicas como 1.5.0 para mayor estabilidad.

Preparación para publicación

Antes de realizar el push, es fundamental verificar la configuración y asegurar que las etiquetas sean correctas:

# Listar imágenes preparadas para publicación
docker images | grep miusuario

# Verificar la autenticación actual
docker system info | grep -i registry

El namespace debe coincidir exactamente con el nombre de usuario de Docker Hub. Un error común es utilizar mayúsculas o caracteres especiales no permitidos en el namespace.

Push y visibilidad

Una vez que tenemos nuestras imágenes correctamente etiquetadas y estamos autenticados, el siguiente paso es publicarlas en Docker Hub y configurar su visibilidad según las necesidades del proyecto. Este proceso implica entender las opciones de acceso y las limitaciones del servicio.

Publicación con docker push

El comando docker push transfiere la imagen desde nuestro entorno local hacia el registro de Docker Hub. Este proceso sube todas las capas que componen la imagen, optimizando la transferencia mediante deduplicación.

# Publicar una imagen específica
docker push miusuario/mi-app:1.0.0

Durante el push, Docker muestra el progreso de cada capa:

The push refers to repository [docker.io/miusuario/mi-app]
a8c6f4d4d4d4: Pushed 
b7d8e9f0f1f2: Pushed 
c9e2f3g4g5g6: Pushed 
1.0.0: digest: sha256:abc123... size: 1234

Publicar múltiples etiquetas simultáneamente:

# Subir todas las etiquetas de un repositorio
docker push miusuario/mi-app --all-tags

Configuración de visibilidad de repositorios

Docker Hub ofrece dos niveles de visibilidad para los repositorios: público y privado. Esta configuración determina quién puede acceder y descargar nuestras imágenes.

Repositorios públicos

Los repositorios públicos son accesibles para cualquier usuario sin autenticación. Son ideales para proyectos de código abierto y herramientas que queremos compartir con la comunidad.

Características de repositorios públicos:

• Acceso libre: Cualquier usuario puede realizar docker pull
• Visibilidad completa: Aparecen en búsquedas públicas de Docker Hub
• Sin límite de pulls: Los usuarios autenticados no tienen restricciones
• Ideal para: Librerías, herramientas open source, imágenes base personalizadas

# Cualquier usuario puede descargar sin autenticación
docker pull miusuario/mi-herramienta:latest

Repositorios privados

Los repositorios privados requieren autenticación específica para acceder al contenido. Son esenciales para aplicaciones empresariales y proyectos con código propietario.

Características de repositorios privados:

• Acceso restringido: Solo usuarios autorizados pueden descargar
• Control de permisos: Gestión granular de colaboradores
• Privacidad: No aparecen en búsquedas públicas
• Límites por plan: Cuentas gratuitas tienen restricciones

# Requiere autenticación previa
docker login
docker pull miusuario/mi-app-privada:1.0.0

Gestión de colaboradores y permisos

Para repositorios privados, Docker Hub permite configurar diferentes niveles de acceso para colaboradores del equipo.

Niveles de permisos disponibles:

• 1. Read: Solo descarga de imágenes
• 2. Write: Descarga y subida de nuevas versiones
• 3. Admin: Control completo incluyendo configuración

La gestión se realiza desde la interfaz web de Docker Hub, en la sección de configuración del repositorio específico.

Rate limits y limitaciones

Docker Hub implementa límites de descarga para controlar el uso del servicio y garantizar la disponibilidad para todos los usuarios.

Límites para usuarios anónimos

Los usuarios no autenticados tienen restricciones más estrictas:

• 100 pulls cada 6 horas por dirección IP
• Medición por IP: Afecta a toda la red/organización
• Reset automático: El contador se reinicia cada 6 horas

# Verificar límites actuales (requiere autenticación)
docker manifest inspect miusuario/mi-app:latest -v

Límites para usuarios autenticados

Los usuarios con cuentas gratuitas de Docker Hub tienen límites más generosos:

• 200 pulls cada 6 horas por cuenta
• Límites independientes: Cada cuenta tiene su propio contador
• Repositorios privados: Limitaciones adicionales según el plan

Planes de suscripción

Docker Hub ofrece planes comerciales que eliminan o incrementan significativamente estos límites:

• Docker Pro: Límites ampliados y repositorios privados ilimitados
• Docker Team: Gestión de equipos y colaboración empresarial
• Docker Business: Características avanzadas de seguridad y administración

Buenas prácticas para la publicación

Una estrategia de publicación consistente mejora la experiencia de los usuarios y facilita el mantenimiento a largo plazo.

Gestión de la etiqueta latest

La etiqueta latest debe utilizarse con criterio, ya que puede causar problemas en entornos de producción:

# Actualizar latest solo con versiones estables
docker tag miusuario/mi-app:1.5.0 miusuario/mi-app:latest
docker push miusuario/mi-app:latest
docker push miusuario/mi-app:1.5.0

Recomendaciones para latest:

• Solo versiones estables: Evitar versiones beta o development
• Actualización consciente: No automática con cada build
• Documentación clara: Especificar qué versión representa latest

Versionado incremental

Un patrón de versionado coherente facilita la adopción y el mantenimiento:

# Patrón recomendado para releases
docker push miusuario/mi-app:2.1.0    # Versión específica
docker push miusuario/mi-app:2.1      # Versión minor
docker push miusuario/mi-app:2        # Versión major

Verificación y testing post-publicación

Después de publicar, es importante validar que la imagen funciona correctamente desde Docker Hub:

# Limpiar imágenes locales para testing real
docker rmi miusuario/mi-app:1.0.0

# Descargar y probar desde Docker Hub
docker run miusuario/mi-app:1.0.0

Validaciones recomendadas:

• Descarga limpia: Probar desde un entorno sin la imagen local
• Funcionalidad básica: Verificar que la aplicación arranca correctamente
• Tamaño optimizado: Confirmar que no se han incluido archivos innecesarios
• Metadatos correctos: Revisar etiquetas y descripciones en Docker Hub

Automatización y CI/CD

En entornos empresariales, la publicación automatizada forma parte del pipeline de desarrollo:

# Ejemplo de script de publicación automatizada
#!/bin/bash
VERSION=$(git describe --tags --always)

docker build -t miusuario/mi-app:${VERSION} .
docker tag miusuario/mi-app:${VERSION} miusuario/mi-app:latest

docker push miusuario/mi-app:${VERSION}
docker push miusuario/mi-app:latest

Esta automatización garantiza consistencia en las publicaciones y reduce errores manuales en el proceso de release.