🐳 The Volume That Stopped Listening to the Image
When a Dockerfile declares a VOLUME at some path, Docker populates that path from the image’s own baked-in content, but only the very first time a volume mounted there is genuinely empty – after that initial population, whatever data already lives in the named volume always takes priority over anything newer baked into a later image rebuild. A team that rebuilds the image with fresh seed data, expecting docker-compose up to pick it up through the same named volume, instead keeps seeing the original data from months ago, because the volume was already populated once and Docker has no mechanism to refresh it from a newer image automatically.
🔎 The Problem
# Dockerfile
FROM postgres:16
COPY ./seed-data /seed
VOLUME /var/lib/postgresql/data
# docker-compose.yml
services:
db:
build: .
volumes:
- db-data:/var/lib/postgresql/data
volumes:
db-data:
# First run: db-data is empty, so Docker populates it from the
# freshly built image's content - works exactly as expected.
$ docker compose up -d
# Months later: seed data is updated, image is rebuilt...
$ docker compose build
$ docker compose up -d
# ...but db-data already has content from the FIRST run. Docker
# only seeds a volume once, when it's empty - the rebuilt image's
# newer seed data is never copied in, with no warning that this
# is what happened.
✅ Fix: Decide Deliberately When a Volume Should Reset
- Remove the named volume explicitly – docker volume rm, or docker compose down -v – whenever a rebuild is genuinely meant to refresh seed data, rather than assuming a rebuild alone will update an already-populated volume.
- Separate persistent application data from seed or reference data that should always come from the image, keeping the latter in a bind mount or baked directly into the image rather than a named volume that only gets seeded once.
- Document explicitly, wherever the Dockerfile’s VOLUME instruction is used for seeding, that it only takes effect the first time the volume is created – so a teammate rebuilding months later doesn’t assume an update to seed data will automatically show up.
⚠️ Why This Is Easy to Miss
- The first time anyone sets this up, everything works exactly as expected – the volume is empty, Docker seeds it from the image, and there’s no reason yet to suspect that behavior won’t repeat on the next rebuild.
- A rebuild appears to succeed completely – the build logs show the new seed data being copied into the image without any error – so there’s nothing in the build process itself suggesting the running container’s actual volume won’t reflect any of it.
A Docker volume gets seeded from the image exactly once – after that, the volume’s own data always wins, no matter how many times you rebuild the image underneath it.
