Container Development

Expert knowledge for containerization and orchestration with focus on security-first, lean container images and 12-factor app methodology.

Security Philosophy (Non-Negotiable)

Non-Root is MANDATORY: ALL production containers MUST run as non-root users. This is not optional.

Minimal Base Images: Use Alpine (~5MB) for Node.js/Go/Rust. Use slim (~50MB) for Python (musl compatibility issues with Alpine).

Multi-Stage Builds Required: Separate build and runtime environments. Build tools should NOT be in production images.

Core Expertise

Container Image Construction

Dockerfile/Containerfile Authoring: Clear, efficient, and maintainable container build instructions
Multi-Stage Builds: Creating minimal, production-ready images
Image Optimization: Reducing image size, minimizing layer count, optimizing build cache
Security Hardening: Non-root users, minimal base images, vulnerability scanning

Container Orchestration

Service Architecture: Microservices with proper service discovery
Resource Management: CPU/memory limits, auto-scaling policies, resource quotas
Health & Monitoring: Health checks, readiness probes, observability patterns
Configuration Management: Environment variables, secrets, configuration management

Key Capabilities

12-Factor Adherence: Ensures containerized applications follow 12-factor principles, especially configuration and statelessness
Health & Reliability: Implements proper health checks, readiness probes, and restart policies
Skaffold Workflows: Structures containerized applications for efficient development loops
Orchestration Patterns: Designs service meshes, load balancing, and container communication
Performance Tuning: Optimizes container resource usage, startup times, and runtime performance

Image Crafting Process

Analyze: Understand application dependencies and build process
Structure: Design multi-stage Dockerfile, separating build-time from runtime needs
Ignore: Create comprehensive .dockerignore file
Build & Scan: Build image and scan for vulnerabilities
Refine: Iterate to optimize layer caching, reduce size, address security
Validate: Ensure image runs correctly and adheres to 12-factor principles

Best Practices

Core Optimization Principles

1. Multi-Stage Builds (MANDATORY):

Separate build-time dependencies from runtime
Keep build tools out of production images
Typical reduction: 60-90% smaller final images

2. Minimal Base Images:

Start with the smallest base that works
Prefer Alpine for most languages (except Python)
Consider distroless for maximum security

3. Non-Root Users (MANDATORY):

Always create and use non-root user
Set UID/GID explicitly (e.g., 1001)
Security compliance requirement

4. .dockerignore (MANDATORY):

Exclude .git, node_modules, __pycache__
Prevent secrets and dev files from entering image
Reduces build context by 90-98%

5. Layer Optimization:

Copy dependency manifests separately from source
Put frequently changing layers last
Combine related RUN commands with &&

Version Checking

CRITICAL: Before using base images, verify latest versions:

Node.js Alpine: Check Docker Hub node for latest LTS
Python slim: Check Docker Hub python for latest
Go Alpine: Check Docker Hub golang for latest
nginx Alpine: Check Docker Hub nginx
Distroless: Check Google distroless for latest

Use WebSearch or WebFetch to verify current versions.

Language-Specific Optimization

For detailed language-specific optimization patterns, see the dedicated skills:

Language	Skill	Key Optimization	Typical Reduction
Go	`go-containers`	Static binaries, scratch/distroless	846MB → 2.5MB (99.7%)
Node.js	`nodejs-containers`	Alpine, multi-stage, npm/yarn/pnpm	900MB → 100MB (89%)
Python	`python-containers`	Slim (NOT Alpine), uv, venv	1GB → 100MB (90%)

Quick Base Image Guide

Choose the right base image:

Go: scratch or distroless/static (2-5MB)
Node.js: node:XX-alpine (50-150MB)
Python: python:XX-slim (80-120MB) - Never use Alpine for Python!
Nginx: nginx:XX-alpine (20-40MB)
Static files: scratch or nginx:alpine (minimal)

Multi-Stage Build Template

# Build stage - includes all build tools
FROM <language>:<version> AS builder
WORKDIR /app

# Copy dependency manifests first (better caching)
COPY package.json package-lock.json ./  # or go.mod, requirements.txt, etc.

# Install dependencies
RUN <install-command>

# Copy source code
COPY . .

# Build application
RUN <build-command>

# Runtime stage - minimal
FROM <minimal-base>
WORKDIR /app

# Create non-root user
RUN addgroup --gid 1001 appgroup && \
    adduser --uid 1001 --gid 1001 --disabled-password appuser

# Copy only what's needed from builder
COPY --from=builder --chown=appuser:appuser /app/dist ./dist

USER appuser
EXPOSE <port>

HEALTHCHECK --interval=30s CMD <health-check-command>

CMD [<start-command>]

Security Requirements (Mandatory)

Non-root user: REQUIRED - never run as root in production
Minimal base images: Choose smallest viable base
- Typical CVE reduction: 50-100% (full base: 50-70 CVEs → minimal: 0-12 CVEs)
- No shell = no shell injection attacks
- No package manager = no supply chain attacks
Multi-stage builds: REQUIRED - keep build tools out of runtime
HEALTHCHECK: REQUIRED for Kubernetes liveness/readiness probes
Vulnerability scanning: Use Trivy, Grype, or Docker Scout in CI
Version pinning: Always use specific tags (e.g., node:20.10-alpine), never latest
.dockerignore: REQUIRED - prevents secrets, .env, .git from entering image

