wagtaildigital/chisel repository overview

⁠Chisel - Minimal Container Image Builder

A Docker image for Canonical's Chisel⁠, a powerful tool that creates minimal container images by cutting out unnecessary components from a base Ubuntu image.

⁠What is Chisel?

Chisel is a tool developed by Canonical that allows you to create minimal container images by selectively including only the components you need from a base Ubuntu image. This results in:

• Smaller image sizes: Reduce your container footprint by including only what you need
• Improved security: Fewer components mean a smaller attack surface
• Faster deployments: Smaller images download and start faster
• Reduced resource usage: Minimal images use less disk space and memory

⁠Supported Tags

• latest: The most recent build of the image
• latest-hardened: The most recent hardened build
• v1.1.0: Full version of Chisel
• v1.1.0-hardened: Full version of Chisel with hardened configuration
• v1.1.0-ubuntu24.04: Specific Chisel version on specific Ubuntu version
• v1.1.0-ubuntu24.04-hardened: Hardened version for specific Chisel and Ubuntu versions

For a complete list of tags, see the Docker Hub Tags page⁠.

⁠Quick Start

# Pull the latest image
docker pull wagtaildigital/chisel:latest

# Run Chisel
docker run --rm wagtaildigital/chisel

# Create a minimal image with specific packages
docker run --rm -v $(pwd)/output:/rootfs wagtaildigital/chisel cut \
  --release ubuntu-24.04 \
  --root /rootfs \
  --arch amd64 \
  base-files_base \
  ca-certificates_data \
  bash_bins

⁠Usage Examples

⁠Creating a Minimal Base Image

# Create a directory for the output
mkdir -p my-minimal-image

# Run Chisel to create a minimal base image
docker run --rm -v $(pwd)/my-minimal-image:/rootfs wagtaildigital/chisel cut \
  --release ubuntu-24.04 \
  --root /rootfs \
  --arch amd64 \
  base-files_base \
  base-files_release-info \
  ca-certificates_data \
  libc6_libs \
  bash_bins \
  coreutils_bins

# Use the minimal image in a Dockerfile
cat > Dockerfile << EOF
FROM scratch
COPY my-minimal-image /
CMD ["/bin/bash"]
EOF

# Build your minimal image
docker build -t my-minimal-image .

⁠Using Chisel in a Multi-stage Build

# First stage: Use Chisel to create a minimal filesystem
FROM wagtaildigital/chisel:v1.1.0 AS chisel
RUN mkdir -p /rootfs
RUN chisel cut --release ubuntu-24.04 --root /rootfs --arch amd64 \
    base-files_base \
    ca-certificates_data \
    libc6_libs \
    python3-minimal_bins \
    python3-minimal_libs

# Second stage: Create the final image from the minimal filesystem
FROM scratch
COPY --from=chisel /rootfs /
COPY ./app /app
WORKDIR /app
CMD ["python3", "app.py"]

⁠Configuration Options

The Docker image can be configured using the following build arguments:

⁠Troubleshooting

⁠Common Issues

Issue: Error when running Chisel: "failed to cut: no such package"
Solution: Make sure you're specifying valid package names. You can find available packages by running chisel list-slice-content.

Issue: Permission denied when writing to the output directory
Solution: Make sure the directory has the correct permissions or run the container with the appropriate user.

⁠License

This project is licensed under the MIT License.

⁠Source Code

The source code for this Docker image is available on GitHub⁠.