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.
Quick reference — reach for these first
docker build -t NAME:TAG .Build from the Dockerfile in . and tag it; add --no-cache to ignore layer cache.docker run -d -p HOST:CONTAINER --name NAME IMAGEStart in background, publish a port, name it for easy reference.docker logs -f NAMEStream stdout/stderr live; add --tail 100 to start from the last 100 lines.docker exec -it NAME shOpen an interactive shell in a running container (use bash if present).docker compose up -d --buildRebuild changed images and start the whole stack detached.Image & container lifecycle, with Compose
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
| Task | Command | Verify |
|---|---|---|
| Confirm which daemon/context you are about to act on | docker 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 image | docker 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 volume | docker 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 container | docker run --rm -it IMAGE sh | Container is auto-removed on exit (not left in `docker ps -a`). |
| List running containers | docker ps | Target container appears with STATUS 'Up ...'. |
| List ALL containers incl. stopped (read exit codes) | docker ps -a | Stopped containers show 'Exited (CODE)'; CODE 0 is clean, non-zero crashed. |
| Follow a running container's logs | docker logs -f --tail 100 NAME | Live output streams; Ctrl-C detaches without stopping the container. |
| Open a shell in a running container | docker exec -it NAME sh | You get a prompt inside the container; `hostname` matches the container id. |
| Inspect full config / IP / mounts / health | docker inspect NAME | JSON includes .NetworkSettings, .Mounts, and .State.Health when a healthcheck is set. |
| List images and reclaimable space | docker images && docker system df | Shows image sizes and how much is reclaimable before pruning. |
| Reclaim unused images/containers/networks — DELETES DATA | docker system prune -a | Prompts 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 rebuild | docker compose up -d --build | `docker compose ps` lists every service as running/healthy. |
| Tear the stack down incl. named volumes — DELETES DATA | docker compose down -v | Reports 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
docker context show
# defaultdocker ps -a --filter name=api
# NAMES STATUS
# api Exited (1) 4 seconds agodocker logs api
# Error: environment variable PORT is requireddocker rm api && docker run -d -p 8080:3000 -e PORT=3000 --name api myimg:latest
# a1b2c3d4e5f6docker ps --filter name=api
# NAMES STATUS PORTS
# api Up 12 seconds (healthy) 0.0.0.0:8080->3000/tcpTroubleshooting — symptom → first check → next check
| Symptom | First check | Establishes | Next 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 volume | docker 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 CLI reference (docker run, ps, logs, exec, inspect)docs.docker.com
- docker build command referencedocs.docker.com
- Docker Compose CLI reference (up, down, logs)docs.docker.com
- Dockerfile HEALTHCHECK instructiondocs.docker.com
- Networking in Compose (service discovery by name)docs.docker.com
Docker Engine 27.x with Compose v2 (`docker compose`, space) on Linux/macOS; legacy `docker-compose` v1 (hyphen) flags differ slightly.