What is the difference between a Docker image and a container?

An image is a read-only blueprint built from a Dockerfile — it contains the filesystem layers and metadata. A container is a running instance of an image with its own writable layer, network, and process space. One image can spawn many containers.

How do I run a Docker container in the background?

Use docker run -d to detach. Add -p 8080:8000 to publish ports and --name app to give it a stable name. Check it with docker ps and follow its logs with docker logs -f app.

What is Docker Compose used for?

Docker Compose defines and runs multi-container applications with a single docker-compose.yml file. It manages service dependencies, shared networks, and named volumes. Use docker compose up -d --build to start everything, and docker compose down -v to tear it down.

How do I reduce Docker image size?

Use multi-stage builds to discard build tooling from the final image, choose a minimal base image (alpine or distroless), combine RUN commands to squash layers, and add a .dockerignore file to exclude node_modules and .git from the build context.

How do I persist data in Docker?

Use named volumes (docker volume create my-vol) for managed persistence, or bind mounts (-v $(pwd)/data:/app/data) to map a host directory into the container. Named volumes are preferred for databases; bind mounts are convenient for development hot-reload.

How do I access a running container shell?

Run docker exec -it CONTAINER_ID sh (or bash if available). Use docker exec -it $(docker ps -qf name=app) sh to resolve the container by name. For a stopped container, start it with docker start -ai CONTAINER_ID to attach to its original command.

Docker Cheatsheet: Build, Compose, Volumes

Start hereQuick start · 6 you’ll reach for daily

Builddocker build -t app .

Rundocker run -p 8000:8000 app

Shell indocker exec -it CID sh

Tail logsdocker logs -f CID

Compose updocker compose up -d --build

Clean diskdocker system prune -af

Target versions · paceVersions

Targets: Docker Engine ≥ 25 BuildKit (default) Compose v2

This sheet assumes docker compose (Go plugin) — not the deprecated docker-compose Python tool. BuildKit is the default builder; the --mount=type=cache and --platform flags assume it’s on.

smoke test · daily-loop commandsSetup

bash

# Sanity check
docker version                     # client + daemon versions
docker info                        # storage driver, registry mirrors

# Daily quick-loop
docker run --rm -it alpine sh                              # throwaway shell
docker run --rm -p 8080:80 nginx:alpine                    # publish a port
docker run --rm -e ENV=prod -v $(pwd):/app -w /app node:22 # env + bind mount

# Auth to a registry
docker login ghcr.io                # GitHub container registry
docker logout ghcr.io

# Clean up reclaimable disk
docker system df                   # show usage
docker system prune -af --volumes  # everything not in use

build artefactsImages

docker images	List local images.
docker pull alpine:3.20	Fetch an image. Pin the tag.
docker build -t app:dev .	Build from the Dockerfile in `.`.
docker build -f infra/Dockerfile -t app:dev .	Custom Dockerfile path.
docker build --target build -t app:build .	Stop at a named multi-stage target.
docker build --build-arg VER=1.2 .	Pass an `ARG`.
docker tag app:dev ghcr.io/me/app:0.4.1	Add a registry-qualified tag.
docker push ghcr.io/me/app:0.4.1	Push to a registry.
docker rmi IMAGE	Remove an image.
docker image prune -a	Remove dangling + unused images.
docker history IMAGE	Layer-by-layer breakdown.
docker image inspect IMAGE	Full metadata as JSON.

running instancesContainers

docker run IMAGE	Create + start. Foreground.
docker run --rm IMAGE	Auto-remove on exit. Default for one-shots.
docker run -d IMAGE	Detached / background.
docker run -it IMAGE sh	Interactive shell.
docker run -p 8000:8000 IMAGE	Publish container:host port.
docker run -e KEY=val IMAGE	Single env var. Repeat the flag.
docker run --env-file .env IMAGE	Load env vars from a file.
docker run --name api IMAGE	Pin a friendly name.
docker run --restart unless-stopped IMAGE	Restart policy for prod.
docker run -v $(pwd):/app -w /app IMAGE	Bind mount cwd. Common dev pattern.
docker ps	Running containers.
docker ps -a	Include stopped.
docker logs -f --tail 100 NAME	Follow logs.
docker exec -it NAME sh	Shell inside a running container.
docker stop NAME · docker rm NAME	Stop, then remove.
docker cp NAME:/path ./out	Copy files in or out.
docker stats	Live CPU / mem per container.
docker inspect NAME	Full container metadata.

instructions referenceDockerfile

FROM python:3.13-slim AS build	Base image. `AS` names a stage.
ARG VER=1.2.3	Build-time variable. Available only during build.
ENV PYTHONUNBUFFERED=1	Runtime env var. Persists in the image.
WORKDIR /app	Sets cwd for subsequent steps; creates it.
COPY src/ /app/src/	Copy from build context. Respects `.dockerignore`.
ADD url\|tar dest	COPY + auto-extract tars + URL support. Prefer `COPY`.
RUN apt-get update && apt-get install -y …	Shell exec at build time. Chain to keep layers small.
RUN --mount=type=cache,target=/root/.cache/pip …	BuildKit cache mount. Survives across builds.
USER app	Drop root. Pair with `RUN useradd -m`.
EXPOSE 8000	Documentation only — doesn’t publish.
VOLUME ["/data"]	Mark a path as an anonymous volume.
ENTRYPOINT ["python", "-m"]	The thing always run.
CMD ["myapp"]	Default args. Override at `docker run` time.
HEALTHCHECK --interval=30s CMD curl -f … \|\| exit 1	Container-level liveness probe.

bash

# syntax=docker/dockerfile:1.7
# --- build stage ---
FROM python:3.13-slim AS build
WORKDIR /app

# Use BuildKit cache for pip — survives across builds
RUN --mount=type=cache,target=/root/.cache/pip \
    --mount=type=bind,source=requirements.txt,target=requirements.txt \
    pip install --prefix=/install -r requirements.txt

COPY . .

# --- runtime stage ---
FROM python:3.13-slim AS runtime
ENV PYTHONDONTWRITEBYTECODE=1 PYTHONUNBUFFERED=1
RUN useradd -m -u 10001 app
WORKDIR /app
COPY --from=build /install /usr/local
COPY --from=build /app /app
USER app
EXPOSE 8000
HEALTHCHECK --interval=30s --timeout=3s CMD curl -fsS localhost:8000/health || exit 1
CMD ["python", "-m", "myapp"]

smaller images, faster buildsBuildKit & multi-stage builds

# syntax=docker/dockerfile:1.7	Pin the frontend. Unlocks newer features.
FROM … AS build / FROM … AS runtime	Two stages: build artefacts, ship only what runs.
COPY --from=build /app /app	Pull artefacts from the build stage. Skips build tools.
RUN --mount=type=cache,target=…	Persistent package-manager cache.
RUN --mount=type=secret,id=npm,target=…	Inject secrets at build time without baking them in.
RUN --mount=type=bind,source=requirements.txt,target=…	Read context files without `COPY`.
docker buildx build --platform linux/amd64,linux/arm64	Cross-arch image. Push to registry as manifest list.
--cache-from / --cache-to type=registry,ref=…	Share cache across CI runners.
.dockerignore	Excludes from build context. Add `.git`, `.venv`, `node_modules`.

Order layers by change frequency. Put COPY requirements.txt + pip install before COPY .. Source edits shouldn’t bust the dependency layer.

persistenceVolumes

docker volume create data	Named volume managed by Docker.
docker run -v data:/var/lib/data IMAGE	Mount named volume.
docker run -v $(pwd):/app IMAGE	Bind mount host path. Dev-only.
--mount type=bind,source=…,target=…,readonly	Modern syntax. Explicit type.
--tmpfs /scratch	RAM-backed scratch dir. Disappears with the container.
docker volume ls / inspect / rm	Manage volumes.
docker volume prune	Remove unused volumes. Read this before running.

Bind mounts shadow the in-image contents at the same path. If /app in the image has files and you bind-mount over it, those files vanish for the container.

container connectivityNetworks

docker network ls	Default networks: `bridge`, `host`, `none`.
docker network create app	User-defined bridge. Containers can DNS each other by name.
docker run --network app --name db postgres	Attach a container to a network.
docker network connect app api	Attach a running container.
--network host	Share host network. Linux only; bypasses port publishing.
--add-host host.docker.internal:host-gateway	Reach the host machine from inside a container.
-p 127.0.0.1:8000:8000	Publish only to localhost. Important for dev daemons.

