Docker Local Build

Docker Local Build

Build all Kurtosis components from source and test them locally on Docker.

Overview

This skill builds the full Kurtosis stack for local Docker testing:

• Engine — Docker image kurtosistech/engine
• Core (APIC) — Docker image kurtosistech/core
• Files Artifacts Expander — Docker image kurtosistech/files-artifacts-expander
• CLI — binary at .tmp/kurtosis, installed to /usr/local/bin/kurtosis

All images are tagged with the current git short SHA (+ -dirty if uncommitted changes exist) via scripts/get-docker-tag.sh. The same tag is compiled into the CLI as KurtosisVersion.

Quick build (recommended)

Run the wrapper script from the repo root. It handles version generation, image builds, CLI compilation, installation, and engine reset:

./scripts/local-build.sh

Environment variables

Examples

# Full build + install + reset
./scripts/local-build.sh

# CLI only (skip image builds)
BUILD_IMAGES=false ./scripts/local-build.sh

# Build with debug images
DEBUG_IMAGE=true ./scripts/local-build.sh

# Install to a custom path
INSTALL_PATH=/tmp/kurtosis ./scripts/local-build.sh

# Skip engine reset (keep running enclaves)
RESET_KURTOSIS_AFTER_BUILD=false ./scripts/local-build.sh

Manual build (step by step)

1. Generate version constants

./scripts/generate-kurtosis-version.sh

This writes the git-based version tag into kurtosis_version/kurtosis_version.go.

2. Build Docker images

The existing build scripts handle binary compilation, unit tests, and Docker image building:

# Build engine image (compiles binary, runs tests, builds Docker image)
./engine/scripts/build.sh

# Build core + files-artifacts-expander images
./core/scripts/build.sh

These scripts:

• Detect the host architecture (amd64/arm64)
• Cross-compile the Go binary for linux
• Run unit tests
• Build a Docker image tagged kurtosistech/<component>:<git-sha>
• Use scripts/docker-image-builder.sh which creates a buildx builder, builds for the local platform with --load, and cleans up

3. Build the CLI

go build -o .tmp/kurtosis ./cli/cli/

4. Install

cp .tmp/kurtosis /usr/local/bin/kurtosis

5. Reset the engine

kurtosis engine stop || true
docker ps -aq --filter "label=com.kurtosistech.app-id=kurtosis" | xargs -r docker rm -f
docker ps -aq --filter "name=kurtosis-engine" | xargs -r docker rm -f
docker ps -aq --filter "name=kurtosis-reverse-proxy" | xargs -r docker rm -f
docker ps -aq --filter "name=kurtosis-logs-collector" | xargs -r docker rm -f
docker ps -aq --filter "name=kurtosis-api--" | xargs -r docker rm -f

6. Start and test

kurtosis engine start
kurtosis run github.com/ethpandaops/ethereum-package
kurtosis clean -a

Key files

Iterating

After making code changes:

1. Re-run ./scripts/local-build.sh (or set BUILD_IMAGES=false if only CLI changed)
2. The version tag changes automatically with each commit (SHA-based)
3. If you have uncommitted changes, the tag gets a -dirty suffix

Common issues