Debug Container

A minimal Alpine-based debug container with bash and curl, built for multiple architectures.

Features

• Based on Alpine Linux
• Includes bash and curl
• Multi-architecture support (amd64 and arm64)
• Automated CI/CD pipeline for building and publishing

Container Registry

Images are automatically built and pushed to the container registry when semantic version tags are created.

Building and Publishing

Automated CI/CD Pipeline

The project uses Forgejo Actions to automatically build and publish multi-arch container images.

Pipeline Jobs

1. Build Jobs: Build architecture-specific images in parallel

   • build-amd64 - Builds for AMD64/x86_64 architecture (runs on docker runner)
   • build-arm64 - Builds for ARM64/aarch64 architecture (runs on docker-arm64 runner)

2. Manifest Job: Creates multi-arch manifests

   • Combines both architecture images into a single manifest
   • Tags the image with the version from the git tag
   • If this is the latest version, also tags as :latest

Triggering a Build

The pipeline only runs when you push a semantic version tag:

# Create a new version tag
git tag v1.0.0

# Push the tag
git push origin v1.0.0

Supported tag formats:

• v1.0.0 or 1.0.0 (standard version)
• v1.0.0-beta.1 (pre-release)
• v1.0.0+build.123 (build metadata)

Image Tags

After a successful build, images are available with the following tags:

• <registry>/<owner>/<repo>:v1.0.0 - Multi-arch image for the specific version
• <registry>/<owner>/<repo>:latest - Multi-arch image (only if this is the latest version)

Architecture-specific images (used internally by the manifest):

• <registry>/<owner>/<repo>:v1.0.0-amd64
• <registry>/<owner>/<repo>:v1.0.0-arm64

Latest Tag Logic

The pipeline automatically determines if the current tag is the latest version by:

1. Fetching all git tags
2. Filtering for semantic version tags
3. Sorting them using version sort
4. Comparing the current tag with the latest

If the current tag matches the latest version, it also pushes the image with the :latest tag.

Using the Container

Pull from Registry

# Pull the latest version
docker pull <registry>/<owner>/<repo>:latest

# Pull a specific version
docker pull <registry>/<owner>/<repo>:v1.0.0

Docker will automatically pull the correct architecture for your platform.

Run the Container

# Run interactively
docker run -it <registry>/<owner>/<repo>:latest

# Run with a specific command
docker run --rm <registry>/<owner>/<repo>:latest curl -I https://example.com

Use in Kubernetes

apiVersion: v1
kind: Pod
metadata:
  name: debug-pod
spec:
  containers:
  - name: debug
    image: <registry>/<owner>/<repo>:latest
    command: ["/bin/bash"]
    stdin: true
    tty: true

Then exec into it:

kubectl exec -it debug-pod -- /bin/bash

Requirements

Forgejo Runners

The pipeline requires two Forgejo runners:

1. AMD64 Runner: Labeled docker:host, running on an AMD64 host with Docker installed
2. ARM64 Runner: Labeled docker-arm64:host, running on an ARM64 host with Docker installed

Both runners use the :host execution mode (jobs run directly on the host).

Secrets and Variables

The following must be configured in Forgejo (Settings > Secrets / Variables):

Secrets:

• DOCKER_PAT - A Personal Access Token with package:write scope for pushing to the container registry

Variables:

• REGISTRY_HOST - The Forgejo instance hostname (e.g., forgejo.example.com), used to construct image tags

Local Development

To build the image locally:

# Build for your native architecture
docker build -t debug-container .

# Build for a specific architecture
docker build --platform linux/amd64 -t debug-container:amd64 .
docker build --platform linux/arm64 -t debug-container:arm64 .