Docker Compose build vs image for VPS: wetin change?
Know how Docker Compose image and build work for VPS, why compose up ignores your Dockerfile change, and the exact command wey go rebuild am.
Docker Compose build vs image: short answer
For Docker Compose file, image: dey identify the image wey e go use. E fit be local image, tag, or digest reference. build: dey tell Compose how to build image from source. If you set only image:, Compose go use or pull the image according to pull_policy. If you set only build:, Compose go build the image with the configured builder. E go give the image name wey come from project name and service name. If you set both, pull_policy go control whether Compose pulls or builds. When e builds, e go tag the result with the name for image:. Na so you fit build image and push am with name wey you choose. The builder fit run locally or for remote Docker host.
Na the complete difference be that. Everything wey dey below explain how e work for server. This one assume say Docker Engine and Compose plugin don already install; how to run Docker for VPS cover that part.
The three forms in full
Use a published tag, and pull am if e dey miss under the default pull policy. No Dockerfile dey involved at any point.
services:
web:
image: nginx:1.27
restart: unless-stopped
ports:
- "80:80"Build from a Dockerfile wey dey inside the project directory. The build fit also pull images and download dependencies wey the Dockerfile need.
services:
web:
build: .
restart: unless-stopped
ports:
- "80:80"Build and tag the result with docker compose build; if you no set explicit pull policy, up go try pull this image before e build am. docker compose push fit then send that exact tag go a registry.
services:
web:
build:
context: .
dockerfile: Dockerfile
image: registry.example.com/acme/web:1.4.2
restart: unless-stopped
ports:
- "80:80"context na the directory wey dem send go the builder. dockerfile dey resolve relative to that context, so context: . with dockerfile: docker/prod.Dockerfile na normal and correct thing. Run docker compose images to see the image name and image ID behind each service container; check the Compose file to confirm whether the service dey use image:, build: or both.
Why does docker compose up no rebuild after I change the Dockerfile?
Because normal up dey reuse image wey already dey there, unless you request build or configure policy wey require am.
When Compose start service wey get only build: section, e use existing image if one dey available. E no read your Dockerfile, compare your source files, or check any timestamp. If both image: and build: dey present and you no specify pull_policy, Compose first try pull, then build if image no dey for registry or platform cache. Once image dey present, Compose treat am as good enough.
So you edit app.py, run docker compose up -d, see Compose report say container dey run, but service still dey serve old code. Nothing fail, so nothing warn you. The clue na the status word wey Compose print beside container name: container wey Compose replace go report as recreated or started, while container wey Compose decide to leave alone go report as running.
Two checks go settle the matter. docker compose images go print image ID wey each container dey use, so note am before deploy and compare am after. docker image ls get a CREATED column, but cached builds and reproducible timestamps mean say that date alone no prove whether your latest source build don happen.
Which flags go force rebuild
docker compose up -d --buildgo build first, then e go recreate any container wey image don change. Na this flag most people dey find.docker compose build webgo build one service and e no start anything. Follow am withdocker compose up --no-deps -d webto replace only that container, while the rest of the stack continue to run.docker compose build --no-cache webgo bypass cached layers and rebuild the service.docker compose build --pullgo try pull newer version of the base image forFROM, so moving tag likenode:22go pick the current contents instead of the copy wey you download for March.docker compose up -d --force-recreatego force container recreation even when configuration and image no change. The flag by itself no request build, butupfit still build when image no dey or pull policy require am. If you use this when wetin you mean na--build, na common dead end.
You fit also put the decision inside the file. As the Compose specification talk am, pull_policy: build mean say Compose go build the image, and rebuild am if e already dey there. Every up go then pay for one build, and na wetin you want for laptop, but e rarely make sense for server.
services:
web:
build: .
image: registry.example.com/acme/web:dev
pull_policy: buildOne more interaction dey important to know. docker compose pull go try pull images for services wey get build section too, and if that pull fail, e go tell you say you must build the image instead. Pass --ignore-buildable to quietly skip those services.
How build cache dey decide your deploy time
The builder dey check each Dockerfile instruction for reusable cached result when that instruction and its inputs no change. For COPY, the inputs include file contents and metadata, but dem no include modification times. Once one layer miss the cache, every later step wey depend on am go rebuild.
That one rule dey decide whether your deploy go take seconds or minutes. Arrange the Dockerfile from things wey rarely change reach things wey change for every commit.
FROM node:22-slim
WORKDIR /app
COPY package.json package-lock.json ./
RUN npm ci
COPY . .
CMD ["node", "server.js"]npm ci dey above COPY . ., so when you edit source file, the install layer remain cached and the build continue from the copy step. If you swap those two lines, one-character change go reinstall every dependency, because COPY . . dey invalidate the layer wey npm ci build on. The same arrangement apply to pip install -r requirements.txt and go mod download.
--no-cache na the correct tool when you suspect say stale layer dey hide your fix. But e no good as default, because e dey throw away the reuse wey correct Dockerfile ordering suppose give you.
One thing wey image set and Compose fit override: Dockerfile CMD na wetin image dey run by default, while command: key for the service go replace am. How command and entrypoint dey work together matter here, because Compose override fit make freshly built image behave exactly like the old one.
Build context and .dockerignore
context: . dey make the project directory available to the builder. If you no set exclusions, e include .git and any data directory wey you keep beside your source, although BuildKit dey skip files wey e no use and transfer only changes incrementally. If build pause for the transferring-context step even though project no change, e mean say the context too large.
A .dockerignore file for the context root dey exclude paths from that transfer. The syntax near resemble .gitignore.
.git
node_modules
*.log
data/
.envE get two benefits. The transfer go smaller, so less time go dey spend sending those files. Also, COPY . . no fit copy .env enter the image again, where anybody wey pull that image fit read am out.
The slow-build problem wey dey grow with time fit come from bind mount. Named volume dey outside your project directory, but bind mount like ./data:/var/lib/postgresql/data dey inside the build context. So your builds go dey slower every week as the database dey grow. One line for .dockerignore go fix am. Bind mounts against named volumes explain the wider trade-off.
Build arguments get smaller version of the same risk. Values wey you pass through args: fit remain for image history or provenance metadata, so put version number there and never put token. Predefined proxy arguments no dey enter build cache and docker history by default, except you reference dem explicitly inside the Dockerfile. Env files and secrets in Compose explain where credentials suppose dey instead.
You suppose build for the VPS or build for another place then pull?
Building for the box wey dey serve your traffic na the default because na the shortest path: git pull, then docker compose up -d --build. E dey okay for small server wey nobody depend on yet. E stop dey okay for two reasons wey you fit measure, plus one reason wey only go show for bad day.
Memory. Build dey run compilers and bundlers beside your live application, and dem na the part wey dey use plenty memory for most stacks. JavaScript bundler or Rust compile fit use all the memory wey dey available for 1 GB VPS. When memory finish, kernel dey choose OOM victim with badness score wey depend on memory use, allocation context, and oom_score_adj; e no simply kill the biggest process. Build fit stop with Killed and exit status 137, or database fit get killed instead and site fit go down during deploy. dmesg -T | grep -i oom dey search kernel log for OOM messages; you need permission to read that log before e fit work.
Disk. Build dey leave image layers and build cache behind. docker system df dey show how much disk dem dey use; BuildKit periodic garbage collection dey reclaim cache according to the policies wey you configure. Use docker image prune to reclaim dangling images, and docker builder prune for cached layers. Full disk dey stop more than build. Database go stop writing too, and that failure cost far pass slow deploy.
Reproducibility. If you no push or export am, image wey you build for server dey exist only for that server. If old image no dey available again, rollback mean say you go checkout old commit and build again. But nobody guarantee say that build go produce wetin you get before, because base tag fit don move and package mirrors fit don move with am. If you build somewhere else and push a tag, rollback become just one edit: point image: to previous tag and run docker compose up -d.
The arrangement wey dey hold up dey straightforward. Your continuous integration go run build and push registry.example.com/acme/web:<git-sha>, while Compose file for VPS go carry image: with no build: key at all. Deployment go then be two commands wey need almost no memory.
docker compose pull
docker compose up -dRun docker login registry.example.com for server to save credentials for pulling private tags.
Keep the build section for development instead of deleting am, for file wey you name yourself.
# compose.dev.yaml
services:
web:
build:
context: .
pull_policy: builddocker compose -f compose.yaml -f compose.dev.yaml up -d --buildName that file compose.dev.yaml, no be compose.override.yaml. Compose dey load override file automatically whenever e dey present, so if stray override file enter server by mistake, e go quietly start building there again. How to layer several Compose files explain how the merge dey resolve each key.
The architecture trap wey dey happen when you build for another place
One platform image dey carry the CPU architecture wey dem use build am. If you build ARM image for Apple Silicon laptop, push am, then use the image for x86_64 VPS, Docker go warn when e dey create container if e use incompatible cached image without explicit platform. Without emulation, the process go fail with exec format error. E fit look like say binary corrupt, but e no be so. Build am for the target architecture directly:
docker buildx build --platform linux/amd64 \
-t registry.example.com/acme/web:1.4.2 --push .The same mismatch fit happen the other way if your laptop na x86 and you run ARM VPS instead of x86 VPS. If you let CI build for the architecture wey you deploy to, you remove the problem. Multi-platform image fit solve this too: Docker go select the variant wey match when e dey pull am.
Wetin to check after deploy
docker compose imagesgo show the image and tag wey dey behind every container wey dey run. If image ID change, na proof say new build dey service.docker compose configgo show the merged file after variable substitution, so you fit read the final image name wey Compose go use before you run anything.docker compose logs -f webfor the first half minute after the swap. Container wey start and exit repeatedly go restart only if im restart policy require am; check the logs to find the cause.docker image lsgo show a CREATED column. Check the build output and deployed image ID too, because creation timestamp alone no prove whether rebuild run.
If you still dey assemble the file wey these checks go use, the basics of a Compose file on a VPS explain the other keys around am, and the Compose command cheat sheet list the remaining subcommands.
FAQ
I fit use build and image for the same service?
Yes, and na this be the normal setup for project wey you build by yourself. When Compose builds from the build: section, e tags the result with the value of image:; if you no set pull_policy, up go try pull first. Na that tag docker compose push sends to a registry, and na wetin another machine pulls. If you no add image: key, Compose still builds, but e names the image after the project and service. E also warns say the missing attribute no allow the image to push.
Why docker compose up no dey pick my Dockerfile change?
Because normal up dey reuse existing image unless you request a build or configure policy wey requires one. E no compare the image with your Dockerfile or source files to decide whether e need rebuild. Run docker compose up -d --build, or run docker compose build web followed by docker compose up --no-deps -d web to replace one service. If you set pull_policy: build for the service, every up go rebuild, and this fit well for development machine.
Wetin be the difference between --build and --force-recreate?
--build builds the image again, then recreates the containers wey their image change. --force-recreate forces container recreation even when configuration and image no change; e no request build by itself. If your change dey for source or Dockerfile, --build na the flag you need. --force-recreate na for resetting the container itself, for example to clear its writable layer while keeping the same image.
Make I build my Docker images for the VPS or somewhere else?
Build somewhere else, then pull a tag once the box dey serve traffic too. Build dey compete with your application for memory. If memory finish, kernel go select a victim with adjustable OOM score, and e fit target the build or your database. Builds also leave cache for disk, although BuildKit dey reclaim am automatically according to its garbage collection policies. Building for the server still dey okay for small project wey no get users. Moving later no cost much if you keep the build: section for development-only Compose file.
How I go stop Docker build cache from filling my disk?
Run docker system df to see how much space your images and build cache dey use separately. docker builder prune removes cached layers, while docker image prune removes dangling images wey earlier builds leave behind. Adding -a removes all unused build cache or all images wey containers no reference, respectively. E no guarantee say the next build go start completely cold. No schedule docker system prune -af --volumes for a server, because e removes stopped containers and unused anonymous volumes. This fit put database data inside anonymous volume at risk during maintenance.