multi-service workflowsCompose

docker compose up -d	Bring services up, detached.
docker compose up --build	Force rebuild before up.
docker compose up --watch	File-sync dev loop using `develop.watch`.
docker compose down -v	Stop + remove, including volumes. Destructive.
docker compose ps	Status across services.
docker compose logs -f api	Follow one service.
docker compose exec api sh	Shell into a service container.
docker compose run --rm api pytest	One-off command in a fresh container.
docker compose config	Resolve + print the merged config.
--profile dev	Activate optional services tagged with a profile.

yaml

# compose.yaml — modern format (no `version:` key needed)
services:
  api:
    build: .
    image: myorg/api:dev
    ports: ["8000:8000"]
    environment:
      DATABASE_URL: postgres://app:app@db:5432/app
    depends_on:
      db: { condition: service_healthy }
    develop:
      watch:
        - { action: sync,    path: ./src,        target: /app/src }
        - { action: rebuild, path: requirements.txt }
    restart: unless-stopped

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: app
      POSTGRES_PASSWORD: app
      POSTGRES_DB: app
    volumes: ["pgdata:/var/lib/postgresql/data"]
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U app"]
      interval: 5s
      retries: 5

volumes:
  pgdata:

distributionRegistries

docker login ghcr.io	Auth. Token in `~/.docker/config.json`.
docker tag local:dev ghcr.io/me/app:0.4.1	Always tag before push.
docker push ghcr.io/me/app:0.4.1	Push the named tag.
docker pull ghcr.io/me/app@sha256:…	Pull by digest. Most reproducible.
docker buildx imagetools inspect IMAGE	Multi-arch manifest details.
docker scout cves IMAGE	CVE scan (Docker Desktop’s built-in).

when it’s on fireDebugging

docker logs --tail 200 --since 10m NAME	Bound log volume; `--timestamps` for clock.
docker exec -it NAME sh	Shell in. Use `bash` only if present.
docker run --rm -it --network container:NAME nicolaka/netshoot	Network diag in target container’s namespace.
docker run --rm -it --pid container:NAME alpine sh	Share PID namespace. Inspect target’s processes.
docker inspect --format '{{json .State}}' NAME	Exit codes, OOM, restart counts.
docker top NAME	Processes inside the container.
docker events --filter container=NAME	Live event stream.
docker system df -v	Find which image / volume is hogging disk.

build → push → runEnd-to-end · Build, push, run

Multi-arch BuildKit build, push to GHCR, run locally with env + restart policy, tail logs, tear down.

bash

# Build, tag, run, ship — the full local-to-registry loop.

# 1 · Build for multiple platforms with BuildKit
docker buildx build \
  --platform linux/amd64,linux/arm64 \
  --tag ghcr.io/me/api:0.4.1 \
  --tag ghcr.io/me/api:latest \
  --push .

# 2 · Inspect the result
docker image inspect ghcr.io/me/api:0.4.1 --format '{{.Size}}'
docker history ghcr.io/me/api:0.4.1

# 3 · Run locally
docker run -d --name api \
  -p 8000:8000 \
  -e DATABASE_URL=postgres://app:app@db:5432/app \
  --restart unless-stopped \
  ghcr.io/me/api:0.4.1

# 4 · Tail logs and exec into the running container
docker logs -f --tail 100 api
docker exec -it api sh

# 5 · Tear down
docker stop api && docker rm api

Best practiceGood to know

Pin tags. python:3.13-slim beats python:latest. For reproducibility, pin by digest: python:3.13-slim@sha256:….

One process per container. No supervisord. If you need two, run two containers and let Compose / Kubernetes wire them. Signals + logs only work cleanly with one.

Multi-stage by default. Final image gets the artefact, not the toolchain. Cuts size 5–10× on most stacks and shrinks the attack surface.

Common trapsWatch out for

Never put secrets in ENV or ARG. They show up in docker history and image inspect. Use --mount=type=secret at build time or runtime secrets (Compose / k8s).

latest isn’t magic. It’s just a tag. If you don’t push it, it’s whatever someone last pushed manually. Pin to a version or digest in production.

Bind mounts hide image files. -v $(pwd):/app over an /app that already has a node_modules in the image will erase it for the container. Mount sub-paths or use named volumes for vendored deps.