secure-container-build

Secure Container Build Best Practices

Build secure, minimal container images using security-hardened runtime images and multi-stage builds.

Core Principles

1. Security-First Runtime Images

Use Wolfi glibc-dynamic as the runtime base image:

• Minimal attack surface (no unnecessary packages)
• Built-in CVE-free by design
• Non-root user by default (UID 65532)
• Regular security updates by Chainguard

Production vs Development

# ARG for choosing runtime image tag
ARG RUNTIME_TAG=latest
FROM cgr.dev/chainguard/glibc-dynamic:${RUNTIME_TAG}

• latest (default): Production - no shell, most secure
• latest-dev: Development - includes shell for debugging

Build for debugging

podman build --build-arg RUNTIME_TAG=latest-dev -t myapp:debug .
podman run -it myapp:debug sh  # Can exec with shell

2. Multi-stage Builds

Always use multi-stage builds to minimize runtime image size:

• Builder stage: Full build environment (Python/Node.js official images)
• Runtime stage: Minimal Wolfi image with only runtime artifacts

3. Non-root User Configuration

Wolfi images use UID 65532 (nonroot user) by default:

# No need to create user, already exists in Wolfi
USER 65532:65532

# When copying files from builder, set ownership
COPY --from=builder --chown=65532:65532 /app /app

4. Init System (tini)

Wolfi images don't include tini. Copy it from builder:

# Copy tini from builder stage
COPY --from=builder /usr/bin/tini-static /usr/bin/tini

# Use as entrypoint for proper signal handling
ENTRYPOINT ["tini", "--"]
CMD ["your-app"]

Quick Start

Python + uv Project

1. Copy Containerfile template:

   cp ${CLAUDE_SKILL_DIR}/assets/Containerfile.python-uv ./Containerfile
   

2. Update application command:

   CMD ["python", "your_app.py"]  # Change to your entry point
   

Bun Project

1. Copy Containerfile template: