containerfile-creator

What this skill does

# Containerfile Creator

Create secure, efficient, and maintainable container images following open source best practices.

## Workflow

1. Determine the project language/framework
2. Load the appropriate reference file for examples (see Language-Specific References below)
3. Apply the core structure and patterns from this document
4. Write the Containerfile following the Final Stage Instruction Ordering

## File Naming

- Prefer `Containerfile` over `Dockerfile`
- Use descriptive names for variants: `alpine.Containerfile`, `distroless.Containerfile`, `ubi.Containerfile`

## Required Syntax Declaration

Every file MUST start with:

```containerfile
# syntax=docker/dockerfile:1
```

## ARG Definition Block

Only `UID`, `VERSION`, and `RELEASE` go at the top level:

```containerfile
# syntax=docker/dockerfile:1
ARG UID=1001
ARG VERSION=EDGE
ARG RELEASE=0
```

`TARGETARCH` and `TARGETVARIANT` MUST be declared inside each stage that uses them, not globally.

## Multi-stage Build Structure

```containerfile
########################################
# Build stage
########################################
FROM python:3.13-alpine AS build

########################################
# Final stage
########################################
FROM python:3.13-alpine AS final
```

- Always name the last stage `final`
- Use 40 `#` characters for stage separators
- Only use a separate `base` stage when it requires non-trivial setup (e.g., installing system packages on UBI/Debian)

## Cache Optimization

Declare multi-arch variables inside each stage that uses cache mounts:

```containerfile
ARG TARGETARCH
ARG TARGETVARIANT
```

### Package Manager Cache Patterns

```containerfile
# Alpine APK
RUN --mount=type=cache,id=apk-$TARGETARCH$TARGETVARIANT,sharing=locked,target=/var/cache/apk \
    apk update && apk add -u package-name

# Debian/Ubuntu APT
RUN --mount=type=cache,id=apt-$TARGETARCH$TARGETVARIANT,sharing=locked,target=/var/cache/apt \
    --mount=type=cache,id=aptlists-$TARGETARCH$TARGETVARIANT,sharing=locked,target=/var/lib/apt/lists \
    apt-get update && apt-get install -y --no-install-recommends package-name

# Python PIP
RUN --mount=type=cache,id=pip-$TARGETARCH$TARGETVARIANT,sharing=locked,target=/root/.cache/pip \
    pip install package-name

# Python UV
RUN --mount=type=cache,id=uv-$TARGETARCH$TARGETVARIANT,sharing=locked,target=/root/.cache/uv \
    uv pip install package-name

# DNF (Fedora/RHEL)
RUN --mount=type=cache,id=dnf-$TARGETARCH$TARGETVARIANT,sharing=locked,target=/var/cache/dnf \
    dnf -y install package-name
```

## Security and Permissions

### Create Non-root User

```containerfile
# Alpine
ARG UID
RUN adduser -g "" -D $UID -u $UID -G root

# Debian/Ubuntu
ARG UID
RUN groupadd -g $UID $UID && \
    useradd -l -u $UID -g $UID -m -s /bin/sh -N $UID
```

### OpenShift Compatibility (Arbitrary UID)

```containerfile
# Create directories
RUN install -d -m 775 -o $UID -g 0 /app && \
    install -d -m 775 -o $UID -g 0 /licenses

# Copy files with proper ownership
COPY --link --chown=$UID:0 --chmod=775 source dest
```

### License Files (Required)

```containerfile
COPY --link --chown=$UID:0 --chmod=775 LICENSE /licenses/Containerfile.LICENSE
COPY --link --chown=$UID:0 --chmod=775 project/LICENSE /licenses/project.LICENSE
```

## Secure dumb-init Usage

Use dumb-init as PID 1 for proper signal handling. Download in a separate stage with SHA256 verification:

```containerfile
########################################
# Download stage
########################################
FROM docker.io/library/debian:bookworm-slim AS download

ARG TARGETARCH
ARG TARGETVARIANT

RUN --mount=type=cache,id=apt-$TARGETARCH$TARGETVARIANT,sharing=locked,target=/var/cache/apt \
    --mount=type=cache,id=aptlists-$TARGETARCH$TARGETVARIANT,sharing=locked,target=/var/lib/apt/lists \
    apt-get update && apt-get install -y --no-install-recommends curl ca-certificates

# Download dumb-init static binary (arch-aware) with SHA256 verification
RUN case "${TARGETARCH}" in \
      amd64) DUMBINIT_ARCH="x86_64"; DUMBINIT_SHA256="e874b55f3279ca41415d290c512a7ba9d08f98041b28ae7c2acb19a545f1c4df" ;; \
      arm64) DUMBINIT_ARCH="aarch64"; DUMBINIT_SHA256="b7d648f97154a99c539b63c55979cd29f005f88430fb383007fe3458340b795e" ;; \
      *) echo "unsupported architecture: ${TARGETARCH}" && exit 1 ;; \
    esac && \
    curl -fsSL "https://github.com/Yelp/dumb-init/releases/download/v1.2.5/dumb-init_1.2.5_${DUMBINIT_ARCH}" \
    -o /dumb-init && \
    echo "${DUMBINIT_SHA256}  /dumb-init" | sha256sum -c -
```

Then copy in the final stage:

```containerfile
COPY --link --chown=$UID:0 --chmod=775 --from=download /dumb-init /usr/local/bin/dumb-init
```

### OpenShift umask Pattern

When the application creates directories at runtime, use `umask 0002` to preserve GID-0 group-write:

```containerfile
ENTRYPOINT ["dumb-init", "--"]
CMD ["sh", "-c", "umask 0002 && exec my-app"]
```

The `exec` replaces the shell so dumb-init's signal forwarding reaches the app directly.

## COPY --link Optimization

Always use `--link` flag for COPY instructions to enable layer reuse across builds:

```containerfile
COPY --link --chown=$UID:0 --chmod=775 source dest
```

Do NOT use `--link` when destination path contains symlinks that need to be followed.

## Final Stage Instruction Ordering (CRITICAL)

Follow this exact order in the final stage:

1. System cleanup (remove pip/setuptools/wheel if applicable)
2. Create user (non-root)
3. Create directories (`install -d`)
4. COPY from build (`--link --chown=$UID:0 --chmod=775`)
5. ENV (PATH and other variables)
6. WORKDIR
7. VOLUME (if applicable)
8. EXPOSE (if applicable)
9. USER $UID
10. STOPSIGNAL SIGINT
11. ENTRYPOINT / CMD
12. **ARG VERSION + ARG RELEASE + LABEL — ALWAYS LAST**

> **LABEL MUST be the very last instruction.** VERSION/RELEASE ARGs bust the cache for all subsequent instructions. Placing them last ensures maximum cache reuse.

## LABEL Standards

```containerfile
ARG VERSION
ARG RELEASE
LABEL name="project-name" \
    vendor="original-author" \
    maintainer="user-id" \
    url="https://github.com/user-id/project" \
    version=${VERSION} \
    release=${RELEASE} \
    io.k8s.display-name="Display Name" \
    summary="Brief summary" \
    description="Detailed description with website reference"
```

## Health Check

> HEALTHCHECK does not function in OCI/podman builds. Do NOT implement unless specifically requested.

When implementing:

```containerfile
COPY --link --from=ghcr.io/tarampampam/curl:8.7.1 /bin/curl /usr/local/bin/
HEALTHCHECK --interval=30s --timeout=2s --start-period=30s \
    CMD [ "curl", "--fail", "http://localhost:8080/" ]
```

## Test, Report, and Binary Stages (Optional)

### Test Stage

Run linting, type-checking, and tests inside the build. Use `--mount=type=bind` for test files to avoid caching them in layers:

```containerfile
########################################
# Test stage
########################################
FROM deps AS test

ARG TARGETARCH
ARG TARGETVARIANT

ENV PATH="/venv/bin${PATH:+:${PATH}}"

WORKDIR /app

# Install dev dependencies using separate cache to avoid conflicts
RUN --mount=type=cache,id=uv-test-$TARGETARCH$TARGETVARIANT,sharing=locked,target=/root/.cache/uv \
    --mount=type=bind,source=pyproject.toml,target=/app/pyproject.toml \
    --mount=type=bind,source=uv.lock,target=/app/uv.lock \
    uv sync --frozen --no-install-project

COPY src/ src/

# Run quality checks and tests with bind-mounted test files
RUN --mount=type=bind,source=tests,target=/app/tests \
    --mount=type=bind,source=pyproject.toml,target=/app/pyproject.toml \
    pytest --junit-xml=/app/test-results.xml \
           --cov=src \
           --cov-report=xml:/app/coverage.xml \
           --cov-fail-under=70 \
           --verbose
```

### Report Stage

Extract test reports from the build without running the full image:

```containerfile
########################################
# Report stage
# How to: podman build --targ