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