Skip to content

Reproduce StageX

Rebuild StageX from source and compare your output with the published StageX digests. This is the highest-assurance verification path: it confirms that the published images correspond to the source and build rules you used.

What you need

Before you begin, ensure you have the following:

  • x86_64 system
  • At least 500 GB free disk space
  • Docker Engine v25 or newer (install)
  • Docker containerd image store enabled (enable)
  • GNU Make, installed with your OS package manager
  • git, curl, and jq, installed with your OS package manager

On a 16-core processor, a full StageX rebuild takes about 42 hours.

Podman and Kaniko are not currently officially supported for reproducing StageX, but are intended to be added.

Clone StageX

Run these steps from the machine you will use for the rebuild.

git clone https://codeberg.org/stagex/stagex.git
cd stagex

Check out the release you want to reproduce:

git checkout release/YYYY.MM.N

Replace release/YYYY.MM.N with the exact release branch for the StageX release you want to reproduce.

Build from source

Start from an empty build output and build the full tree:

make clean
make

Do not run make preseed for this verification path. Preseeding downloads already-published layers into the local cache, which is useful for development but not for proving that your machine can reproduce StageX from source.

Generate local digests

After the build completes, generate the digest files from your local output:

make digests

The generated digest files should be written under digests/.

Compare with published digests

Fetch the published digest files for the release you checked out, then compare them with your local files. For example:

for file in bootstrap core pallet user; do
    curl -fsSL "https://codeberg.org/stagex/stagex/raw/branch/release/YYYY.MM.N/digests/$file.txt" \
        -o "published-$file.txt"
    diff -u "published-$file.txt" "digests/$file.txt"
done

Replace release/YYYY.MM.N with the same release branch you built.

No diff means your build reproduced the published digests. Any diff means at least one package digest does not match and needs investigation.

If the build fails or differs

Common causes include:

  • Not enough disk space.
  • Docker or BuildKit version mismatch.
  • Docker containerd image store is not enabled.
  • Building on a non-x86_64 system.
  • Building the wrong release branch.
  • Running with preseeded or stale output when you intended a cold source rebuild.
  • Network interruption while fetching source archives.
  • Local hardware or filesystem issues.

When investigating, first confirm the branch, Docker version, available disk, available RAM, and whether out/, fetch/, or Docker build cache data came from an earlier attempt.

If the mismatch or failure is still unclear, join the StageX Matrix room and ask for help. Include the release branch, Docker version, CPU architecture, RAM, free disk space, and the failing command output.

Next steps

After your digests match, here's what to explore next: