act-docker-setup

name	act-docker-setup
description	Use when configuring Docker environments for act, selecting runner images, managing container resources, or troubleshooting Docker-related issues with local GitHub Actions testing.
allowed-tools	["Read","Write","Edit","Bash","Grep","Glob"]

Act - Docker Configuration and Setup

Use this skill when configuring Docker for act, choosing runner images, managing container resources, and optimizing Docker performance for local GitHub Actions workflow testing.

Runner Images

Image Size Categories

Act supports three image size categories:

Size	Image	Tools	Use Case
Micro	node:16-buster-slim	Minimal	Simple Node.js workflows
Medium	catthehacker/ubuntu:act-*	Common tools	Most workflows
Large	catthehacker/ubuntu:full-*	Everything	Maximum compatibility

Official catthehacker Images

# Latest Ubuntu (22.04)
act -P ubuntu-latest=catthehacker/ubuntu:act-latest

# Specific Ubuntu versions
act -P ubuntu-22.04=catthehacker/ubuntu:act-22.04
act -P ubuntu-20.04=catthehacker/ubuntu:act-20.04

# Full images (larger, more tools)
act -P ubuntu-latest=catthehacker/ubuntu:full-latest
act -P ubuntu-22.04=catthehacker/ubuntu:full-22.04

# Runner images (closest to GitHub)
act -P ubuntu-latest=catthehacker/ubuntu:runner-latest

Language-Specific Images

# Node.js
act -P ubuntu-latest=node:20
act -P ubuntu-latest=node:20-alpine

# Python
act -P ubuntu-latest=python:3.12
act -P ubuntu-latest=python:3.12-slim

# Go
act -P ubuntu-latest=golang:1.22
act -P ubuntu-latest=golang:1.22-alpine

# Ruby
act -P ubuntu-latest=ruby:3.3
act -P ubuntu-latest=ruby:3.3-alpine

Platform Configuration

.actrc Configuration

Create .actrc in project root for persistent settings:

# Default platform images
-P ubuntu-latest=catthehacker/ubuntu:act-latest
-P ubuntu-22.04=catthehacker/ubuntu:act-22.04
-P ubuntu-20.04=catthehacker/ubuntu:act-20.04

# Reuse containers
--reuse

# Container options
--container-architecture linux/amd64
--container-daemon-socket -

# Resource limits
--container-cap-add SYS_PTRACE
--container-cap-add NET_ADMIN

Per-Workflow Configuration

Create .github/workflows/.actrc for workflow-specific settings:

-P ubuntu-latest=node:20
--env-file .env.ci

Command Line Override

# Override .actrc settings
act -P ubuntu-latest=python:3.12 --no-reuse

Container Management

Reusing Containers

# Reuse containers for faster iteration
act --reuse

# Reuse with specific job
act --reuse -j build

# Force recreate containers
act --rm

Container Lifecycle

# List running act containers
docker ps --filter "label=act"

# Stop all act containers
docker stop $(docker ps -q --filter "label=act")

# Remove all act containers
docker rm $(docker ps -aq --filter "label=act")

# Clean up act volumes
docker volume prune

Inspect Containers

# Exec into running container
docker exec -it act-<job-name> /bin/bash

# View container logs
docker logs act-<job-name>

# Inspect container config
docker inspect act-<job-name>

Volume Mounts and Binds

Default Mounts

Act automatically mounts:

• Current directory → /github/workspace
• Act cache → /root/.cache/act
• Docker socket (if needed)

Custom Bind Mounts

# Mount additional directory
act --bind /host/path:/container/path

# Mount multiple directories
act --bind /data:/data --bind /config:/config

# Read-only mount
act --bind /readonly:/readonly:ro

Persistent Cache

# Configure cache location
export ACT_CACHE_DIR=$HOME/.cache/act

# Clean cache
rm -rf $HOME/.cache/act

Docker Configuration

Docker Socket

# Use default Docker socket
act --container-daemon-socket -

# Use custom socket
act --container-daemon-socket /var/run/docker.sock

# Use Docker Desktop socket (Mac)
act --container-daemon-socket unix:///Users/$USER/.docker/run/docker.sock

Container Architecture

# Specify architecture
act --container-architecture linux/amd64

# For Apple Silicon Macs
act --container-architecture linux/arm64

Network Configuration

# Use host network
act --network host

# Use custom network
act --network my-network

# Create isolated network
docker network create act-network
act --network act-network

Resource Management

Memory Limits

# Set memory limit
act --memory 4g

# Set memory and swap
act --memory 4g --memory-swap 8g

CPU Limits

# Limit CPU cores
act --cpus 2

