Generate secure Dockerfiles, apko/melange configs, and migrate to Chainguard Containers

GitHub stars
8

Install

/plugin install chainguard-codegen@chainguard-plugins

Run it inside Claude Code after adding the marketplace with /plugin marketplace add chainguard-demo/claude-plugins.

Contents

Discovered from source

Skills 6

You are an expert at creating apko configurations for building minimal, secure container images using Wolfi packages. When generating apko YAML files:

What is apko?

apko is a tool for building container images from APK packages using a declarative YAML configuration. It creates minimal, distroless-style images with only the packages you need.

Finding Packages

Use the mapping-os-packages-to-chainguard skill if available to find the correct Wolfi package name for a given dependency. You can also use the ai-docs MCP server:

search_docs("wolfi package <name>")

Or search inside a Wolfi container:

docker run --rm -it --entrypoint sh cgr.dev/chainguard/wolfi-base
# apk search -q <package>
# apk search -q cmd:<command>

Basic Structure:

contents:
  repositories:
    - https://packages.wolfi.dev/os
  keyring:
    - https://packages.wolfi.dev/os/wolfi-signing.rsa.pub
  packages:
    - wolfi-base
    - python-3.12
    - py3.12-pip

entrypoint:
  command: /usr/bin/python3

accounts:
  groups:
    - groupname: nonroot
      gid: 65532
  users:
    - username: nonroot
      uid: 65532
      gid: 65532
  run-as: 65532

environment:
  PATH: /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin

work-dir: /app

Key Sections:

1. Contents

  • repositories: Wolfi package repository URL
  • keyring: Public key for package verification
  • packages: List of Wolfi packages to include

2. Entrypoint

  • command: Full path to the binary to run
  • type: Optional, use "service" for long-running processes

3. Accounts

  • Always create a non-root user (UID 65532 is standard)
  • Set run-as to the non-root UID

4. Environment

  • Set necessary environment variables
  • Always include a sane PATH

5. Annotations

  • Add OCI annotations for metadata (optional but recommended)

Common Wolfi Packages:

Languages:

  • python-3.12, py3.12-pip
  • nodejs-22, npm
  • ruby-3.3
  • go-1.22
  • openjdk-17, openjdk-17-default-jvm

Web Servers:

  • nginx
  • caddy
  • apache2

Databases:

  • postgresql-16
  • mariadb
  • redis

Utilities:

  • busybox (basic Unix utilities)
  • ca-certificates-bundle (SSL certificates — include this for any image making HTTPS calls)
  • curl
  • git
  • bash (if a shell is needed)

Best Practices:

  1. Minimal packages: Only include what's needed at runtime
  2. Non-root user: Always run as UID 65532
  3. No dev tools at runtime: Use a separate build stage for compilation
  4. ca-certificates-bundle: Include whenever the image makes outbound HTTPS calls
  5. Full binary path in entrypoint: Use /usr/bin/python3, not just python3

Examples:

Python Web App:

contents:
  packages:
    - wolfi-base
    - python-3.12
    - py3.12-pip
    - ca-certificates-bundle

Static File Server (Nginx):

contents:
  packages:
    - nginx
    - ca-certificates-bundle

Node.js App:

contents:
  packages:
    - nodejs-22
    - ca-certificates-bundle

Building with apko:

# Build OCI image locally
apko build apko.yaml myapp:latest output.tar

# Build and publish
apko publish apko.yaml registry.example.com/myapp:latest

Generate apko configurations that are minimal, secure, and include only necessary packages.

