
chainguard-codegen
Generate secure Dockerfiles, apko/melange configs, and migrate to Chainguard Containers
- GitHub stars
- 8
Install
/plugin install chainguard-codegen@chainguard-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add chainguard-demo/claude-plugins.
Contents
Discovered from sourceSkills 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-asto 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-pipnodejs-22,npmruby-3.3go-1.22openjdk-17,openjdk-17-default-jvm
Web Servers:
nginxcaddyapache2
Databases:
postgresql-16mariadbredis
Utilities:
busybox(basic Unix utilities)ca-certificates-bundle(SSL certificates — include this for any image making HTTPS calls)curlgitbash(if a shell is needed)
Best Practices:
- Minimal packages: Only include what's needed at runtime
- Non-root user: Always run as UID 65532
- No dev tools at runtime: Use a separate build stage for compilation
- ca-certificates-bundle: Include whenever the image makes outbound HTTPS calls
- Full binary path in entrypoint: Use
/usr/bin/python3, not justpython3
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:
- Use Chainguard Containers: Always start with a Chainguard base image from cgr.dev/chainguard/*
- Multi-stage builds: Use multi-stage builds to minimize final image size
- Non-root user: Ensure the container runs as a non-root user (UID 65532)
- Minimal layers: Combine commands to reduce layers
- No secrets: Never include secrets in the Dockerfile
- Best practices: Follow Docker and Chainguard best practices
Common Chainguard Containers:
- Python:
cgr.dev/chainguard/python:latestorcgr.dev/chainguard/python:latest-dev(includes pip, build tools) - Node.js:
cgr.dev/chainguard/node:latestorcgr.dev/chainguard/node:latest-dev - Go:
cgr.dev/chainguard/go:latest(for building) andcgr.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 uselatest, no-devvariant) - 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
:latestfor production deployments (minimal attack surface) - Use
:latest-devfor build stages or development - Use
chainguard-basewhen replacing a generic Linux distro (debian, ubuntu, alpine) - Use
wolfi-basewhen you need apk at runtime - Use
staticfor compiled static binaries (Go, Rust, C) withCGO_ENABLED=0 - Use
-fipsvariants 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 databaseanalyze_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:
- What is the Chainguard organization name? (use
ORGANIZATIONas placeholder if unknown; usechainguardfor free tier) - Is FIPS compliance required? (FIPS images have a
-fipssuffix, e.g.python-fips) - Should images be pulled from
cgr.devdirectly, or from a proxied/mirrored registry? - 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
- Use
analyze_dockerfileto understand the current structure - Use
convert_dockerfilefor automated conversion - Review and correct the output using the guidance below
- Explain each change and its security benefit
Image Mapping
| Original | Chainguard Image | Notes |
|---|---|---|
python:* | cgr.dev/ORGANIZATION/python | Use -dev for build stages |
node:* | cgr.dev/ORGANIZATION/node | Use -dev for npm/yarn install |
golang:* | cgr.dev/ORGANIZATION/go + static:latest | Build with go, run in static |
nginx:* | cgr.dev/ORGANIZATION/nginx | Drop-in replacement |
postgres:* | cgr.dev/ORGANIZATION/postgres | Compatible |
redis:* | cgr.dev/ORGANIZATION/redis | Compatible |
ruby:* | cgr.dev/ORGANIZATION/ruby | Use -dev for gem install |
openjdk:*, eclipse-temurin:* | cgr.dev/ORGANIZATION/jdk (build) / jre (runtime) | |
maven:* | cgr.dev/ORGANIZATION/maven | |
php:* | cgr.dev/ORGANIZATION/php | Use -dev for composer |
ubuntu:*, debian:* | cgr.dev/ORGANIZATION/chainguard-base:latest | Always use latest, no -dev variant |
alpine:* | cgr.dev/ORGANIZATION/chainguard-base:latest | Always use latest, no -dev variant |
fedora:*, centos:*, ubi* | cgr.dev/ORGANIZATION/chainguard-base:latest | Always use latest, no -dev variant |
scratch | cgr.dev/ORGANIZATION/static:latest | For 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-devvariant - Provides
apkfor 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
-devsuffix when the stage hasRUNcommands (exceptchainguard-base) - Final stage of a multi-stage build should use non-dev unless it has
RUNcommands
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:
- Use the dfc MCP server for automated conversion where available
- Apply tag mapping rules
- Look up unknown images using the ai-docs MCP server
- 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:
chainguard-basealways useslatest— never add a version or-devsuffix- No tag or non-semantic tag →
latestFROM node→FROM cgr.dev/ORGANIZATION/node:latestFROM node:lts→FROM cgr.dev/ORGANIZATION/node:latest
- Semantic version → truncate to major.minor
FROM node:14.17.3→FROM cgr.dev/ORGANIZATION/node:14.17
- Add
-devsuffix when the stage hasRUNcommands (exceptchainguard-base)FROM node:14(stage has RUN) →FROM cgr.dev/ORGANIZATION/node:14-devFROM node:14(no RUN) →FROM cgr.dev/ORGANIZATION/node:14
- Final stage of a multi-stage build should use a non-dev image unless it
has
RUNcommands
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 Image | Chainguard Image | Notes |
|---|---|---|
node, node:* | cgr.dev/ORGANIZATION/node | |
python:* | cgr.dev/ORGANIZATION/python | |
golang:*, go:* | cgr.dev/ORGANIZATION/go | Use static for distroless runtime |
golang:*-alpine | cgr.dev/ORGANIZATION/go | Strip 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:*-fpm | cgr.dev/ORGANIZATION/php:latest-fpm | Pass 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:latest | Always latest, no -dev variant |
alpine:* | cgr.dev/ORGANIZATION/chainguard-base:latest | Always latest, no -dev variant |
fedora:*, centos:*, ubi* | cgr.dev/ORGANIZATION/chainguard-base:latest | Always latest, no -dev variant |
scratch | cgr.dev/ORGANIZATION/static:latest | For 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
latesttag - There is no
latest-devvariant forchainguard-base chainguard-baseprovidesapkfor 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-fipsnode→node-fipsgo→go-fipsjdk→jdk-fipschainguard-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 imagesget_image_docs(image_name)— get documentation for a specific imagesearch_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:
- Download package mappings
- Map package name
- 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:
- Clarify instructions with the user
- Convert the Dockerfile
- Modify
FROMstatements to use Chainguard images. - Migrate any uses of other OS package managers to
apk - Adjust users and permissions where required.
- Modify
- Test the conversion
- Build the image
- Run the image
- 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:
- What is the Chainguard organization name? Each Chainguard customer has their
own organization and it will be referred to generically as
ORGANIZATIONin these instructions. - Is FIPS required? Chainguard offers FIPS compliant images that have the
suffix
-fips. For instance:python-fips. - Should images be pulled directly from
cgr.dev? Or, if images are hosted/proxied from another repository, what is that repository? - Should you test the conversion?
- Should you try and build the image to validate the conversion worked?
- 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