Docksmith

Docksmith is an educational, fully offline container builder and runtime written in Go. It keeps a small scope but now models more production-like behavior: stronger Linux isolation, deterministic layers, cache diagnostics, image verification, and richer CLI UX.

Highlights

• Deterministic, immutable image layers (tar + SHA-256)
• Whiteout support for deleted files between layers
• Symlink-aware layers with metadata-preserving copy/extract behavior
• Cache diagnostics showing why a miss happened and which key component changed
• Persistent cache statistics including estimated saved build time
• Linux runtime isolation with PID, mount, IPC, UTS, network, and optional user namespace rootless mode
• Optional seccomp filtering and read-only root filesystem mode
• Runtime overlay layer (when available) for temporary writable container state
• Image export/import as tar archives
• New operational commands: inspect/history/diff/stats/verify/dashboard
• Colored logs, build progress bars, and troubleshooting-oriented errors

Project Scope

Docksmith remains intentionally educational and local-only:

• No Docker/containerd dependency
• No registry pull/push
• No cluster orchestration
• No network stack emulation

CLI

docksmith build [--no-cache] -t <name:tag> <context>
docksmith run [options] <name:tag> [command...]
docksmith images
docksmith rmi <name:tag>
docksmith inspect <name:tag>
docksmith history <name:tag>
docksmith diff <image1:tag> <image2:tag>
docksmith stats
docksmith verify <name:tag>
docksmith export <name:tag> <archive.tar>
docksmith import <archive.tar>
docksmith dashboard

Runtime options

--namespaces          # enable namespace isolation (Linux default)
--no-namespaces       # disable namespace isolation
--rootless            # enable rootless mode (with namespaces)
--no-rootless         # disable rootless mode
--readonly            # remount container rootfs read-only
--seccomp             # enable seccomp filtering (Linux default)
--no-seccomp          # disable seccomp filtering
--overlay             # enable runtime overlay layer (Linux default)
--no-overlay          # disable runtime overlay layer
--hostname <name>     # set container hostname
-e, --env KEY=VALUE   # add or override environment variables (repeatable)

Runtime execution (docksmith run and Dockerfile RUN) requires Linux. Non-Linux hosts return an explicit unsupported-platform error.

Build options

--no-cache            # skip cache lookup and force instruction execution

Docksmithfile CMD format

CMD must be expressed as a JSON string array:

CMD ["/bin/sh", "-c", "echo hello"]

Shell-form CMD echo hello is rejected.

Build and Run

go build -o docksmith .
./docksmith help

Create a local base image first:

./create-base-image.sh
# or on Windows
create-base-image.bat

Build and run an example:

./docksmith build -t myapp:v1 examples
./docksmith run --readonly myapp:v1

Determinism and Reproducibility

Docksmith keeps builds reproducible by:

• Sorting tar entries
• Normalizing tar timestamps to epoch
• Normalizing archive owner metadata
• Using deterministic cache key components
• Computing cryptographic digests from archive content

Cache Diagnostics

On cache miss, Docksmith reports:

• If miss is a cascade from an earlier miss
• If there is no historical cache data for that instruction
• Which cache key component changed:
  • previous layer digest
  • instruction text
  • workdir
  • env digest
  • copied content hash

docksmith stats includes cumulative cache hit/miss and total saved build time.

Dashboard

docksmith dashboard shows:

• image manifests
• layer relationships
• cache hit/miss metrics
• disk usage by store area
• recent runtime logs

Safety Notes

• Layer extraction blocks tar path traversal (../ escapes)
• Whiteouts are handled while applying layers
• Non-Linux platforms do not execute runtime workloads; Linux isolation primitives are required
• Runtime workloads execute in a dedicated network namespace to prevent host-network access
• docksmith rmi removes the manifest and all layer archives associated with that image

Tests

Key tests cover:

• cache determinism and diagnostics
• deterministic layer digests
• layer order affecting image digest
• tar traversal protection
• runtime isolation defaults and namespace flags
• environment override behavior

Run tests with:

go test ./...