Docker Admin

Docker Admin

Overview

Docker container administration: Compose V2, Dockerfile best practices, cross-platform gotchas, security, and production patterns. This skill covers the tricky parts — quoting across shells, Windows mount issues, AD user mapping, and patterns that prevent 3am incidents.

Docker Compose (V2)

Use docker compose (space, not hyphen). docker-compose (V1) is deprecated.

Compose File Structure

# compose.yaml (preferred name, also accepts docker-compose.yml)
services:
  app:
    build:
      context: .
      dockerfile: Dockerfile
      args:
        NODE_ENV: production
    ports:
      - "8080:8080"
    environment:
      - DATABASE_URL=${DATABASE_URL}
    env_file:
      - .env
    depends_on:
      db:
        condition: service_healthy
    healthcheck:
      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
      interval: 30s
      timeout: 10s
      retries: 3
      start_period: 40s
    deploy:
      resources:
        limits:
          memory: 512M
          cpus: "1.0"
    volumes:
      - app-data:/data
      - ./config:/app/config:ro
    networks:
      - backend

  db:
    image: postgres:16-alpine
    volumes:
      - db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U postgres"]
      interval: 10s
      timeout: 5s
      retries: 5
    networks:
      - backend

volumes:
  app-data:
  db-data:

networks:
  backend:
    driver: bridge

Key Compose Features

Environment Variable Precedence (highest → lowest)

1. docker compose run -e VAR=val
2. Shell environment
3. .env file in project directory
4. env_file in compose
5. Dockerfile ENV

Default values: ${VAR:-default} (use default if unset), ${VAR:?error} (fail if unset)

Dockerfile Best Practices

Multi-Stage Build (Standard Pattern)

# Stage 1: Build
FROM node:22-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --production=false
COPY . .
RUN npm run build

# Stage 2: Production
FROM node:22-alpine AS production
RUN addgroup -g 1001 appgroup && adduser -u 1001 -G appgroup -D appuser
WORKDIR /app
COPY --from=builder /app/dist ./dist
COPY --from=builder /app/node_modules ./node_modules
USER appuser
EXPOSE 8080
HEALTHCHECK CMD wget -q --spider http://localhost:8080/health || exit 1
ENTRYPOINT ["node", "dist/server.js"]

Layer Caching Rules

# GOOD: Dependencies first (rarely change), code second (often changes)
COPY package*.json ./
RUN npm ci
COPY . .

# BAD: Code change invalidates npm ci cache
COPY . .
RUN npm ci

BuildKit Features

# Cache mount (persist package manager cache between builds)
RUN --mount=type=cache,target=/var/cache/apt \
    apt-get update && apt-get install -y python3

# Build secret (never stored in image layers)
RUN --mount=type=secret,id=npm_token \
    NPM_TOKEN=$(cat /run/secrets/npm_token) npm ci

# Heredoc (multi-line scripts without \)
RUN <<EOF
  apt-get update
  apt-get install -y curl git
  rm -rf /var/lib/apt/lists/*
EOF

Enable BuildKit: DOCKER_BUILDKIT=1 or set in Docker daemon config (default in Docker 23.0+).

Base Image Selection

Pin versions: Use node:22.5-alpine not node:latest. For maximum reproducibility, pin by digest: node@sha256:abc123...

Entrypoint Patterns

Init Process (Always Use)

Containers need an init process to reap zombie processes and forward signals:

# Compose (easiest)
services:
  app:
    init: true  # Uses tini

# Or in Dockerfile
ENTRYPOINT ["tini", "--", "node", "server.js"]

Why: Without init, PID 1 is your app — it won't reap zombie child processes and may not handle SIGTERM correctly.

Wait-for-Dependencies

#!/bin/bash
# entrypoint.sh
set -e

# Wait for database
until pg_isready -h "$DB_HOST" -p "$DB_PORT" -U "$DB_USER"; do
  echo "Waiting for database..."
  sleep 2
done

# Run migrations
python manage.py migrate

# Start app
exec "$@"

Key: exec "$@" replaces the shell with the actual process — signals go directly to the app, not the shell.

Config Generation from Environment

# Generate config from env vars using envsubst
envsubst < /app/config.template > /app/config.json
exec "$@"

Cross-Platform: Windows Mounts & Quoting

Volume Mount Paths by Shell

Quoting Cheat Sheet

# Bash
docker run -d \
  --name myapp \
  -p 8080:8080 \
  -v ./data:/app/data \
  -e DATABASE_URL="postgresql://user:pass@db:5432/mydb" \
  myimage:latest

# PowerShell
docker run -d `
  --name myapp `
  -p 8080:8080 `
  -v "${PWD}/data:/app/data" `
  -e DATABASE_URL="postgresql://user:pass@db:5432/mydb" `
  myimage:latest

# CMD
docker run -d ^
  --name myapp ^
  -p 8080:8080 ^
  -v %cd%\data:/app/data ^
  -e DATABASE_URL="postgresql://user:pass@db:5432/mydb" ^
  myimage:latest

Windows Bind Mount Issues

Package Installation in Containers

apt (Debian/Ubuntu)

RUN --mount=type=cache,target=/var/cache/apt \
    apt-get update && \
    apt-get install -y --no-install-recommends \
      curl \
      python3 \
    && rm -rf /var/lib/apt/lists/*

dnf/yum (RHEL/Fedora/Rocky)

RUN --mount=type=cache,target=/var/cache/dnf \
    dnf install -y --setopt=install_weak_deps=False \
      python3 curl \
    && dnf clean all

apk (Alpine)

RUN apk add --no-cache \
    python3 curl

npm/pip (Application Dependencies)

# npm — use ci for reproducible installs
COPY package*.json ./
RUN npm ci --omit=dev

# pip — no cache, specify versions
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

Rule: Always --no-install-recommends (apt), --no-cache (apk), --omit=dev (npm), --no-cache-dir (pip) to minimize image size.

Centrify / AD User Mapping

SSSD Socket Mounting (Recommended)

Mount the host's SSSD socket into the container for AD user resolution:

services:
  app:
    volumes:
      - /var/lib/sss/pipes:/var/lib/sss/pipes:ro
      - /var/lib/sss/mc:/var/lib/sss/mc:ro
    # Container needs nsswitch.conf configured for sss

UID/GID Mapping

# Run as specific AD-mapped UID
ARG APP_UID=1000
ARG APP_GID=1000
RUN groupadd -g ${APP_GID} appgroup && \
    useradd -u ${APP_UID} -g appgroup -m appuser
USER appuser

Pass AD user's UID at build or run time: docker run --user $(id -u):$(id -g) myimage

User Namespace Remapping

Docker's userns-remap maps container root to an unprivileged host user:

// /etc/docker/daemon.json
{
  "userns-remap": "default"
}

Security Checklist

Every container should pass:

• Non-root user — USER directive, never run as root
• Read-only filesystem — --read-only + tmpfs for /tmp
• No unnecessary capabilities — --cap-drop ALL --cap-add only what's needed
• No new privileges — --security-opt=no-new-privileges
• Pinned base image — version tag or digest, not latest
• No secrets in image — use build secrets --mount=type=secret or runtime secrets
• Vulnerability scan — docker scout cves or trivy image in CI
• Minimal base — alpine/slim/distroless, not full OS
• Health check — HEALTHCHECK in Dockerfile or compose
• Init process — init: true in compose or tini in Dockerfile
• No Docker socket mount — unless absolutely required (security risk)

Essential Commands

See commands-reference.md for the full reference. Quick essentials:

Anti-Patterns

Related Skills