kurtosis-techkurtosis-tech/kurtosis/skills/docker-local-build/SKILL.md

docker-local-build

Skill558 starsChanged 3 years agoApache-2.0View on GitHub

Build and test Kurtosis from source on local Docker. Compiles all components (engine, core, files-artifacts-expander), builds Docker images, installs the CLI, and restarts the engine. Use when developing Kurtosis and testing changes locally with Docker.

In this repository21 other files it gives its agents.
- cleanSkill
- cli-local-buildSkill
- cluster-manageSkill
- context-manageSkill
- docker-debugSkill
- dumpSkill
- enclave-inspectSkill
- engine-manageSkill
- files-inspectSkill
- gatewaySkill
- graflokiSkill
- import-composeSkill
- k8s-clean-clusterSkill
- k8s-debug-podsSkill
- k8s-dev-deploySkill
- lintSkill
- portalSkill
- port-forwardSkill
- run-packageSkill
- service-manageSkill
- starlark-devSkill

The file

We split this skill into the rules it gives an agent

5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.

≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.

Common
Distinctive
Very specific

Very specific:
All images are tagged with the current git short SHA (+ -dirty if uncommitted changes exist) via scripts/get-docker-tag.sh.
line 22
Distinctive:
Run the wrapper script from the repo root.
line 26
Very specific:
Use scripts/docker-image-builder.sh which creates a buildx builder, builds for the local platform with --load, and cleans up
line 88
Distinctive:
After making code changes:
line 136
Very specific:
If you have uncommitted changes, the tag gets a -dirty suffix
line 140

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.

Keep what fits and drop the rest. Your version, ready for your agents.

Files

SKILL.md

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

Variable	Default	Description
`INSTALL_PATH`	`/usr/local/bin/kurtosis`	Where to install the CLI binary
`BUILD_IMAGES`	`true`	Set to `false` to skip Docker image builds (CLI only)
`DEBUG_IMAGE`	`false`	Build debug images with delve debugger
`PODMAN_MODE`	`false`	Use podman instead of docker
`RESET_KURTOSIS_AFTER_BUILD`	`true`	Stop engine and clean containers after build

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

Component	Source	Dockerfile	Image
Engine	`engine/server/engine/main.go`	`engine/server/Dockerfile`	`kurtosistech/engine`
Core (APIC)	`core/server/api_container/main.go`	`core/server/Dockerfile`	`kurtosistech/core`
Files Artifacts Expander	`core/files_artifacts_expander/main.go`	`core/files_artifacts_expander/Dockerfile`	`kurtosistech/files-artifacts-expander`
CLI	`cli/cli/main.go`	N/A	N/A
Version	`kurtosis_version/kurtosis_version.go`	N/A	N/A
Version generator	`scripts/generate-kurtosis-version.sh`	N/A	N/A
Docker tag	`scripts/get-docker-tag.sh`	N/A	N/A
Image builder	`scripts/docker-image-builder.sh`	N/A	N/A

Iterating

After making code changes:

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

Common issues

Symptom	Fix
`go build` fails with import errors	Run `go mod tidy` in the failing module directory
Docker build fails with `.dockerignore` error	Ensure `.dockerignore` exists in the component's server directory
Engine starts but uses old images	The tag is SHA-based; make sure the built image tag matches `kurtosis version` output
`webapp directory not found` warning	Normal when building without enclave-manager; an empty placeholder is created automatically
buildx builder conflict	Remove stale builders: `docker buildx rm kurtosis-docker-builder` and `docker context rm kurtosis-docker-builder-context`
Version mismatch between CLI and engine	Rebuild everything from the same commit; version is compiled into the CLI binary

Download now (ZIP)

Does it work?

Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.

No reviews yet

People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.

It worked
Partly
It didn't

What did you use it for? e.g. Reviewing pull requests in a Rails app

Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.

Your trail

Files you open will collect here, so you can find them again.

Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.

Now do this for your own.

Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

Check your setup, free