← All cheatsheets

Containers

Docker & Compose — build, run, debug containers

Build images, run and inspect containers, follow logs, exec in, orchestrate multi-service stacks with Compose, and debug the usual failures — exits, port clashes, auth, disk, networking, and volume permissions.

Docs-checkeddockercomposecontainersimagesdebugging

Quick reference — reach for these first

Build imagedocker build -t NAME:TAG .Build from the Dockerfile in . and tag it; add --no-cache to ignore layer cache.
Run detacheddocker run -d -p HOST:CONTAINER --name NAME IMAGEStart in background, publish a port, name it for easy reference.
Follow logsdocker logs -f NAMEStream stdout/stderr live; add --tail 100 to start from the last 100 lines.
Shell insidedocker exec -it NAME shOpen an interactive shell in a running container (use bash if present).
Compose updocker compose up -d --buildRebuild changed images and start the whole stack detached.

Image & container lifecycle, with Compose

Docker image and container lifecycle with ComposeA Dockerfile is built into an image, the image is run as a container, and the container is observed with logs, exec, and inspect. Below, a compose file brings up several services on a shared network.Dockerfileimagecontainercompose.yamllogs -f · exec -itinspectweb · db · cacheone network,DNS by service namebuild -trun -d -pcompose up -d --build

Text equivalent: A Dockerfile is turned into an image by 'docker build -t', the image is started as a container by 'docker run -d -p', and the running container is observed with logs -f, exec -it, and inspect. Separately, a compose.yaml is brought up by 'docker compose up -d --build' into multiple services (web, db, cache) that share one network and resolve each other by service name.

Common tasks

Task · Command · Verify

TaskCommandVerify
Confirm which daemon/context you are about to act ondocker context show && docker info --format '{{.Name}} {{.ServerVersion}}'Prints the expected context (e.g. default/desktop-linux) before you build, run, or prune.
Build and tag an imagedocker build -t NAME:TAG .Ends with 'naming to docker.io/library/NAME:TAG'; `docker images NAME` lists it.
Force a clean rebuild (ignore cache)docker build --no-cache -t NAME:TAG .Each step reruns (no 'CACHED'); use when a base image or apt package changed.
Run detached with port, env, and volumedocker run -d -p 8080:80 -e KEY=VALUE -v DATA:/var/lib/app --name NAME IMAGE`docker ps` shows the container Up and 0.0.0.0:8080->80/tcp.
Run a one-shot throwaway containerdocker run --rm -it IMAGE shContainer is auto-removed on exit (not left in `docker ps -a`).
List running containersdocker psTarget container appears with STATUS 'Up ...'.
List ALL containers incl. stopped (read exit codes)docker ps -aStopped containers show 'Exited (CODE)'; CODE 0 is clean, non-zero crashed.
Follow a running container's logsdocker logs -f --tail 100 NAMELive output streams; Ctrl-C detaches without stopping the container.
Open a shell in a running containerdocker exec -it NAME shYou get a prompt inside the container; `hostname` matches the container id.
Inspect full config / IP / mounts / healthdocker inspect NAMEJSON includes .NetworkSettings, .Mounts, and .State.Health when a healthcheck is set.
List images and reclaimable spacedocker images && docker system dfShows image sizes and how much is reclaimable before pruning.
Reclaim unused images/containers/networks — DELETES DATAdocker system prune -aPrompts y/N, then reports 'Total reclaimed space'; removes all images not used by a container — re-pull/rebuild needed.
Bring the Compose stack up with a rebuilddocker compose up -d --build`docker compose ps` lists every service as running/healthy.
Tear the stack down incl. named volumes — DELETES DATAdocker compose down -vReports containers, networks, and volumes removed; stack data is gone (omit -v to keep volumes).

A container keeps exiting — find the exit code, read the logs, fix, verify healthy

exit-code

1
The 'api' container disappears from `docker ps` seconds after starting — confirm the context first.
docker context show
# default
2
List all containers (including stopped) to read the exit code.
docker ps -a --filter name=api
# NAMES  STATUS
# api    Exited (1) 4 seconds ago
3
Non-zero exit means it crashed — read why from its logs.
docker logs api
# Error: environment variable PORT is required
4
Fix the cause (missing env), remove the dead container, and re-run with the env set.
docker rm api && docker run -d -p 8080:3000 -e PORT=3000 --name api myimg:latest
# a1b2c3d4e5f6
5
Verify it is up and, if a HEALTHCHECK is defined, that it reports healthy.
docker ps --filter name=api
# NAMES  STATUS                    PORTS
# api    Up 12 seconds (healthy)   0.0.0.0:8080->3000/tcp

Troubleshooting — symptom → first check → next check

SymptomFirst checkEstablishesNext check
Container exits immediately after `docker run`docker ps -a (read the Exited (CODE) status)Whether the process crashed (non-zero code) or just had no long-running foreground process (code 0).`docker logs NAME` for the stack trace; ensure CMD/ENTRYPOINT runs a foreground process (not a backgrounded one that lets PID 1 exit).
'Bind for 0.0.0.0:PORT failed: port is already allocated'docker ps --filter publish=PORT (and `lsof -i :PORT` for host processes)Which container or host process already holds the port.Stop the holder, or publish a different host port: `-p OTHER:CONTAINER`.
'pull access denied' / 'requires login' / 'repository does not exist'docker login REGISTRY (Docker Hub if omitted)Whether it is an auth failure vs a wrong image path/tag.Re-run pull after login; verify the full REGISTRY/NAMESPACE/IMAGE:TAG and that your account can access a private repo.
Build/pull fails with 'no space left on device'docker system df (see reclaimable build cache, images, volumes)How much Docker is holding and what is reclaimable.`docker builder prune` then `docker system prune -a` (DELETES unused images/cache); remove dangling volumes with `docker volume prune` — check volumes hold no needed data first.
Service A can't reach service B by name (connection refused / DNS)docker network inspect NETWORK (confirm both containers are attached)Whether they share a user-defined network — Compose makes one automatically; plain `docker run` on the default bridge has no name-based DNS.Use the service name as hostname and the container's internal port; put both on the same user-defined/compose network. Confirm B actually listens on 0.0.0.0, not 127.0.0.1.
'permission denied' writing to a mounted volumedocker exec -it NAME ls -ln /MOUNT (compare the owner UID to the container user)A UID/GID mismatch between the host files (bind mount) or volume and the process user inside.chown the path to the container's UID, run the container as that user (`--user UID:GID`), or use a named volume so Docker initializes ownership from the image.

References

Docker Engine 27.x with Compose v2 (`docker compose`, space) on Linux/macOS; legacy `docker-compose` v1 (hyphen) flags differ slightly.