# Set CPU shares
act --cpu-shares 512

Disk Space

# Check Docker disk usage
docker system df

# Clean up unused resources
docker system prune -a

# Remove old act cache
find ~/.cache/act -type d -mtime +30 -exec rm -rf {} +

Security

Capabilities

# Add Linux capabilities
act --container-cap-add SYS_PTRACE

# Drop capabilities
act --container-cap-drop ALL

# Security profile
act --security-opt seccomp=unconfined

Privileged Mode

# Run in privileged mode (use sparingly)
act --privileged

# Safer: add specific capabilities instead
act --container-cap-add SYS_ADMIN

Multi-Platform Builds

Docker Buildx

# Workflow using buildx
jobs:
  build:
    runs-on: ubuntu-latest
    steps:
      - uses: docker/setup-buildx-action@v3
      - uses: docker/build-push-action@v5
        with:
          platforms: linux/amd64,linux/arm64

Test with act:

# Enable buildx in act
act --use-gitignore=false \
    -P ubuntu-latest=catthehacker/ubuntu:act-latest

Troubleshooting

Image Pull Failures

# Pull image manually
docker pull catthehacker/ubuntu:act-latest

# Use cached image
act --pull=false

# Force pull latest
act --pull=true

Permission Issues

# Fix workspace permissions
act --container-options "--user $(id -u):$(id -g)"

# Run as root (not recommended)
act --container-options "--user root"

DNS Issues

# Use custom DNS
act --container-options "--dns 8.8.8.8"

# Use host DNS
act --container-options "--dns-search ."

Container Exit Codes

# Continue on error
act --continue-on-error

# Capture exit code
act; echo $?

Performance Optimization

Image Selection

Choose the smallest image that meets your needs:

# Fast but limited
act -P ubuntu-latest=node:20-alpine

# Balanced
act -P ubuntu-latest=catthehacker/ubuntu:act-latest

# Comprehensive but slow
act -P ubuntu-latest=catthehacker/ubuntu:full-latest

Layer Caching

# Optimize Dockerfile for caching
FROM node:20

# Install system deps first (changes rarely)
RUN apt-get update && apt-get install -y git

# Copy package files (changes sometimes)
COPY package*.json ./

# Install deps (changes sometimes)
RUN npm ci

# Copy source (changes often)
COPY . .

Parallel Jobs

# Run jobs in parallel
act --parallel

# Limit parallelism
act --parallel --jobs 2

Custom Images

Building Custom Image

Create Dockerfile:

FROM catthehacker/ubuntu:act-latest

# Add custom tools
RUN apt-get update && apt-get install -y \
    postgresql-client \
    redis-tools \
    && rm -rf /var/lib/apt/lists/*

# Install specific Node version
RUN curl -fsSL https://deb.nodesource.com/setup_20.x | bash - \
    && apt-get install -y nodejs

# Install global npm packages
RUN npm install -g pnpm yarn

Build and use:

docker build -t my-act-runner .
act -P ubuntu-latest=my-act-runner

Publishing Custom Image

# Tag image
docker tag my-act-runner username/act-runner:latest

# Push to Docker Hub
docker push username/act-runner:latest

# Use in team
act -P ubuntu-latest=username/act-runner:latest

Best Practices

DO

✅ Use .actrc for consistent configuration across team ✅ Choose appropriate image size for your needs ✅ Use --reuse during development ✅ Clean up Docker resources regularly ✅ Pin image versions in production workflows ✅ Use layer caching for faster builds ✅ Document image requirements in README

DON'T

❌ Use :latest tags in production ❌ Run containers in privileged mode unnecessarily ❌ Ignore Docker disk space usage ❌ Use oversized images for simple workflows ❌ Commit large images to version control ❌ Skip Docker resource cleanup ❌ Expose sensitive data in container logs

Common Patterns

Development Setup

# Fast iteration setup
cat > .actrc << 'EOF'
-P ubuntu-latest=catthehacker/ubuntu:act-latest
--reuse
--rm=false
--container-architecture linux/amd64
EOF

CI Validation

# Strict validation setup
act --dryrun \
    --pull=true \
    --no-reuse \
    -P ubuntu-latest=catthehacker/ubuntu:full-latest

Monorepo Setup

# Different images per job
act -j backend -P ubuntu-latest=node:20 \
    -j frontend -P ubuntu-latest=node:20-alpine \
    -j database -P ubuntu-latest=postgres:16

Related Skills

• act-workflow-syntax: Creating workflow files
• act-local-testing: Testing workflows with act CLI
• act-advanced-features: Advanced act usage patterns