Images and Containers

An image is a read-only package. A container is a running instance of one. That distinction was introduced alongside the virtual machine comparison; this lesson goes into what each one is actually made of, because the practical rules of working with Docker fall straight out of it.

An image has two parts. The first is a stack of read-only layers holding files: a base operating system layer, then whatever each build instruction added. The second is metadata — which command to run on start-up, which user to run it as, which environment variables to set, which port the image documents.

Starting a container adds a thin writable layer on top of that stack and runs the configured command. The image itself never changes. Every write the container performs lands in its own writable layer, which belongs to that container and nothing else.

# Fetch an image without starting anything
docker pull postgres:16

# Three isolated databases from that one image
docker run -d --name test-db-1 -p 5441:5432 \
  -e POSTGRES_PASSWORD=local-dev-placeholder postgres:16
docker run -d --name test-db-2 -p 5442:5432 \
  -e POSTGRES_PASSWORD=local-dev-placeholder postgres:16
docker run -d --name test-db-3 -p 5443:5432 \
  -e POSTGRES_PASSWORD=local-dev-placeholder postgres:16

# Three containers running
docker ps

# Still one image
docker images postgres

• docker pull downloads the layers and stores them locally. It starts nothing — this is the package arriving, not the application running.
• Each docker run creates a separate container from the same layers. They share the read-only layers on disk, so the three cost far less space than three copies would.
• The names and host ports have to differ, because those belong to the containers rather than the image. The port inside each container is 5432 in all three cases.
• docker images still lists one postgres:16 entry. Counting containers and counting images are different questions.

# Write a file inside the first container
docker exec test-db-1 sh -c "echo note > /tmp/reminder.txt"
docker exec test-db-1 cat /tmp/reminder.txt      # note

# The second container never saw it
docker exec test-db-2 cat /tmp/reminder.txt      # No such file or directory

# Stopping keeps the writable layer
docker stop test-db-1 && docker start test-db-1
docker exec test-db-1 cat /tmp/reminder.txt      # note

# Removing the container discards it
docker rm -f test-db-1
docker run -d --name test-db-1 -p 5441:5432 \
  -e POSTGRES_PASSWORD=local-dev-placeholder postgres:16
docker exec test-db-1 cat /tmp/reminder.txt      # gone

• docker exec runs an extra command inside a container that is already running. It is how you look inside one without restarting it.
• The file is invisible to the second container because each container has its own writable layer. Sharing files between containers takes a volume, covered later in the course.
• Stop and start reuse the same container, so the writable layer survives. This is worth knowing, because it makes the next step surprising if you have not separated the two ideas.
• docker rm deletes the container and its writable layer. The replacement is built from the image alone, so it knows nothing about the file. The image never changed at any point.