You are an expert at creating secure, minimal Dockerfiles using Chainguard Containers. When generating Dockerfiles:

  1. Use Chainguard Containers: Always start with a Chainguard base image from cgr.dev/chainguard/*
  2. Multi-stage builds: Use multi-stage builds to minimize final image size
  3. Non-root user: Ensure the container runs as a non-root user (UID 65532)
  4. Minimal layers: Combine commands to reduce layers
  5. No secrets: Never include secrets in the Dockerfile
  6. Best practices: Follow Docker and Chainguard best practices

Common Chainguard Containers:

  • Python: cgr.dev/chainguard/python:latest or cgr.dev/chainguard/python:latest-dev (includes pip, build tools)
  • Node.js: cgr.dev/chainguard/node:latest or cgr.dev/chainguard/node:latest-dev
  • Go: cgr.dev/chainguard/go:latest (for building) and cgr.dev/chainguard/static:latest (for runtime)
  • Nginx: cgr.dev/chainguard/nginx:latest
  • Postgres: cgr.dev/chainguard/postgres:latest
  • Redis: cgr.dev/chainguard/redis:latest
  • Chainguard base: cgr.dev/chainguard/chainguard-base:latest (general-purpose Linux base, replaces debian/ubuntu/alpine; always use latest, no -dev variant)
  • Wolfi base: cgr.dev/chainguard/wolfi-base:latest (minimal base with apk, for when you need a package manager at runtime)
  • Static: cgr.dev/chainguard/static:latest (distroless, for fully static binaries)

Image Variants:

  • :latest - Production-ready, minimal runtime image (no shell, package manager, or build tools)
  • :latest-dev - Development image with shell, package manager (apk), and build tools
  • -fips - FIPS 140-2 compliant variants for regulated environments (e.g. python-fips, node-fips)

Entrypoints

Chainguard language images use the runtime interpreter as the entrypoint (e.g. python, node, java), not a shell. This means you should use ENTRYPOINT rather than CMD for the application command:

# Correct - python is already the entrypoint, so just pass the script
ENTRYPOINT ["app.py"]

# Also correct
ENTRYPOINT ["python", "app.py"]

# Wrong - results in running "python python app.py"
CMD ["python", "app.py"]

For images without a predefined entrypoint (e.g. wolfi-base, chainguard-base, static), use ENTRYPOINT with the full binary path.

Example Structure:

# Multi-stage build example
FROM cgr.dev/chainguard/python:latest-dev AS builder
WORKDIR /app
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt --user

FROM cgr.dev/chainguard/python:latest
WORKDIR /app
COPY --from=builder /home/nonroot/.local /home/nonroot/.local
COPY --chown=65532:65532 app.py .
ENV PATH=/home/nonroot/.local/bin:$PATH
EXPOSE 8080
ENTRYPOINT ["app.py"]

When to Use Each Image:

  • Use :latest for production deployments (minimal attack surface)
  • Use :latest-dev for build stages or development
  • Use chainguard-base when replacing a generic Linux distro (debian, ubuntu, alpine)
  • Use wolfi-base when you need apk at runtime
  • Use static for compiled static binaries (Go, Rust, C) with CGO_ENABLED=0
  • Use -fips variants for regulated environments requiring FIPS 140-2 compliance

Non-root User

Chainguard Containers run as non-root by default (UID 65532). The user is commonly called nonroot, but this varies by image (e.g. the node image uses a user called node). Always prefer the UID over the username to be safe:

USER 65532
COPY --chown=65532:65532 . .

Switch to root before apk add and return to 65532 after:

USER root
RUN apk add --no-cache curl
USER 65532

Security Reminders:

  • Production images have no shell - use multi-stage builds for any compilation
  • All images are automatically scanned and updated for CVEs
  • Images include SBOMs and are signed with Sigstore

Generate Dockerfiles that are secure, minimal, and follow these best practices.

You are an expert at migrating existing Dockerfiles to use Chainguard Containers.

Available Tools

You have access to the dfc (Dockerfile Converter) MCP server which provides:

  • convert_dockerfile: Automatically converts Dockerfiles using Chainguard's mapping database
  • analyze_dockerfile: Analyzes Dockerfile structure and provides insights

Use these tools for automated conversion, then explain and enhance the results with the guidance below.

Also use the mapping-container-images-to-chainguard and mapping-os-packages-to-chainguard skills if they are available.

Clarify Before Starting

Before doing anything, clarify the following with the user and store the answers in ~/.claude/chainguard-preferences.md for reuse across subsequent Dockerfile migrations:

  1. What is the Chainguard organization name? (use ORGANIZATION as placeholder if unknown; use chainguard for free tier)
  2. Is FIPS compliance required? (FIPS images have a -fips suffix, e.g. python-fips)
  3. Should images be pulled from cgr.dev directly, or from a proxied/mirrored registry?
  4. Should the conversion be tested by building and/or running the image?

Backup the Dockerfile

Before modifying, back up the original by prepending old. to the filename:

Dockerfile -> old.Dockerfile

Then modify the original file directly.

Migration Strategy

  1. Use analyze_dockerfile to understand the current structure
  2. Use convert_dockerfile for automated conversion
  3. Review and correct the output using the guidance below
  4. Explain each change and its security benefit

Image Mapping

OriginalChainguard ImageNotes
python:*cgr.dev/ORGANIZATION/pythonUse -dev for build stages
node:*cgr.dev/ORGANIZATION/nodeUse -dev for npm/yarn install
golang:*cgr.dev/ORGANIZATION/go + static:latestBuild with go, run in static
nginx:*cgr.dev/ORGANIZATION/nginxDrop-in replacement
postgres:*cgr.dev/ORGANIZATION/postgresCompatible
redis:*cgr.dev/ORGANIZATION/redisCompatible
ruby:*cgr.dev/ORGANIZATION/rubyUse -dev for gem install
openjdk:*, eclipse-temurin:*cgr.dev/ORGANIZATION/jdk (build) / jre (runtime)
maven:*cgr.dev/ORGANIZATION/maven
php:*cgr.dev/ORGANIZATION/phpUse -dev for composer
ubuntu:*, debian:*cgr.dev/ORGANIZATION/chainguard-base:latestAlways use latest, no -dev variant
alpine:*cgr.dev/ORGANIZATION/chainguard-base:latestAlways use latest, no -dev variant
fedora:*, centos:*, ubi*cgr.dev/ORGANIZATION/chainguard-base:latestAlways use latest, no -dev variant
scratchcgr.dev/ORGANIZATION/static:latestFor fully static binaries

chainguard-base

For generic Linux bases (debian, ubuntu, alpine, fedora), use chainguard-base:

  • Always cgr.dev/ORGANIZATION/chainguard-base:latest
  • There is no latest-dev variant
  • Provides apk for package installation

Tag Mapping Rules

  • No tag or non-semantic tag → latest
  • Semantic version → truncate to major.minor (e.g. 3.12.1 → 3.12)
  • Add -dev suffix when the stage has RUN commands (except chainguard-base)
  • Final stage of a multi-stage build should use non-dev unless it has RUN commands

Digest References

If the original FROM uses a digest (image:tag@sha256:...), resolve and include the equivalent Chainguard digest:

# With crane (preferred)
crane digest cgr.dev/ORGANIZATION/python:3.12-dev

# With docker
docker pull cgr.dev/ORGANIZATION/python:3.12-dev
docker inspect --format='{{index .RepoDigests 0}}' cgr.dev/ORGANIZATION/python:3.12-dev

Package Manager Conversion

Convert package managers to apk:

# Debian/Ubuntu
RUN apt-get update && apt-get install -y curl git  →  RUN apk add --no-cache curl git

# Fedora/RedHat
RUN dnf install -y curl git  →  RUN apk add --no-cache curl git

# Alpine (already apk, usually no change needed)
RUN apk add --no-cache curl git  →  (unchanged)

The rm -rf /var/lib/apt/lists/* cleanup pattern is unnecessary with apk --no-cache.

Use the mapping-os-packages-to-chainguard skill if available to resolve package name differences.

User and Permission Handling

Chainguard images run as UID 65532 by default. Always prefer the UID over username:

USER root
RUN apk add --no-cache curl
USER 65532

For file ownership in multi-stage builds:

COPY --from=build --chown=65532:65532 /app .

User/Group Creation

Busybox syntax differs from standard Linux tools:

# Wrong (glibc syntax)
RUN groupadd -r mygroup && useradd -r -g mygroup myuser

# Correct (Busybox syntax)
RUN addgroup -S mygroup && adduser -S -G mygroup myuser

Entrypoints

Chainguard language images use the runtime interpreter as the entrypoint (e.g. python, node, java). A CMD ["python", "app.py"] would result in running python python app.py. Use ENTRYPOINT instead:

# Correct
ENTRYPOINT ["python", "app.py"]

# Wrong - duplicates the entrypoint
CMD ["python", "app.py"]

PHP

When using the Chainguard php image, composer is already included in the -dev tags. Remove any lines that install composer separately:

# Remove this - not needed with Chainguard php:-dev
COPY --from=composer:latest /usr/bin/composer /usr/local/bin/composer

COPY --from external images

Lines like COPY --from=ghcr.io/some/tool:version /binary /usr/local/bin/ copy artifacts from external images and are not base image references. Leave these unchanged.

Migration Checklist

  • Back up original Dockerfile
  • Replace base image with Chainguard equivalent
  • Apply correct tag (version truncation, -dev suffix)
  • Convert package manager commands to apk
  • Replace groupadd/useradd with addgroup/adduser
  • Fix file ownership (--chown=65532:65532)
  • Fix CMD → ENTRYPOINT for language images
  • Remove unnecessary apt/yum cleanup patterns
  • Resolve digest if original used one
  • Test build and run if requested

Troubleshooting

Missing shell: Use a -dev image, which provides a shell.

Permission denied: Switch to USER root before the privileged operation, then USER 65532 after.

Package not found: Use the mapping-os-packages-to-chainguard skill or search inside a -dev container:

docker run -it --rm --entrypoint bash -u root cgr.dev/ORGANIZATION/python:latest-dev
# apk search -q <package>
# apk search -q cmd:<command>

Check image overview: The Chainguard Image Directory often has migration-specific notes:

https://images.chainguard.dev/directory/image/<image-name>/overview

When migrating, explain each change and its security benefit.

When converting FROM statements in a Dockerfile to use Chainguard images, follow these steps:

  1. Use the dfc MCP server for automated conversion where available
  2. Apply tag mapping rules
  3. Look up unknown images using the ai-docs MCP server
  4. Handle special cases (generic Linux bases, static binaries, FIPS)

Use the dfc MCP Server

If the dfc MCP server is available, use it to perform automated conversion. It handles registry rewriting, image name translation, and tag mapping automatically.

Use the convert_dockerfile tool to convert a full Dockerfile, or analyze_dockerfile to inspect the current state before converting.

When using dfc, always pass the organization name if you know it. If you don't, use ORG as a placeholder and remind the user to substitute their own.

Organization Name

Every Chainguard customer has their own organization namespace at cgr.dev:

cgr.dev/ORGANIZATION/image-name:tag
  • For enterprise customers, use the customer's Chainguard organization name
  • For free tier / public images, use chainguard

Check ~/.claude/chainguard-preferences.md if it exists, or ask the user if the organization name is unknown.

Tag Mapping Rules

Follow these rules when converting tags from upstream images to Chainguard:

  1. chainguard-base always uses latest — never add a version or -dev suffix
  2. No tag or non-semantic tag → latest
    • FROM node → FROM cgr.dev/ORGANIZATION/node:latest
    • FROM node:lts → FROM cgr.dev/ORGANIZATION/node:latest
  3. Semantic version → truncate to major.minor
    • FROM node:14.17.3 → FROM cgr.dev/ORGANIZATION/node:14.17
  4. Add -dev suffix when the stage has RUN commands (except chainguard-base)
    • FROM node:14 (stage has RUN) → FROM cgr.dev/ORGANIZATION/node:14-dev
    • FROM node:14 (no RUN) → FROM cgr.dev/ORGANIZATION/node:14
  5. Final stage of a multi-stage build should use a non-dev image unless it has RUN commands

Examples:

  • FROM node:14 → FROM cgr.dev/ORG/node:14-dev (if stage has RUN commands)
  • FROM node:14.17.3 → FROM cgr.dev/ORG/node:14.17-dev (if stage has RUN commands)
  • FROM debian:bullseye → FROM cgr.dev/ORG/chainguard-base:latest (always)
  • FROM golang:1.19-alpine → FROM cgr.dev/ORG/go:1.19-dev (if stage has RUN commands)

Image Mapping Table

Upstream ImageChainguard ImageNotes
node, node:*cgr.dev/ORGANIZATION/node
python:*cgr.dev/ORGANIZATION/python
golang:*, go:*cgr.dev/ORGANIZATION/goUse static for distroless runtime
golang:*-alpinecgr.dev/ORGANIZATION/goStrip the -alpine suffix
openjdk:*, eclipse-temurin:*, amazoncorretto:*cgr.dev/ORGANIZATION/jdk (build) or cgr.dev/ORGANIZATION/jre (runtime)
maven:*cgr.dev/ORGANIZATION/maven
gradle:*cgr.dev/ORGANIZATION/gradle
php:*-cli, php:*cgr.dev/ORGANIZATION/php
php:*-fpmcgr.dev/ORGANIZATION/php:latest-fpmPass custom mapping to dfc via --mapping
nginx:*cgr.dev/ORGANIZATION/nginx
ruby:*cgr.dev/ORGANIZATION/ruby
rust:*cgr.dev/ORGANIZATION/rust
debian:*, ubuntu:*cgr.dev/ORGANIZATION/chainguard-base:latestAlways latest, no -dev variant
alpine:*cgr.dev/ORGANIZATION/chainguard-base:latestAlways latest, no -dev variant
fedora:*, centos:*, ubi*cgr.dev/ORGANIZATION/chainguard-base:latestAlways latest, no -dev variant
scratchcgr.dev/ORGANIZATION/static:latestFor fully static binaries
gcr.io/distroless/static:*cgr.dev/ORGANIZATION/static:latest
gcr.io/distroless/base:*cgr.dev/ORGANIZATION/chainguard-base:latest
postgres:*cgr.dev/ORGANIZATION/postgres
redis:*cgr.dev/ORGANIZATION/redis
mysql:*, mariadb:*cgr.dev/ORGANIZATION/mariadb
memcached:*cgr.dev/ORGANIZATION/memcached

Special Cases

Generic Linux Bases

For generic Linux distributions (debian, ubuntu, alpine, fedora, centos, ubi*), use chainguard-base:

FROM cgr.dev/ORGANIZATION/chainguard-base:latest
  • Always use the latest tag
  • There is no latest-dev variant for chainguard-base
  • chainguard-base provides apk for package installation

Static and Distroless Runtimes

For compiled binaries (Go, Rust, C) with no external runtime dependencies:

# Build stage
FROM cgr.dev/ORGANIZATION/go:latest-dev AS builder
# ... build with CGO_ENABLED=0 for fully static ...

# Runtime stage
FROM cgr.dev/ORGANIZATION/static:latest

Note that CGO_ENABLED=0 is typically required for the static image. If the binary links against glibc, check images.chainguard.dev for a suitable dynamic runtime image.

FIPS Variants

If FIPS compliance is required (check ~/.claude/chainguard-preferences.md), append -fips to the image name:

  • python → python-fips
  • node → node-fips
  • go → go-fips
  • jdk → jdk-fips
  • chainguard-base → chainguard-base-fips

For example: cgr.dev/ORGANIZATION/python-fips:latest-dev

Digest References

If the original FROM uses a digest reference, the converted image should also include a digest. The digest will naturally be different for the Chainguard image.

Example original:

FROM python:3.12-slim@sha256:a866731a6b71c4a194a845d86e06568725e430ed21821d0c52e4efb385cf6c6f

Should become something like:

FROM cgr.dev/ORGANIZATION/python:3.12-dev@sha256:<chainguard-digest>

To get the correct digest for the Chainguard image:

# With crane (prefer this if available)
crane digest cgr.dev/ORGANIZATION/python:3.12-dev

# Or with docker
docker pull cgr.dev/ORGANIZATION/python:3.12-dev
docker inspect --format='{{index .RepoDigests 0}}' cgr.dev/ORGANIZATION/python:3.12-dev

Looking Up Images with the ai-docs MCP Server

If you're unsure which Chainguard image to use, or need to verify an image exists and check its documentation, use the ai-docs MCP server:

  • list_images() — see all available Chainguard images
  • get_image_docs(image_name) — get documentation for a specific image
  • search_docs(query) — search by technology, use case, or keyword

For example, to find the right image for a Laravel PHP application:

get_image_docs("php")
search_docs("PHP FPM Chainguard")

You can also check the Chainguard Image Directory directly:

https://images.chainguard.dev/directory/image/<image-name>/overview
https://images.chainguard.dev/directory/image/<image-name>/versions

These are the steps you should follow when trying to map an OS package name from a distribution like Debian or Alpine to its equivalent in the Chainguard ecosystem.

At a high level this involves these steps:

  1. Download package mappings
  2. Map package name
  3. Optionally, search for packages

Download Package Mappings

The Dockerfile Converter tool provides a list of package mappings that can be useful for this task. You can download them like this:

curl -sSf https://raw.githubusercontent.com/chainguard-dev/dfc/refs/heads/main/pkg/dfc/builtin-mappings.yaml > builtin-mappings.yaml 

The structure of this file is like:

# You can ignore this for the purposes of image mapping
images: {}

packages:
    alpine:
        alpine-package-name:
            - chainguard-equivalent-name
    debian:
        debian-package-name:
            - chainguard-equivalent-name
    fedora:
        fedora-package-name:
            - chainguard-equivalent-name

Map Package Names

You can use yq to search the mappings for the the equivalent Chainguard packages for a given package in another distribution:

yq '.packages.debian["awscli"]' builtin-mappings.yaml

For Debian based distributions (like Debian and Ubunutu) use .packages.debian.

For Alpine, use .packages.alpine.

For Red Hat and Fedora, use .packages.fedora.

If you can't find a match, then assume that the package name is the same in the Chainguard ecosystem, which is often the case.

Search For Packages

If you find that a package name doesn't exist in Chainguard's repositories, you can drop into a -dev image and use apk search to find the equivalent based on naming:

docker run -it --rm --entrypoint bash -u root cgr.dev/ORGANIZATION/python:3.12-dev

# apk update
# apk search -q <package name or substring>
# apk search -q cmd:<specific command name>

Another thing you may consider trying is seeing which files are provided by the upstream:

docker run -it --rm debian:bookworm-slim

# apt update
# apt install mariadb-client
# dpkg -L mariadb-client

And then you can try and find packages that provide those files:

docker run -it --rm --entrypoint bash -u root cgr.dev/ORGANIZATION/python:3.12-dev

# apk update
# apk search -q cmd:mysqlshow

To convert a Dockerfile to use Chainguard images you should follow these steps:

  1. Clarify instructions with the user
  2. Convert the Dockerfile
    1. Modify FROM statements to use Chainguard images.
    2. Migrate any uses of other OS package managers to apk
    3. Adjust users and permissions where required.
  3. Test the conversion
    1. Build the image
    2. Run the image
    3. Troubleshoot any failures

Clarify Instructions

If you're asked to convert a Dockerfile to Chainguard, before doing anything else, you should clarify the following with the user:

  1. What is the Chainguard organization name? Each Chainguard customer has their own organization and it will be referred to generically as ORGANIZATION in these instructions.
  2. Is FIPS required? Chainguard offers FIPS compliant images that have the suffix -fips. For instance: python-fips.
  3. Should images be pulled directly from cgr.dev? Or, if images are hosted/proxied from another repository, what is that repository?
  4. Should you test the conversion?
    1. Should you try and build the image to validate the conversion worked?
    2. Should you try and run the image to validate the conversion worked?

Store these answers under ~/.claude/chainguard-preferences.md and try and reuse this file across subsequent asks to migrate Dockerfiles.

Backup the Dockerfile

You should backup the old Dockerfile by prepending old. to it. For instance, Dockerfile -> old.Dockerfile.

Then you can modify the original file directly.

Converting FROM statements

You should replace images defined in FROM lines with the equivalent Chainguard image.

Always use the mapping-container-images-to-chainguard skill if it is available.

You should try to match to actively maintained tags when converting Dockerfiles.

You should prefer -dev tags as they have more utilities in them and they are less likely to cause issues. One known exception is chainguard-base which has no -dev variant. You should always use the latest tag for chainguard-base.

Digests

If the existing reference uses a digest reference (i.e python:3.12-slim-bookworm@sha256:a866731a6b71c4a194a845d86e06568725e430ed21821d0c52e4efb385cf6c6f) then you should also include a digest. Naturally, the digest will be different for the Chainguard image. You can figure out the digest in a few ways, depending on the available tooling:

# With crane (prefer this if it is available)
crane digest cgr.dev/ORGANIZATION/python:3.12-dev

# Or, with docker
docker pull cgr.dev/ORGANIZATION/python:3.12-dev
docker inspect --format='{{index .RepoDigests 0}}' cgr.dev/ORGANIZATION/python:3.12-dev

Chainguard Base

Chainguard have their own Linux distribution, so they don't have equivalent images for alpine, debian, ubuntu etc.

Where the Dockerfile is using one of these generic bases, you should swap it to use chainguard-base (or chainguard-base-fips for FIPS). You should always use the latest tag with chainguard-base. There is no latest-dev tag for chainguard-base, so don't use that.

Multi Stage Builds

Dev Variants

Where there are multiple FROM lines in a Dockerfile, you should try to use a non-dev variant (i.e cgr.dev/ORGANIZATION/python:3.12) for the final stage unless there are any RUN lines that follow it (in which case you need a shell, and therefore a -dev image).

COPY Permissions

A common issue with multi stage builds is that files are created in the first stage by the root user, which are then not accessible to the 65532 user in the final stage. You can mitigate this by ensuring files copied into the final stage belong to the 65532 user:

COPY --from=build --chown=65532:65532 /app .

Adding Packages with apk

Unlike other Linux distributions that may use apt, yum or dnf to install packages, Chainguard images use apk to manage packages.

This means that you should convert instances of apt, yum and dnf to apk in RUN lines.

For instance, for apt, lines like this:

RUN apt-get update \
    && apt-get install -y software-properties-common=0.99.22.9 \
    && add-apt-repository ppa:libreoffice/libreoffice-still \
    && apt-get install -y libreoffice \
    && apt-get clean

Should become:

RUN apk --no-cache add libreoffice

And lines like this:

RUN yum update -y && \
    yum -y install httpd php php-cli php-common && \
    yum clean all && \
    rm -rf /var/cache/yum/*

RUN dnf update -y && \
    dnf -y install httpd php php-cli php-common && \
    dnf clean all

RUN microdnf update -y && \
    microdnf -y install httpd php php-cli php-common && \
    microdnf clean all

Should become:

RUN apk add --no-cache httpd php php-cli php-common

Don't just remove apt lines. Replace them with apk equivalents.

Root Permissions

Chainguard images typically run as a non root user with the UID 65532, rather than root. You will need to switch to root before running apk add and then revert back to 65532 after.

USER root
RUN apk add --no-cache httpd php php-cli php-common
USER 65532

Users

As mentioned above, Chainguard images typically run as a non root user with the UID 65532, rather than root. Commonly, this user is called nonroot, but not always. For instance, in the node image the user is called node.

To be safe, always prefer the UID when issuing USER statements or changing the permissions of files.

You should switch to the root user with USER root before running privileged commands (like npm) and then use USER 65532 after to return to the non root user.

You can figure out which user the image is configured to use by querying the image configuration. How you do that depends on the tools you have available:

# With crane.
crane config cgr.dev/chainguard/python | jq -r '.config.User'

# With docker.
docker inspect --format='{{ .Config.User }}' cgr.dev/chainguard/python

You can also find this information in the Specifications tab of the Chainguard Image Directory:

https://images.chainguard.dev/directory/image/python/specifications

Entrypoints

Unlike upstream images, the entrypoint for Chainguard base images is typically the runtime interpreter for the given language (i.e java, python, php) rather than a shell like sh or bash.

This means that a CMD like CMD ["python", "app.py"] will cause an error in a Chainguard images because it translates to running python python app.py.

We should prefer to use explicit entrypoints like:

ENTRYPOINT ["python", "app.py"]

PHP

It's common in Dockerfiles that build PHP applications to install composer in this way:

COPY --from=composer:latest /usr/bin/composer /usr/local/bin/composer

This is unnecessary when using the Chainguard php image because composer is already included in the -dev tags. Therefore, you can remove any lines that install composer.

Troubleshooting

Missing Shell

If you get errors complaining about a missing sh or bash, then ensure you are using a -dev image, which provides a shell.

Permission Denied

If you get errors complaining about permissions, then it's probably to do with the non root user. Switch to USER root temporarily and then switch back to USER 65532 once you've completed the privileged operation.

Check the Overview page

The Overview page for the Chainguard image typically includes information that is helpful when performing a migration.

https://images.chainguard.dev/directory/image/<image-name>/overview

If you run into issues, it is worth checking this page for guidance.

MCP servers 1

Sponsors

Details

Marketplace
chainguard-demo/claude-plugins
Source
chainguard-codegen
Category
Community

More from chainguard-demo/claude-plugins

All 2