Typical Impact of Full Optimization:

Image size: 85-99% reduction
Security: 70-100% fewer CVEs
Pull time: 80-98% faster
Build time: 40-60% faster (with proper caching)
Memory usage: 60-80% lower
Storage costs: 90-99% reduction

12-Factor App Principles

Configuration via environment variables
Stateless processes
Explicit dependencies
Port binding for services
Graceful shutdown handling

Container Labels (OCI Annotations)

Container labels provide metadata for image discovery, linking, and documentation. GitHub Container Registry (GHCR) specifically supports OCI annotations to link images to repositories and display descriptions.

Required Labels for GHCR

Label	Purpose	Example
`org.opencontainers.image.source`	Links image to repository (enables GHCR features)	`https://github.com/owner/repo`
`org.opencontainers.image.description`	Package description (max 512 chars)	`Production API server`
`org.opencontainers.image.licenses`	SPDX license identifier (max 256 chars)	`MIT`, `Apache-2.0`

Recommended Labels

Label	Purpose	Example
`org.opencontainers.image.version`	Semantic version	`1.2.3`
`org.opencontainers.image.revision`	Git commit SHA	`abc1234`
`org.opencontainers.image.created`	Build timestamp (RFC 3339)	`2025-01-19T12:00:00Z`
`org.opencontainers.image.title`	Human-readable name	`My Application`
`org.opencontainers.image.vendor`	Organization name	`Forum Virium Helsinki`
`org.opencontainers.image.url`	Project homepage	`https://example.com`
`org.opencontainers.image.documentation`	Documentation URL	`https://docs.example.com`

Adding Labels in Dockerfile

# Static labels (set at build time)
LABEL org.opencontainers.image.source="https://github.com/owner/repo" \
      org.opencontainers.image.description="Production API server" \
      org.opencontainers.image.licenses="MIT" \
      org.opencontainers.image.vendor="Forum Virium Helsinki"

# Dynamic labels (via build args)
ARG VERSION=dev
ARG BUILD_DATE
ARG VCS_REF

LABEL org.opencontainers.image.version="${VERSION}" \
      org.opencontainers.image.created="${BUILD_DATE}" \
      org.opencontainers.image.revision="${VCS_REF}"

Adding Labels at Build Time

docker build \
  --label "org.opencontainers.image.source=https://github.com/owner/repo" \
  --label "org.opencontainers.image.description=My container image" \
  --label "org.opencontainers.image.licenses=MIT" \
  --build-arg VERSION=1.2.3 \
  --build-arg BUILD_DATE=$(date -u +"%Y-%m-%dT%H:%M:%SZ") \
  --build-arg VCS_REF=$(git rev-parse --short HEAD) \
  -t myapp:1.2.3 .

GitHub Actions with docker/metadata-action

The docker/metadata-action automatically generates OCI labels from repository metadata:

- id: meta
  uses: docker/metadata-action@v5
  with:
    images: ghcr.io/${{ github.repository }}
    labels: |
      org.opencontainers.image.title=My Application
      org.opencontainers.image.description=Production API server
      org.opencontainers.image.vendor=Forum Virium Helsinki

- uses: docker/build-push-action@v6
  with:
    labels: ${{ steps.meta.outputs.labels }}

Auto-generated labels by metadata-action:

org.opencontainers.image.source (from repository URL)
org.opencontainers.image.revision (from commit SHA)
org.opencontainers.image.created (build timestamp)
org.opencontainers.image.version (from tags/refs)

Skaffold Preference

Favor Skaffold over Docker Compose for local development
Continuous development loop with hot reload
Production-like local environment

Agentic Optimizations

When building and testing containers, use these optimizations for faster feedback:

Context	Command	Purpose
Quick build	`DOCKER_BUILDKIT=1 docker build --progress=plain -t app .`	BuildKit with plain output
Build with cache	`docker build --cache-from app:latest -t app:new .`	Reuse layers from previous builds
Security scan	`docker scout cves app:latest \| head -50`	Quick vulnerability check
Size analysis	`docker images app --format "{{.Size}}"`	Check image size
Layer inspection	`docker history app:latest --human --no-trunc`	Analyze layer sizes
Build without cache	`docker build --no-cache --progress=plain -t app .`	Force clean build
Test container	`docker run --rm -it app:latest /bin/sh`	Interactive testing
Quick health check	`docker run --rm app:latest timeout 5 /health`	Verify startup

Build optimization flags:

--target=<stage>: Build specific stage only (faster iteration)
--build-arg BUILDKIT_INLINE_CACHE=1: Enable inline cache
--secret id=key,src=file: Mount secrets without including in image

For detailed Dockerfile optimization techniques, orchestration patterns, security hardening, and Skaffold configuration, see REFERENCE.md.

Related Skills

Language-Specific Container Optimization:

go-containers - Go static binaries, scratch/distroless (846MB → 2.5MB)
nodejs-containers - Node.js Alpine patterns, npm/yarn/pnpm (900MB → 100MB)
python-containers - Python slim (NOT Alpine), uv/poetry (1GB → 100MB)

Related Commands

/configure:container - Comprehensive container infrastructure validation
/configure:dockerfile - Dockerfile-specific configuration
/configure:workflows - GitHub Actions including container builds
/configure:skaffold - Kubernetes development configuration

container-development