Crear y publicar una imagen Docker con un Dockerfile

Una imagen Docker debe poder reconstruirse a partir de instrucciones y archivos versionados. Para ello, utiliza un Dockerfile como fuente de verdad en lugar de instalar paquetes manualmente dentro de un contenedor y guardar el resultado con docker commit [1].

En esta guía prepararemos una imagen web sencilla, la construiremos con una etiqueta versionada, la probaremos y la publicaremos en un registro. Sustituye los nombres de ejemplo por los de tu proyecto.

Preparar el contexto de construcción

Crea un directorio de proyecto con esta estructura:

sitio-docker/
├── Dockerfile
├── .dockerignore
└── sitio/
    └── index.html

El contexto de construcción es el conjunto de archivos que Docker puede utilizar para construir la imagen; en el comando de más adelante será el directorio actual (.) [2].

Escribe un Dockerfile que parta de una imagen mantenida y copie el contenido del sitio:

FROM nginx:stable-alpine
COPY sitio/ /usr/share/nginx/html/

La etiqueta stable-alpine sirve para ilustrar el ejemplo, pero puede apuntar a una versión diferente con el tiempo. Para repetir una compilación con mayor precisión, selecciona una etiqueta específica validada para el proyecto; para fijar exactamente el contenido base, Docker permite indicar también su digest [1].

Define .dockerignore para no enviar al builder archivos que no necesita la imagen:

.git
.env
secrets/
node_modules/

Docker excluye del contexto los archivos que coinciden con .dockerignore [2]. No copies contraseñas, claves privadas u otros secretos dentro del contexto ni los incluyas con COPY o ADD.

Construir y revisar la imagen

Desde la raíz del proyecto, construye la imagen y asígnale un nombre y una etiqueta de versión:

docker build --pull -t mi-cuenta/sitio-ejemplo:1.0.0 .

--pull pide comprobar si hay una versión más reciente de la imagen base con esa etiqueta. Como las etiquetas pueden cambiar, fija la versión base apropiada en el Dockerfile y documenta cuándo la actualizas [1].

Confirma que la imagen aparece en el inventario local y ejecútala ligada solo a la interfaz local para probarla:

docker image ls mi-cuenta/sitio-ejemplo
docker run --rm -p 127.0.0.1:8080:80 mi-cuenta/sitio-ejemplo:1.0.0

Abre http://localhost:8080 y comprueba que se sirve el contenido esperado. docker run permanece en primer plano en este ejemplo; pulsa Ctrl+C para detener el contenedor de prueba.

Versionar y publicar la imagen

Mantén el Dockerfile, .dockerignore y los archivos de la aplicación en Git. Para una versión aprobada, puedes crear y publicar una etiqueta Git:

git tag -a v1.0.0 -m "Versión 1.0.0"
git push origin v1.0.0

La etiqueta Git documenta una versión del código fuente. No construye ni publica por sí sola una imagen: eso requiere ejecutar el flujo de construcción y docker push, manualmente o mediante una integración continua configurada para reaccionar a etiquetas [3].

Para publicar manualmente en Docker Hub, inicia sesión y sube la imagen versionada:

docker login
docker push mi-cuenta/sitio-ejemplo:1.0.0

Las etiquetas permiten distinguir versiones de una misma imagen. Si además mantienes una etiqueta móvil como latest, publícala de forma explícita y no la uses como sustituto de una versión concreta [4].

Si usas GitHub Container Registry, el nombre de la imagen incluye el registro, por ejemplo ghcr.io/mi-cuenta/sitio-ejemplo:1.0.0; configura la autenticación y los permisos de publicación según la documentación de GitHub [5].

Por qué no usar docker commit como flujo habitual

docker commit guarda en una imagen los cambios que se hicieron dentro de un contenedor. Aunque puede ser útil en casos puntuales, esos cambios no quedan descritos de forma completa en un archivo de construcción y pueden incluir datos o credenciales por accidente [4].

Un Dockerfile deja el proceso revisable y repetible: se pueden revisar las instrucciones, versionar cambios y reconstruir la imagen desde una base conocida. Evita guardar secretos en instrucciones, argumentos de construcción o capas; utiliza mecanismos de secretos apropiados para la plataforma cuando sean necesarios [1].

En resumen

• Describe la imagen en un Dockerfile y guarda sus fuentes en control de versiones.
• Mantén pequeño y explícito el contexto con .dockerignore.
• Construye, etiqueta y prueba la imagen antes de publicarla.
• Relaciona las etiquetas de Git y del registro, recordando que una etiqueta Git solo activa una publicación si existe una automatización configurada.
• No uses docker commit como sustituto de un proceso de construcción mantenible.

📚 Fuentes consultadas

1. Building best practices — Docker Docs
2. Build context — Docker Docs
3. Publishing Docker images — GitHub Docs
4. Build, tag, and publish an image — Docker Docs
5. Working with the Container registry — GitHub Docs

Imagen