Docker Compose: diferencias entre build e image en un VPS
Entiende por qué Compose ignora cambios en tu Dockerfile: image usa una imagen y build la compila. Incluye el comportamiento de compose up en un VPS.
Docker Compose: diferencia entre build e image, respuesta breve
En un archivo de Docker Compose, image: identifica la imagen que se debe usar. Puede ser una imagen local, una etiqueta o una referencia a un digest. build: indica a Compose cómo compilar una imagen a partir del código fuente. Si se establece sólo image:, Compose usa o descarga la imagen según pull_policy. Si se establece sólo build:, Compose compila la imagen con el compilador configurado y le asigna un nombre derivado del nombre del proyecto y del servicio. Si se establecen ambos, pull_policy determina si Compose descarga o compila la imagen. Cuando la compila, etiqueta el resultado con el nombre indicado en image:. Así se puede compilar una imagen y subirla con el nombre elegido. El compilador puede ejecutarse localmente o en un Docker host remoto.
Esa es toda la diferencia. El resto explica cómo funciona en la práctica en un servidor. Se asume que Docker Engine y el plugin de Compose ya están instalados. Ejecutar Docker en un VPS cubre esa parte.
Las tres formas completas
Use una etiqueta publicada. Si falta, se descarga según la política de descarga predeterminada. No interviene ningún Dockerfile.
services:
web:
image: nginx:1.27
restart: unless-stopped
ports:
- "80:80"Compile a partir de un Dockerfile situado en el directorio del proyecto. La compilación también puede descargar imágenes y dependencias requeridas por el Dockerfile.
services:
web:
build: .
restart: unless-stopped
ports:
- "80:80"Compile y etiquete el resultado con docker compose build. Sin una política de descarga explícita, up intenta descargar esta imagen antes de compilarla. Después, docker compose push puede enviar esa etiqueta exacta a un registro.
services:
web:
build:
context: .
dockerfile: Dockerfile
image: registry.example.com/acme/web:1.4.2
restart: unless-stopped
ports:
- "80:80"context es el directorio que se envía al compilador. dockerfile se resuelve en relación con ese contexto, por lo que context: . con dockerfile: docker/prod.Dockerfile es normal y correcto. Ejecute docker compose images para ver el nombre y el ID de imagen asociados a cada contenedor de servicio. Compruebe el archivo de Compose para confirmar si el servicio usa image:, build: o ambos.
¿Por qué docker compose up no vuelve a compilar después de cambiar el Dockerfile?
Porque el funcionamiento normal de up reutiliza una imagen existente, salvo que solicite una compilación o configure una política que la requiera.
Cuando Compose inicia un servicio que sólo tiene una sección build:, usa la imagen existente si está disponible. No lee el Dockerfile, compara los archivos de origen ni comprueba ninguna marca de tiempo. Si se especifican image: y build: y no se indica explícitamente pull_policy, Compose intenta extraer la imagen primero y la compila si no está disponible en el registro o en la caché de la plataforma. Que la imagen esté presente se considera suficiente.
Por eso edita app.py, ejecuta docker compose up -d, ve que Compose informa de que el contenedor está en ejecución y termina sirviendo el código antiguo. No se produjo ningún error, así que tampoco apareció ningún aviso. La pista está en la palabra de estado que Compose muestra junto al nombre del contenedor: un contenedor que Compose reemplazó aparece como recreado o iniciado, mientras que un contenedor que Compose decidió no modificar aparece como en ejecución.
Dos comprobaciones permiten confirmarlo. docker compose images muestra el ID de imagen que usa cada contenedor; anótelo antes del despliegue y compárelo después. docker image ls incluye una columna CREATED, pero las compilaciones almacenadas en caché y las marcas de tiempo reproducibles implican que esa fecha, por sí sola, no demuestra si se compiló el código fuente más reciente.
Qué opciones obligan a reconstruir
docker compose up -d --buildcrea primero las imágenes y después vuelve a crear cualquier contenedor cuya imagen haya cambiado. Esta es la opción que busca la mayoría de los usuarios.docker compose build webcrea la imagen de un servicio y no inicia ningún contenedor. Úsela condocker compose up --no-deps -d webpara reemplazar sólo ese contenedor y mantener el resto de la pila en ejecución.docker compose build --no-cache webomite las capas almacenadas en caché y reconstruye el servicio.docker compose build --pullintenta descargar una versión más reciente de la imagen base enFROM. De este modo, una etiqueta mutable comonode:22obtiene su contenido actual en lugar de usar la copia que descargó en marzo.docker compose up -d --force-recreateobliga a volver a crear el contenedor aunque la configuración y la imagen no hayan cambiado. Esta opción no solicita una compilación, peroupaún puede crear la imagen si falta o si la política de descarga lo exige. Usar esta opción cuando en realidad necesitaba--buildes un error frecuente.
También puede trasladar esta decisión al archivo. Según la especificación de Compose, pull_policy: build indica que Compose crea la imagen y la vuelve a crear si ya existe. Cada up implica entonces una compilación, lo que puede ser adecuado en un portátil, pero rara vez lo es en un servidor.
services:
web:
build: .
image: registry.example.com/acme/web:dev
pull_policy: buildTambién conviene conocer otra interacción. docker compose pull intenta descargar las imágenes de los servicios que también tienen una sección build. Si la descarga falla, indica que la imagen debe crearse. Pase --ignore-buildable para omitir esos servicios sin mostrar mensajes.
Cómo decide la caché de compilación el tiempo de despliegue
El constructor comprueba cada instrucción del Dockerfile para buscar un resultado reutilizable en la caché cuando esa instrucción y sus entradas no han cambiado. En COPY, las entradas incluyen el contenido y los metadatos de los archivos, pero excluyen las horas de modificación. Cuando una capa deja de coincidir con la caché, se vuelven a compilar los pasos posteriores que dependen de ella.
Esa única regla determina si el despliegue tarda segundos o minutos. Ordene el Dockerfile desde lo que cambia con menos frecuencia hasta lo que cambia en cada commit.
FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
CMD ["node", "server.js"]npm ci está por encima de COPY . ., por lo que editar un archivo de código fuente mantiene la capa de instalación en la caché y la compilación continúa desde el paso de copia. Si intercambia esas dos líneas, un cambio de un solo carácter vuelve a instalar todas las dependencias, porque COPY . . invalida la capa sobre la que se basa npm ci. La misma estructura se aplica a pip install -r requirements.txt y a go mod download.
--no-cache es la herramienta adecuada cuando sospecha que una capa obsoleta está ocultando la corrección. No es una buena opción predeterminada, porque elimina la reutilización que el orden del Dockerfile permite conseguir.
Hay un elemento que los conjuntos de la imagen y Compose pueden sobrescribir: CMD del Dockerfile es lo que la imagen ejecuta de forma predeterminada, y una clave command: en el servicio lo reemplaza. Cómo interactúan command y entrypoint es importante en este caso, porque una sobrescritura de Compose puede hacer que una imagen recién compilada se comporte exactamente igual que la anterior.
Contexto de compilación y .dockerignore
context: . pone el directorio del proyecto a disposición del compilador. Sin exclusiones, esto incluye .git y cualquier directorio de datos que mantenga junto al código fuente, aunque BuildKit omite los archivos que no se usan y transfiere los cambios de forma incremental. Si una compilación se detiene en el paso de transferencia del contexto aunque el proyecto no haya cambiado, el contexto es demasiado grande.
Un archivo .dockerignore en la raíz del contexto excluye rutas de esa transferencia. La sintaxis es similar a .gitignore.
.git
node_modules
*.log
data/
.envEsto ofrece dos ventajas. La transferencia se reduce y se tarda menos en enviar esos archivos. Además, COPY . . ya no puede copiar .env a la imagen, donde cualquiera que descargue esa imagen puede leerlo.
El caso de compilaciones que se vuelven más lentas con el tiempo suele deberse a un bind mount. Un volumen con nombre se encuentra fuera del directorio del proyecto, pero un bind mount como ./data:/var/lib/postgresql/data está dentro del contexto de compilación. Por eso, las compilaciones se vuelven más lentas cada semana a medida que crece la base de datos. Una línea en .dockerignore lo corrige. Bind mounts frente a volúmenes con nombre explica esta diferencia con más detalle.
Los argumentos de compilación presentan una versión menor del mismo riesgo. Los valores pasados mediante args: pueden permanecer en el historial de la imagen o en los metadatos de procedencia. Por tanto, use allí un número de versión y nunca un token. Los argumentos de proxy predefinidos se excluyen de la caché de compilación y docker history de forma predeterminada, salvo que se referencien explícitamente en el Dockerfile. Archivos de entorno y secretos en Compose explica dónde deben almacenarse las credenciales.
¿Debe compilar en el VPS o compilar en otro lugar y descargar la imagen?
Compilar en el servidor que atiende el tráfico es la opción predeterminada porque es el camino más corto: git pull y luego docker compose up -d --build. Esto funciona en un servidor pequeño del que todavía no depende nadie. Deja de ser una buena opción por dos razones que puede medir y por otra que sólo aparece en un día problemático.
Memoria. Una compilación ejecuta compiladores y empaquetadores junto a la aplicación activa, y estos suelen ser los componentes que más memoria consumen. Un empaquetador de JavaScript o una compilación de Rust puede agotar la memoria disponible en un VPS de 1 GB. Cuando se agota la memoria, el kernel selecciona una víctima de OOM mediante una puntuación de peligrosidad basada en el uso de memoria, el contexto de asignación y oom_score_adj; no termina simplemente el proceso más grande. La compilación puede detenerse con Killed y el estado de salida 137, o el kernel puede terminar la base de datos y el sitio puede quedar fuera de servicio durante un despliegue. dmesg -T | grep -i oom busca mensajes de OOM en el registro del kernel; para acceder a él se necesita permiso de lectura.
Disco. Las compilaciones dejan capas de imágenes y caché de compilación. docker system df muestra el uso de disco; la recolección de basura periódica de BuildKit recupera la caché según las políticas configuradas. Recupere espacio con docker image prune para las imágenes huérfanas y con docker builder prune para las capas almacenadas en la caché. Un disco lleno detiene algo más que la compilación. La base de datos también deja de escribir, y ese fallo cuesta mucho más que un despliegue lento.
Reproducibilidad. Si no la publica ni la exporta, una imagen compilada en el servidor sólo existe en ese servidor. Si la imagen anterior ya no está disponible, para volver atrás debe cambiar al commit anterior y compilar de nuevo. No se garantiza que esa compilación produzca lo mismo, porque la etiqueta base cambió y los espejos de paquetes también cambiaron. Compilar en otro lugar y publicar una etiqueta convierte una reversión en una edición: apunte image: a la etiqueta anterior y ejecute docker compose up -d.
La configuración que resulta fiable es sencilla. La integración continua ejecuta la compilación y publica registry.example.com/acme/web:<git-sha>, y el archivo Compose del VPS contiene image: sin ninguna clave build:.
El despliegue se reduce entonces a dos comandos que apenas necesitan memoria.
docker compose pull
docker compose up -dEjecute docker login registry.example.com en el servidor para guardar las credenciales necesarias para descargar etiquetas privadas.
Conserve la sección de compilación para el desarrollo en lugar de eliminarla, en un archivo cuyo nombre elija.
# compose.dev.yaml
services:
web:
build:
context: .
pull_policy: builddocker compose -f compose.yaml -f compose.dev.yaml up -d --buildLlame a ese archivo compose.dev.yaml y no compose.override.yaml. Compose carga automáticamente un archivo de sustituciones cuando está presente, por lo que una sustitución copiada por error en el servidor volvería a iniciar las compilaciones allí sin avisar. La combinación de varios archivos Compose explica cómo se resuelve cada clave durante la combinación.
La trampa de la arquitectura al compilar en otro equipo
Una imagen de plataforma contiene la arquitectura de CPU para la que se compiló. Si compila una imagen ARM en un portátil con Apple Silicon, la publica y después la usa en un VPS x86_64, Docker muestra una advertencia durante la creación del contenedor si utiliza una imagen almacenada en caché con una arquitectura incompatible y no se ha especificado una plataforma. Sin emulación, el proceso falla con exec format error. El mensaje parece indicar que el binario está dañado, pero no es así. Compile explícitamente para el destino:
docker buildx build --platform linux/amd64 \
-t registry.example.com/acme/web:1.4.2 --push .El mismo desajuste ocurre en sentido inverso si el portátil usa x86 y ejecuta un VPS ARM en lugar de uno x86. Si deja que CI compile en la arquitectura en la que realiza el despliegue, elimina esta duda. Una imagen multiplataforma también resuelve el problema: Docker selecciona la variante correspondiente al descargarla.
Qué comprobar después de un despliegue
docker compose imagesmuestra la imagen y la etiqueta usadas por cada contenedor en ejecución. Un ID de imagen diferente confirma que la nueva compilación está en servicio.docker compose configmuestra el archivo combinado después de sustituir las variables, para que pueda leer el nombre de imagen final que usará Compose antes de ejecutar nada.docker compose logs -f webdurante los primeros 30 segundos posteriores al cambio. Un contenedor que se inicia y se detiene repetidamente sólo se reinicia si su política de reinicio lo indica; revise los registros para conocer la causa.docker image lsmuestra una columna CREATED. Compruebe también la salida de la compilación y el ID de la imagen desplegada, porque la marca de tiempo de creación por sí sola no demuestra que se haya ejecutado una recompilación.
Si todavía está preparando el archivo que usarán estas comprobaciones, los conceptos básicos de un archivo Compose en un VPS cubren las claves relacionadas, y la guía rápida de comandos de Compose enumera el resto de subcomandos.
FAQ
¿Puedo usar build e image en el mismo servicio?
Sí. Es la configuración habitual para un proyecto que compila usted mismo. Cuando Compose compila desde la sección build:, etiqueta el resultado con el valor de image:. Sin un pull_policy explícito, up intenta hacer pull primero. Esa etiqueta es la que docker compose push envía a un registro y la que otra máquina descarga. Sin una clave image:, Compose sigue compilando, pero asigna el nombre de la imagen a partir del proyecto y del servicio, y advierte de que falta el atributo necesario para enviar la imagen.
¿Por qué docker compose up no detecta el cambio en mi Dockerfile?
Porque un up normal reutiliza una imagen existente, salvo que solicite una compilación o configure una política que la requiera. No compara esa imagen con el Dockerfile ni con los archivos de origen para decidir si debe volver a compilar. Ejecute docker compose up -d --build, o ejecute docker compose build web seguido de docker compose up --no-deps -d web para reemplazar un solo servicio. Si establece pull_policy: build en el servicio, cada up volverá a compilar la imagen, lo que resulta adecuado en un equipo de desarrollo.
¿Cuál es la diferencia entre --build y --force-recreate?
--build vuelve a compilar la imagen y después recrea los contenedores cuya imagen haya cambiado. --force-recreate fuerza la recreación de los contenedores aunque la configuración y la imagen no hayan cambiado; por sí solo no solicita una compilación. Si el cambio está en el código fuente o en el Dockerfile, --build es la opción que necesita. --force-recreate sirve para restablecer el propio contenedor, por ejemplo, para borrar su capa de escritura y conservar la misma imagen.
¿Debo compilar mis imágenes de Docker en el VPS o en otro lugar?
Compile en otro lugar y descargue una etiqueta cuando el servidor también atienda tráfico. La compilación compite con la aplicación por la memoria y, si se agota, el kernel selecciona un proceso mediante una puntuación OOM ajustable, que puede afectar a la compilación o a la base de datos. Las compilaciones también dejan caché en el disco, aunque BuildKit la recupera automáticamente según sus políticas de recolección de basura. Compilar en el servidor sigue siendo válido para un proyecto pequeño sin usuarios. Más adelante, la migración será sencilla si mantiene la sección build: en un archivo Compose exclusivo para desarrollo.
¿Cómo evito que la caché de compilación de Docker llene el disco?
Ejecute docker system df para consultar cuánto espacio ocupan las imágenes y la caché de compilación. docker builder prune elimina las capas en caché y docker image prune elimina las imágenes sin referencia que dejaron las compilaciones anteriores. Añadir -a elimina toda la caché de compilación no utilizada o todas las imágenes no referenciadas por contenedores, respectivamente; no garantiza que la siguiente compilación empiece sin caché. No programe docker system prune -af --volumes en un servidor, porque elimina los contenedores detenidos y los volúmenes anónimos no utilizados, lo que pone en riesgo los datos de bases de datos almacenados en un volumen anónimo durante el mantenimiento.