container-development

What this skill does

# Container Development

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

## When to Use This Skill

| Use this skill when... | Use a language-specific sibling (`go-containers`, `nodejs-containers`, `python-containers`) instead when... |
|---|---|
| Writing or optimizing language-agnostic Dockerfiles | Optimizing Go static binaries, Node.js Alpine builds, or Python slim images |
| Authoring multi-stage build patterns or 12-factor configuration | The image-size goal is dominated by language runtime choices (scratch, distroless, musl/glibc) |
| Hardening containers (non-root, minimal base, secrets) | Running Skaffold sync (`skaffold-filesync`) or OrbStack networking (`skaffold-orbstack`) |
| Composing services with Docker Compose | The work is purely a Skaffold pre-deploy test (`skaffold-testing`) |

## 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

1. **Analyze**: Understand application dependencies and build process
2. **Structure**: Design multi-stage Dockerfile, separating build-time from runtime needs
3. **Ignore**: Create comprehensive `.dockerignore` file
4. **Build & Scan**: Build image and scan for vulnerabilities
5. **Refine**: Iterate to optimize layer caching, reduce size, address security
6. **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](https://hub.docker.com/_/node) for latest LTS
- **Python slim**: Check [Docker Hub python](https://hub.docker.com/_/python) for latest
- **Go Alpine**: Check [Docker Hub golang](https://hub.docker.com/_/golang) for latest
- **nginx Alpine**: Check [Docker Hub nginx](https://hub.docker.com/_/nginx)
- **Distroless**: Check [Google distroless](https://github.com/GoogleContainerTools/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

```dockerfile
# 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`,