Skip to content

Set Up a Development Environment

Target audience: Developers, Maintainers Goal: Configure your local machine for StageX development.

Prerequisites

  • OS: Linux (x86_64) or macOS (Apple Silicon / Intel)
  • Hardware: See System Requirements for hardware specs by workload type (single package vs full tree)
  • sudo access
  • Internet connection (first build downloads all source tarballs)

Step 1: Install Docker + containerd Image Store

StageX building requires Docker with the containerd image store. Podman is not supported for building — only for consuming images.

Install Docker Engine 25+:

# Debian / Ubuntu
sudo apt-get install docker-ce docker-ce-cli containerd.io
# Fedora / RHEL
sudo dnf install docker-ce docker-ce-cli containerd.io
# Arch Linux
sudo pacman -S docker containerd
# macOS
# Install Docker Desktop (buildx included)

Enable the containerd image store — create or edit /etc/docker/daemon.json:

{
  "features": {
    "containerd-snapshotter": true
  }
}

Restart and verify:

sudo systemctl restart docker
docker info -f '{{ .DriverStatus }}' | grep io.containerd.snapshotter.v1

If the grep returns empty, building will fail.

Step 2: Install Build Tools

Tool Minimum Install
bash 5.0 apt/yum install bash / brew install bash
make any apt/yum install make / brew install make
git any apt/yum install git / brew install git
curl any apt/yum install curl / brew install curl
jq 1.6 apt/yum install jq / brew install jq
gpg 2.2 apt install gpg / yum install gnupg2 / brew install gnupg

Versions match what compat.sh checks — a snapshot of the CI environment.

Step 3: Install Docker Buildx

Buildx 0.30.1+ is required. Docker Desktop includes it; on Linux install the plugin:

# Debian / Ubuntu
sudo apt-get install docker-buildx-plugin
# Fedora / RHEL
sudo dnf install docker-buildx-plugin
# Arch Linux
sudo pacman -S docker-buildx

Verify:

docker buildx version

Step 4: Clone the Repo

git clone --depth=1 https://codeberg.org/stagex/stagex.git
cd stagex

Checkout the current release branch (release/YYYY.MM.* per MAINTENANCE.md):

git branch --list 'release/*'
git checkout release/2026.05.0

Step 5: Verify with make compat

This is the single most useful diagnostic — it checks all tooling at once. Run it from your StageX clone:

make compat

A clean exit means everything is ready. Failure reports the specific missing or outdated tool.

Step 6: Build a Single Package

Build pallet-rust — the Rust toolchain image — entirely from source:

make pallet-rust
  • First build downloads all source tarballs (~5–10 min).
  • Subsequent builds reuse cached downloads.
  • For preseed workflows, see Reproduce Builds.

Step 7: Verify Local Build

make verify

Compares local build digests against committed digests. Clean exit confirms bit-for-bit reproducibility. See Reproduce Builds for manual comparison.

Step 8 (Optional): Configure GPG

GPG 2.2+ is needed for signature verification (installed in Step 2 if not):

# macOS
brew install gnupg

For keyring import and policy.json configuration, see Verify Attestations.

Troubleshooting

Problem Fix
docker: command not found Install Docker Engine (Step 1).
make: docker: No such file or directory Docker not in PATH — log out and back in, or start Docker Desktop.
Error response from daemon Daemon not running. sudo systemctl start docker or launch Docker Desktop.
Build fails at docker save Containerd image store not enabled. Fix daemon.json per Step 1.
buildx: command not found Install docker-buildx-plugin (Linux) per Step 3.
permission denied on socket User not in docker group: sudo usermod -aG docker $USER && newgrp docker.
no space left on device docker system prune -af.
bash 5.0+ required Upgrade bash. macOS: brew install bash.
unsupported platform QEMU binfmt missing. Run: docker run --privileged --rm tonistiigi/binfmt --install all.

See Also