Dockerfile Reference

Overview

The multi-stage Dockerfile produces a deployment-ready Ubuntu 24.04 image with Claude Code and 32+ SRE/DevOps tools. The container runs as non-root (UID 10000) with tini as PID 1 for proper signal handling and zombie process reaping.

Build Stages

The Dockerfile uses two build stages. Stage 1 downloads static binary tools, and Stage 2 assembles the final runtime image — installing apt packages, copying tools from Stage 1, and installing Claude Code via its native binary installer.

Multi-Stage Build

Two stages: tools-downloader feeds static binaries into the runtime image.

Stage 1 tools-downloader tini, kubectl, helm k9s, stern, kubectx kubens, jq, yq trivy, grype 11 static binaries COPY --from Stage 2: runtime Ubuntu 24.04 + apt tools (curl, dig, nmap, htop, git...) + database clients (psql, mysql, redis-cli) + Claude Code (native binary installer) + scripts (entrypoint, healthcheck, readiness) + MCP config + DevOps skills UID 10000 tini PID 1 32+ tools curl https://claude.ai/install.sh | bash

Version Pins

All tool versions are pinned via global ARG declarations at the top of the Dockerfile. This ensures reproducible builds and explicit upgrade control.

ARG Version Purpose
UBUNTU_VERSION24.04Base OS image
CLAUDE_CODE_VERSION2.1.62Claude Code CLI (native binary)
TINI_VERSION0.19.0Minimal init system (PID 1)
KUBECTL_VERSION1.35.1Kubernetes CLI
HELM_VERSION4.1.1Helm package manager
K9S_VERSION0.50.18Terminal-based K8s UI
STERN_VERSION1.33.0Multi-pod log tailing
KUBECTX_VERSION0.9.5Context/namespace switcher
JQ_VERSION1.8.1JSON processor
YQ_VERSION4.52.4YAML processor
TRIVY_VERSION0.68.2Vulnerability scanner
GRYPE_VERSION0.109.0Container image scanner

Installed Tools

Tools are organized by category, matching the structure in verify-tools.sh. Privileged tools (marked with *) require elevated capabilities at runtime and are verified by binary existence only.

Category Count Tools
Network9curl, dig, nmap, tcpdump*, wget, netcat, ip, ss, ping
Process/System6htop, strace*, ps, top, perf*, bpftrace*
Kubernetes6kubectl, helm, k9s, stern, kubectx, kubens
Data/Log3jq, yq, less
Database Clients3psql, mysql, redis-cli
Security2trivy, grype
Standard8git, vim, nano, unzip, file, tree, ripgrep, bash
Claude Code1claude

* Requires elevated capabilities (CAP_NET_RAW, CAP_SYS_PTRACE). Checked for binary existence only during verification.

Security

The container follows Kubernetes security best practices:

  • Non-root execution -- UID/GID 10000, above the typical system (0-999) and user (1000-9999) ranges. Avoids host UID conflicts and satisfies PodSecurityStandard restricted profiles.
  • podSecurityContext alignment -- The Helm chart sets runAsUser: 10000, runAsGroup: 10000, runAsNonRoot: true as belt-and-suspenders with the Dockerfile's USER directive.
  • Pre-configured Claude settings -- Bypasses permission prompts, disables telemetry, autoupdater, and error reporting. Settings are staged in /app/.claude-settings.json and copied into the PVC at /app/.claude/settings.json by the entrypoint on each startup.
  • tini as PID 1 -- Provides proper signal forwarding (SIGTERM, SIGINT) and zombie process reaping. Docker does not provide init behavior by default.

Multi-Architecture Support

The Dockerfile supports both linux/amd64 and linux/arm64 via Docker BuildKit's TARGETARCH variable. Each tool download maps TARGETARCH to the vendor's naming convention:

  • Standard (amd64/arm64) -- kubectl, helm, k9s, stern, jq, yq, grype
  • kubectx/kubens -- uses x86_64 instead of amd64
  • trivy -- uses 64bit (amd64) and ARM64 (arm64)
  • Claude Code -- native installer auto-detects architecture

Build Command

Single architecture

docker build
$ docker build -f docker/Dockerfile -t claude-in-a-box:dev .

Multi-platform

docker buildx
$ docker buildx build --platform linux/amd64,linux/arm64 -f docker/Dockerfile -t claude-in-a-box:dev .