Docker Images and Containers — Why Unpinned Tags Break

Building an Image with Dockerfile

A Dockerfile is a recipe for building an image. Each instruction creates a new layer — a filesystem diff on top of the previous layer. Docker caches layers and only rebuilds from the first changed instruction downward. Understanding this is the single most important optimization for build speed.

The layer caching principle: if a layer has not changed and all preceding layers are cached, Docker reuses the cached layer instantly. Dependencies change rarely. Code changes frequently. Put rare changes first.

The .dockerignore file controls what gets sent to the Docker Daemon as build context. Without it, your entire project directory — including .git (often 100MB+), node_modules, __pycache__, and .env files with secrets — is sent on every build. This slows builds and risks secret exposure.

# Best practices Dockerfile for a Python FastAPI app
FROM python:3.12-slim  # slim variant: much smaller than full python image

WORKDIR /app

# Copy requirements FIRST for layer caching
# If code changes but requirements don't, this layer is cached
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Now copy application code
COPY . .

# Run as non-root for security
RUN useradd -m appuser
USER appuser

# Document the port (does not actually publish it)
EXPOSE 8000

CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8000"]

Running Containers

A container is a running instance of an image with an additional thin writable layer. Multiple containers can run from the same image — each with its own writable layer, environment variables, and port mappings. The image itself never changes.

The container lifecycle: create (allocate resources), start (run the CMD process), stop (send SIGTERM, wait, then SIGKILL), remove (delete the writable layer). The --rm flag automates removal on stop.

Port mapping confusion: -p HOST:CONTAINER maps the host port to the container port. Your application inside the container must bind to 0.0.0.0 (all interfaces), not 127.0.0.1 (localhost). Binding to localhost inside the container means the application only accepts connections from within the container — the host port mapping becomes useless.

The difference between stop and kill: docker stop sends SIGTERM (graceful shutdown, 10-second default timeout), then SIGKILL if the process does not exit. docker kill sends SIGKILL immediately. Always use stop in production — it gives your application time to flush logs, close database connections, and complete in-flight requests.

# Run a container
docker run -p 8000:8000 myapp:1.0

# Flags:
# -p HOST_PORT:CONTAINER_PORT   — publish port
# -d                            — detached (background)
# -e DATABASE_URL=postgres://.. — environment variable
# -v /host/path:/container/path — bind mount volume
# --name my-container           — give it a name
# --rm                          — remove when stopped

docker run -d \
  --name api-server \
  -p 8000:8000 \
  -e DATABASE_URL=postgres://localhost/mydb \
  --rm \
  myapp:1.0

# Container lifecycle
docker ps          # running containers
docker ps -a       # all containers (including stopped)
docker stop api-server     # graceful stop (SIGTERM)
docker kill api-server     # force stop (SIGKILL)
docker rm api-server       # remove stopped container
docker logs api-server     # view logs
docker logs -f api-server  # follow logs
docker exec -it api-server bash  # shell into running container

Volumes and Networking

Containers are ephemeral — when a container stops, its writable layer is discarded. For state that must survive container restarts (databases, file uploads, logs), you need volumes.

Named volumes: Managed by Docker. The storage location is controlled by the Docker Daemon (typically /var/lib/docker/volumes/). Survives docker compose down. Destroyed only by docker compose down -v or docker volume rm. Best for databases.

Bind mounts: Mount a host directory into the container. Changes on either side are reflected immediately. Great for development (hot reload). Not recommended for production — ties the container to a specific host path and breaks portability.

Networking: Containers on the same Docker network can reach each other by container name. Docker's embedded DNS server (127.0.0.11) resolves container names to internal IPs. The host-mapped port (left side of -p) is for external access. Container-to-container communication uses the container port directly — never the host port.

Volume lifecycle gotcha: Named volumes persist data even after the container is removed. This is a feature for databases but a trap for test environments — stale data from previous test runs can cause non-deterministic test failures. Use docker compose down -v in CI to ensure clean state.

# Named volumes: data persists after container is removed
docker volume create postgres-data
docker run -d \
  -v postgres-data:/var/lib/postgresql/data \
  -e POSTGRES_PASSWORD=secret \
  postgres:16

# Container networking: containers on same network can reach each other by name
docker network create myapp-network

docker run -d --name db --network myapp-network postgres:16
docker run -d \
  --name api \
  --network myapp-network \
  -e DATABASE_URL=postgres://db/myapp \
  myapp:1.0
# 'api' container reaches 'db' by hostname 'db'

# Image management
docker image ls          # list images
docker image rm myapp:1.0
docker system prune -a   # remove all unused images, containers, networks