Subscribe

Docker from zero: images, containers, layers and volumes

A hands-on start with Docker: run containers, keep Postgres data in a named volume, use bind mounts, build an image, read its layers with docker history, see why a deleted file still costs space, and push to a registry.

Docker from zero: images, containers, layers and volumes

Docker is easy to start with and easy to get wrong in quiet ways. People run containers for months without knowing where their data actually lives, or why an image is 300 MB when the app is 13. Most of that comes down to four words: image, container, layer and volume.

In this blog we will go through those four by running things, not by drawing boxes. We'll start a container, run Postgres with data that survives the container, build an image for shorty (the URL shortener from Designing a URL shortener from requirements to scale), look at its layers with docker history, and push it to a registry. Level is beginner. You need Docker installed and a terminal, nothing else.

I ran everything here with Docker 29.8.2 on a Mac, through OrbStack, so the Linux side is arm64. Docker Desktop or Docker on Linux will print the same things, give or take some IDs and sizes.

Images and containers

An image is a read-only template: a filesystem plus some settings like which command to run. A container is a running (or stopped) instance of an image, with its own thin writable layer on top. One image, many containers. The same way one binary can run as many processes.

docker run --rm debian:trixie-slim sh -c 'echo "hello from $(hostname)"; head -2 /etc/os-release'
hello from 0b2e68b6e5d9
PRETTY_NAME="Debian GNU/Linux 13 (trixie)"
NAME="Debian GNU/Linux"

That's a whole Debian userland, started, ran one command and gone. The hostname is the container's ID. --rm deletes the container when it exits, otherwise stopped containers pile up in docker ps -a forever. I add --rm to almost every throwaway run out of habit.

Note what it isn't. It's not a VM. There's no Debian kernel in there, the container uses the host's kernel (on a Mac, the kernel of the small Linux VM that Docker Desktop or OrbStack runs for you). It's just processes with their own view of the filesystem, network and process list.

Running something real

Let's run Postgres in the background with -d, and give it a name so we don't have to copy IDs around.

docker run -d --name pg -e POSTGRES_PASSWORD=devonly \
  -v pgdata:/var/lib/postgresql postgres:18-alpine
docker ps
docker logs --tail 3 pg
NAMES     IMAGE                STATUS         PORTS
pg        postgres:18-alpine   Up 4 seconds   5432/tcp
2026-11-19 08:02:31.655 UTC [1] LOG:  listening on Unix socket "/run/postgresql/.s.PGSQL.5432"
2026-11-19 08:02:31.658 UTC [65] LOG:  database system was shut down at 2026-11-19 08:02:31 UTC
2026-11-19 08:02:31.660 UTC [1] LOG:  database system is ready to accept connections

The "was shut down" line looked odd to me the first time. It's normal: on the first start the image creates the database, stops that temporary server and starts the real one.

-e sets an environment variable. -v pgdata:/var/lib/postgresql is the important bit, we'll come to it in a minute. docker logs shows whatever the main process writes to stdout and stderr. That's why apps in containers should log to stdout and not to files.

To run a command inside the running container, use docker exec:

docker exec pg psql -U postgres -c "CREATE TABLE notes (body text)" \
  -c "INSERT INTO notes VALUES ('written before rm')"

Add -it (docker exec -it pg psql -U postgres) when you want an interactive session with a prompt.

Containers are disposable, volumes are not

Now delete the container. Not stop, delete.

docker rm -f pg
docker run -d --name pg2 -e POSTGRES_PASSWORD=devonly \
  -v pgdata:/var/lib/postgresql postgres:18-alpine
docker exec pg2 psql -U postgres -c "SELECT * FROM notes"
       body
-------------------
 written before rm
(1 row)

The container is gone but the row survived, because it was never in the container. It was in the volume pgdata, which Docker created on the first run and which lives until you remove it yourself:

docker volume inspect pgdata --format '{{.Driver}} {{.Mountpoint}}'
local /var/lib/docker/volumes/pgdata/_data

That path is inside Docker's Linux VM on a Mac, not on your Mac's disk where you could ls it. Without -v, the data would have gone into the container's writable layer and died with docker rm.

One thing that changed recently and bites people: Postgres 18 images keep their data under /var/lib/postgresql/18/docker, so the volume goes on /var/lib/postgresql. Older guides mount /var/lib/postgresql/data. Inside pg2, ls /var/lib/postgresql printed just 18, which is how I'd check.

This is the same idea my blog runs on. Ghost and MySQL are containers that get replaced on every upgrade, the data sits in volumes, as in Migrating a Ghost-CLI blog to Docker Compose with Caddy and MySQL 8. And because volumes are only as safe as the disk under them, they get backed up nightly, see Nightly MySQL and content backups to S3 with a systemd timer.

Clean up:

docker rm -f pg2
docker volume rm pgdata

Bind mounts

A volume is storage Docker manages. A bind mount is a folder from your machine mounted into the container. Good for config files, seed data, source code during development. Here's shorty's seed folder, mounted read-only:

docker run --rm -v "$PWD/seed:/seed:ro" debian:trixie-slim sh -c 'ls -l /seed; touch /seed/x'
total 4
-rw-r--r-- 1 root root 285 Nov 19 06:41 seed.sql
touch: cannot touch '/seed/x': Read-only file system

The :ro did its job. My rule of thumb is: volumes for data the container owns (databases), bind mounts for files I own and edit (config, code). Bind mounts on a Mac also go through the VM's file sharing, so they are slower than volumes for heavy disk work. Don't put a database on one.

Building an image

An image is built from a Dockerfile. shorty's is a multi-stage one: a Go build stage, then only the binary copied into a tiny distroless image. I explained the multi-stage idea in Creating a multi-stage Dockerfile for a Go web service, so here I'll only build it:

docker build -t shorty:dev .

-t gives it a name and a tag, shorty and dev. The second time I ran it, it took 3.5 seconds, every step said CACHED. Docker reuses a step's result as long as the step and everything before it hasn't changed. That's the cache, and it's made of layers.

What a layer is

Each filesystem-changing instruction in a Dockerfile (RUN, COPY, ADD) adds a layer: a diff of files added, changed or removed. The image is the stack of those diffs. docker history shows the stack, newest on top:

docker history shorty:dev
IMAGE          CREATED         CREATED BY                                      SIZE      COMMENT
536b23e30c4f   4 minutes ago   CMD ["/shorty" "serve"]                         0B        buildkit.dockerfile.v0
<missing>      4 minutes ago   HEALTHCHECK {Test:[CMD /shorty healthcheck] …   0B        buildkit.dockerfile.v0
<missing>      4 minutes ago   EXPOSE [8080/tcp]                               0B        buildkit.dockerfile.v0
<missing>      4 minutes ago   USER 65532:65532                                0B        buildkit.dockerfile.v0
<missing>      4 minutes ago   COPY /out/shorty /shorty # buildkit             13.5MB    buildkit.dockerfile.v0
<missing>      N/A             bazel build //common:cacerts_debian13_arm64_…   270kB
<missing>      N/A             bazel build //common:os_release_debian13        4.1kB
<missing>      N/A             bazel build //static:nsswitch                   4.1kB
<missing>      N/A             bazel build //common:tmp                        0B
<missing>      N/A             bazel build //common:group                      4.1kB
<missing>      N/A             bazel build //common:home                       0B
<missing>      N/A             bazel build //common:passwd                     4.1kB
<missing>      N/A             bazel build //common:rootfs                     0B
<missing>      N/A             bazel build @trixie//media-types/arm64:data_…   111kB
<missing>      N/A             bazel build @trixie//tzdata-legacy/arm64:dat…   3.1MB
<missing>      N/A             bazel build @trixie//tzdata/arm64:data_statu…   2.34MB
<missing>      N/A             bazel build @trixie//netbase/arm64:data_stat…   45.1kB
<missing>      N/A             bazel build @trixie//base-files/arm64:data_s…   582kB

A few things to read from it. The bottom rows are the distroless base image, built by Google with Bazel, mostly certificates and time zone data. Our only real layer is the COPY of the 13.5 MB binary. CMD, USER, EXPOSE and HEALTHCHECK are 0B, they're settings, not files. And the whole Go build stage with its Go toolchain isn't there at all. That's the point of multi-stage. <missing> just means those layers don't have their own image ID locally, it's not an error.

docker image ls shorty reports 25.6 MB in total.

A deleted file still costs you

Layers only ever add. Deleting a file in a later layer hides it, the bytes are still in the earlier layer. This tiny Dockerfile shows it:

FROM debian:trixie-slim
RUN head -c 50000000 /dev/urandom > /big.bin
RUN rm /big.bin
CMD ["ls", "-l", "/"]
docker build -t layers:demo layers/
docker history layers:demo --format 'table {{.CreatedBy}}\t{{.Size}}'
CREATED BY                                      SIZE
CMD ["ls" "-l" "/"]                             0B
RUN /bin/sh -c rm /big.bin # buildkit           0B
RUN /bin/sh -c head -c 50000000 /dev/urandom…   50MB
# debian.sh --arch 'arm64' out/ 'trixie' '@1…   109MB

docker run --rm layers:demo ls /big.bin says no such file. And still the 50 MB layer gets pulled by everyone who uses the image. docker image ls showed 239 MB for it against 141 MB for plain debian:trixie-slim, so the difference was close to 100 MB, not 50. My guess is it counts the layer twice on this setup (Docker 29 here uses the containerd image store, which keeps the compressed blob and the unpacked files), and random bytes don't compress at all. Either way: download, use and delete in the same RUN, or better, in a build stage you throw away.

Tagging and pushing

A tag is just a name pointing at an image. To push, the name has to include the registry. To try it without any cloud account, run a registry locally (it's an image too):

docker run -d --rm --name registry -p 127.0.0.1:5077:5000 \
  -v registry-data:/var/lib/registry registry:3
docker tag shorty:dev localhost:5077/shorty:0.1.0
docker push localhost:5077/shorty:0.1.0
curl -s 127.0.0.1:5077/v2/shorty/tags/list
0.1.0: digest: sha256:536b23e30c4fa530f96a8c1524973adc6094e3e1d5a88a08541067a0bd9baa52 size: 856
{"name":"shorty","tags":["0.1.0"]}

My first try used port 5055, and the curl got back an S3 "NoSuchBucket" error in XML. Confusing for a minute. Something else on my Mac (a Python process) already listened on 127.0.0.1:5055, and docker run didn't complain about it. lsof -nP -iTCP:5055 -sTCP:LISTEN showed the culprit, I moved to 5077. Ports get a whole post of their own in the networking part.

For real use, the registry is ECR, GHCR or Docker Hub, and you docker login first. Same tag and push.

Cleaning up

docker ps -a
docker volume ls
docker rm -f registry
docker volume rm registry-data
docker system df

docker system df shows how much space images, containers, volumes and build cache take. There's also docker system prune, which is handy on your own laptop. Read what it says it will delete before you say yes, especially the volumes part.

There we have it. Next time you see a Dockerfile, read each line as "this adds a layer" or "this is a setting", and it starts to make sense. Once the image starts, it's the CMD that runs, which matters more than it looks on ECS, see Why your Docker image should use CMD and not ENTRYPOINT when ECS overrides the command.