railpack

Configure and troubleshoot Railpack builds, with emphasis on RAILPACK_* environment variables, railpack.json overlays, build-plan inspection, local CLI installation and usage, and local BuildKit containers. Use for Railpack provider configuration, custom install/build/start commands, Mise or Apt packages, build or runtime variables and secrets, generated-plan debugging, BUILDKIT_HOST errors, or running Railpack from a release or source checkout.

Install
npx skills add 'https://github.com/railwayapp/railpack/tree/main/.'
Incomplete bundle · no download
main · 21a254fScanned 2026-09-17

Contributors

GitHub-linked commit authors for this SKILL.md at the saved revision. Co-authors and history before file renames are not included.

File history ↗

.mise/tasks/images.toml

.mise/tasks/images.tomlBrowse 1970 files
View on GitHub
← Back to SKILL.md
[image-builder-build]run = "docker build --build-arg MISE_VERSION=$RAILPACK_MISE_VERSION -f images/debian/build/Dockerfile -t railpack-builder:local ." [mise-builder-shell]description = "Shell into the railpack-builder image"usage = 'flag "--local" help="Build and use railpack-builder:local instead of the ghcr image"'run = '''if [ "${usage_local:-false}" = "true" ]; then  mise run image-builder-build  image="railpack-builder:local"else  image="ghcr.io/railwayapp/railpack-builder:mise-$RAILPACK_MISE_VERSION"fiexec docker run -it --rm "$image" bash''' [image-runtime-build]run = "docker build -f images/debian/runtime/Dockerfile -t railpack-runtime:local ." [image-frontend-build]description = "Build the railpack frontend image and push to local registry"run = [  "docker build -f images/alpine/frontend/Dockerfile -t railpack-frontend:local .",  # in order for builtctl to use this image, it needs to exist on a registry  "docker tag railpack-frontend:local localhost:7890/railpack-frontend:local",  "docker push localhost:7890/railpack-frontend:local",] [image-run-registry]description = "Local image registry for frontend images and BuildKit cache (HTTP on :7890)"run = '''docker rm -f railpack-registry 2>/dev/null || truedocker run -d --rm \  --name railpack-registry \  -p 7890:5000 \  registry:2''' [image-frontend-build-project]description = "Build a project dir with the local railpack frontend via buildctl with debug logging enabled and a local cache registry"usage = 'arg "<dir>" help="Project directory to build (e.g. examples/node-bun)"'run = '''set -euxo pipefail dir="${usage_dir:?dir is required}"if [ ! -d "$dir" ]; then  echo "directory not found: $dir" >&2  exit 1fi project_name="$(basename "$dir")" plan_dir="tmp/frontend-plan"mkdir -p "$plan_dir"mise run cli plan "$dir" --out "$plan_dir/railpack-plan.json" # host.docker.internal is required since the frontend container is running inside a buildx containerbuildctl --debug build \  --frontend=gateway.v0 \  --opt source=host.docker.internal:7890/railpack-frontend:local \  --opt build-arg:verbose=true \  --opt image-resolve-mode=pull \  --local "context=$dir" \  --local "dockerfile=$plan_dir" \  --progress=plain \  --trace="$plan_dir/build.trace" \  --debug-json-cache-metrics stdout \  --export-cache type=registry,ref=host.docker.internal:7890/"$project_name":cache,mode=max \  --import-cache type=registry,ref=host.docker.internal:7890/"$project_name":cache'''