Docker Management

Docker Management

Purpose

• Use this skill to run, inspect, debug, and clean up Docker workloads.
• Prefer it when the task involves containers, images, networks, volumes, or Compose stacks.
• This skill covers both day-to-day lifecycle operations and practical debugging patterns.

Core Mental Model

• Images are immutable build artifacts.
• Containers are running or stopped instances of images.
• Volumes persist data outside the container filesystem lifecycle.
• Networks define service-to-service connectivity.
• Compose describes multi-container applications declaratively.

Container Lifecycle

• Create and run a container.
• Start a stopped container.
• Stop a running container.
• Restart a container after config or dependency issues.
• Remove a container when it is no longer needed.

Common Lifecycle Commands

bashCopy code
docker run -d --name myapp -p 8080:80 -v ./data:/data myimage
docker start myapp
docker stop myapp
docker restart myapp
docker rm myapp

• -d runs the container in detached mode.
• --name assigns a stable container name.
• -p 8080:80 maps host port 8080 to container port 80.
• -v ./data:/data mounts a host path into the container.

Run Command Pattern

bashCopy code
docker run -d --name myapp -p 8080:80 -v ./data:/data myimage

Use this pattern when you need:

• background execution
• a predictable container name
• host-to-container port mapping
• local bind-mount persistence

Inspect Running Containers

bashCopy code
docker ps
docker ps -a

• docker ps shows running containers only.
• docker ps -a shows all containers including exited ones.
• Exited containers often reveal crash-loop or entrypoint problems.

Exec Into a Container

bashCopy code
docker exec -it myapp bash

• Use this when the container image includes bash.
• Fall back to sh for slimmer images:

bashCopy code
docker exec -it myapp sh

Useful checks inside a container:

• verify file paths
• inspect environment variables
• test network reachability
• check permissions
• run the application command manually

View Logs

bashCopy code
docker logs -f myapp

• Use -f to follow logs live.
• Add --tail 100 to reduce noise when the log is very large.
• Container logs are the fastest first stop for boot failures.

List Images, Volumes, and Networks

bashCopy code
docker images
docker volume ls
docker network ls

• docker images helps identify build tags and old layers.
• docker volume ls helps track stateful storage.
• docker network ls is useful when debugging Compose service communication.

Build Images

bashCopy code
docker build -t myapp:latest .

• Tag images explicitly.
• Rebuild after Dockerfile changes, dependency changes, or copy-step changes.
• Keep the build context small with a .dockerignore.

Dockerfile Baseline

dockerfileCopy code
FROM python:3.12-slim

WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

COPY . .
CMD ["python", "app.py"]

• Copy dependency manifests before source code to improve layer caching.
• Use a narrow base image unless native toolchains are required.

Multi-Stage Dockerfile Pattern

dockerfileCopy code
FROM node:22 AS build
WORKDIR /src
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build

FROM nginx:alpine
COPY --from=build /src/dist /usr/share/nginx/html
HEALTHCHECK CMD wget -qO- http://localhost/ || exit 1

• Build dependencies stay in the builder stage.
• The final stage is smaller and carries less attack surface.
• Multi-stage builds are standard for frontend artifacts, Go binaries, and compiled assets.

Health Checks

• Define health checks in the Dockerfile when the service has a meaningful liveness probe.
• Health checks help Compose and orchestration layers reason about readiness.

Example:

dockerfileCopy code
HEALTHCHECK --interval=30s --timeout=5s --retries=3 CMD curl -fsS http://localhost:8080/health || exit 1

• Prefer an explicit application health endpoint.
• Avoid health checks that pass before dependencies are ready unless that is intentional.

Docker Compose Basics

bashCopy code
docker compose up -d
docker compose logs
docker compose down

• docker compose up -d starts the stack in the background.
• docker compose logs shows service logs across the stack.
• docker compose down stops and removes the stack's containers and network.

Minimal Compose Example

yamlCopy code
services:
  app:
    build: .
    ports:
      - "8080:8080"
    environment:
      APP_ENV: development
    depends_on:
      - redis

  redis:
    image: redis:7-alpine

• Compose is the default choice for local multi-service development.
• Keep service names stable because they also become DNS names on the Compose network.

Inspect Container Metadata

bashCopy code
docker inspect myapp | jq '.[0].NetworkSettings'

• Use docker inspect to view full JSON metadata.
• Pipe through jq to isolate fields that matter.
• Useful fields include mounts, networks, exposed ports, health status, and entrypoint configuration.

Resource Usage

bashCopy code
docker stats

• This gives a live view of CPU, memory, network I/O, and block I/O.
• Use it to spot memory leaks, unexpected idle CPU, or runaway workers.

Copy Files In and Out

bashCopy code
docker cp file.txt myapp:/app/
docker cp myapp:/app/output.log ./output.log

• docker cp is useful for hot inspection, artifact extraction, and ad hoc debugging.
• Prefer rebuilds for durable fixes, but docker cp can unblock investigation quickly.

Cleanup

bashCopy code
docker system prune -af
docker volume prune

• docker system prune -af removes unused containers, networks, dangling images, and build cache aggressively.
• docker volume prune removes unused volumes.
• Be careful: pruning can destroy useful cached layers and orphaned but still valuable data.

Common Debugging Patterns

Override the Entrypoint

bashCopy code
docker run --rm -it --entrypoint sh myimage

• Override the entrypoint when the default startup command exits too quickly.
• This lets you inspect the filesystem and run the target process manually.

Check Environment Variables

bashCopy code
docker exec -it myapp env

• Verify that expected secrets, ports, and mode flags are actually present.
• Many container bugs reduce to missing or misspelled env vars.

Check the Effective Command

bashCopy code
docker inspect myapp | jq '.[0].Config.Entrypoint, .[0].Config.Cmd'

• This helps distinguish build-time assumptions from runtime reality.
• It is especially useful when wrapper scripts are involved.

Verify Mounts

bashCopy code
docker inspect myapp | jq '.[0].Mounts'

• Bind-mount mistakes are common in local development.
• Check source path, destination path, and access mode.

Test Networking

bashCopy code
docker exec -it myapp sh -c "wget -qO- http://redis:6379 || true"

• Test container-to-container DNS and reachability from inside the network namespace.
• For HTTP services, use curl or wget.
• For TCP-only services, use the relevant client or a port probe.

Image Hygiene

• Pin important base images when reproducibility matters.
• Use slim runtime images where possible.
• Minimize package-manager caches and temporary files.
• Copy only what is needed.
• Keep secrets out of the image entirely.

Security and Reliability Notes

• Do not bake credentials into Dockerfiles.
• Avoid running as root when the workload does not require it.
• Use read-only filesystems or dropped capabilities where appropriate.
• Scan images regularly with vulnerability tools.

Operational Guidance

• Prefer Compose for local stacks rather than long hand-written docker run chains.
• Use docker logs -f first when a service does not start cleanly.
• Use docker inspect when port mappings or mounts behave unexpectedly.
• Use health checks for services that depend on internal readiness.
• Prune deliberately, not reflexively.

Summary

• Manage container lifecycle with run, start, stop, restart, and rm.
• Build images with docker build -t myapp:latest ..
• Debug with docker exec -it myapp bash, docker logs -f myapp, docker inspect, and docker stats.
• Operate stacks with docker compose up -d, docker compose logs, and docker compose down.
• Clean carefully with docker system prune -af and docker volume prune.
• Use multi-stage Dockerfiles and health checks to improve runtime quality and image hygiene.