Tom Foster 89aff24960 docs(build): improve documentation accuracy and fix CI mirror patterns

Remove redundant fedora.md file and update remaining documentation for
technical accuracy and writing quality. Fix CI mirror job regex patterns
to recognise single Node.js version tags after recent build optimisation.

Documentation changes include correcting Python installation descriptions,
updating all NODE_VERSIONS references to NODE_VERSION, and fixing Docker
package references for Fedora (moby-engine not docker-ce).

2025-09-13 13:59:53 +01:00

5.1 KiB

Raw Permalink Blame History

Building ACT runner images locally

This guide explains how to build your own ACT runner images locally for testing or customisation.

Prerequisites

You'll need Docker installed and running on your system. Follow the official Docker Engine Installation Guide for your platform. Docker BuildKit should be enabled (it's the default in modern Docker versions).

Clone the repository:

git clone https://git.tomfos.tr/tom/act-runner.git
cd act-runner

Building images

The images are now built in a single step with all components (Ubuntu/Fedora + Node.js + Python) included:

Build Ubuntu images

docker build -f docker/ubuntu.Dockerfile \
  --build-arg UBUNTU_VERSION=24.04 \
  --build-arg NODE_VERSION=22 \
  --build-arg PYTHON_VERSION=3.13 \
  -t act-runner:ubuntu24.04-node22-py3.13 \
  ./docker

For native Python instead of deadsnakes:

docker build -f docker/ubuntu.Dockerfile \
  --build-arg UBUNTU_VERSION=24.04 \
  --build-arg NODE_VERSION=22 \
  --build-arg PYTHON_VERSION=3.12 \
  --build-arg USE_NATIVE_PYTHON=true \
  -t act-runner:ubuntu24.04-node22-py3.12 \
  ./docker

Build Fedora images

docker build -f docker/fedora.Dockerfile \
  --build-arg FEDORA_VERSION=42 \
  --build-arg NODE_VERSION=22 \
  -t act-runner:fedora42-node22-py3.13 \
  ./docker

Available versions typically include current LTS releases and the rolling/rawhide release. Check the workflow files for the current matrix of supported versions.

Build arguments

Ubuntu Dockerfile (docker/ubuntu.Dockerfile):

UBUNTU_VERSION - Ubuntu version to use (e.g. "24.04")
NODE_VERSION - Node.js version (e.g. "22")
PYTHON_VERSION - Python version (e.g. "3.13")
USE_NATIVE_PYTHON - Set to "true" to use native Ubuntu Python (now default behaviour)
K8S_VERSION - Kubernetes version for repository setup (e.g. "1.31")

Fedora Dockerfile (docker/fedora.Dockerfile):

FEDORA_VERSION - Fedora version to use (e.g. "42" or "rawhide")
NODE_VERSION - Node.js version (e.g. "22")
K8S_VERSION - Kubernetes version for repository setup (e.g. "1.31")

BuildKit features

The Dockerfiles use BuildKit cache mounts for optimal caching:

APT/DNF package cache (/var/cache/apt, /var/lib/apt for Ubuntu; /var/cache/dnf, /var/lib/dnf for Fedora)
Download cache (/tmp/downloads)
Python package cache (/root/.cache/uv)

To benefit from these caches, ensure BuildKit is enabled:

export DOCKER_BUILDKIT=1

Or use Docker Buildx:

docker buildx build -f docker/ubuntu.Dockerfile \
  --build-arg UBUNTU_VERSION=24.04 \
  --build-arg NODE_VERSION=22 \
  --build-arg PYTHON_VERSION=3.13 \
  -t act-runner:ubuntu24.04-node22-py3.13 \
  ./docker

Multi-architecture builds

To build for multiple architectures (requires Docker Buildx):

# Create a builder instance
docker buildx create --use

# Build for multiple platforms
docker buildx build -f docker/ubuntu.Dockerfile \
  --platform linux/amd64,linux/arm64,linux/ppc64le,linux/s390x \
  --build-arg UBUNTU_VERSION=24.04 \
  --build-arg NODE_VERSION=22 \
  --build-arg PYTHON_VERSION=3.13 \
  -t act-runner:ubuntu24.04-node22-py3.13 \
  --push \
  ./docker

Testing your images

With Docker:

docker run --rm -it act-runner:ubuntu24.04-node22-py3.13 bash

With ACT:

act -P ubuntu-latest=act-runner:ubuntu24.04-node22-py3.13

In GitHub/Forgejo Actions:

jobs:
  test:
    runs-on: ubuntu-latest
    container: act-runner:ubuntu24.04-node22-py3.13
    steps:
      - uses: actions/checkout@v4
      - run: python --version
      - run: node --version

Customisation tips

To add system packages, edit the appropriate Dockerfile and add packages to the apt-get install command. Remember to:

Keep packages alphabetically sorted for maintainability
Use --no-install-recommends to minimise image size
Clear apt lists with rm -rf /var/lib/apt/lists/*

To change tool versions:

Node.js: Modify NODE_VERSION build argument
Python: Modify PYTHON_VERSION build argument
Ubuntu: Modify UBUNTU_VERSION build argument

For tools that should be available in all images, add them to the base section of each Dockerfile. For language-specific tools, add them to the appropriate Dockerfile.

Troubleshooting

Build failures

Network issues: Check your internet connection and Docker's DNS settings
Space issues: Ensure you have enough disk space for Docker images
BuildKit not enabled: Ensure Docker BuildKit is enabled (export DOCKER_BUILDKIT=1)

Cache issues

If builds aren't using cache as expected:

# Clear builder cache
docker builder prune

# Force rebuild without cache
docker build --no-cache -f docker/ubuntu.Dockerfile \
  --build-arg UBUNTU_VERSION=24.04 \
  --build-arg NODE_VERSION=22 \
  --build-arg PYTHON_VERSION=3.13 \
  -t act-runner:ubuntu24.04-node22-py3.13 \
  ./docker

Contributing

When contributing changes:

Test your builds locally first
Ensure all combinations in the CI matrix still build
Update this documentation if you change build processes
Follow the existing code style and conventions

5.1 KiB Raw Permalink Blame History