/docker-management

name: docker-management
description: Manage Docker containers, images, volumes, networks, and Compose stacks - lifecycle ops, debugging, cleanup, and Dockerfile optimization.
version: 1.0.0
author: hermes-CCC (ported from Hermes Agent by NousResearch)
license: MIT
metadata:
  hermes:
    tags: [Docker, DevOps, Containers, Infrastructure, Compose]
    related_skills: []

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

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

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

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

docker exec -it myapp bash

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

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

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

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

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

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

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:

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

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

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

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

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

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

docker system prune -af
docker volume prune

• `docker system prune -af` removes unused containers,