Docksmith Engine

A simplified Docker-like image build + container runtime system implemented in Go.

Docksmith parses a Docksmithfile, builds layered images with a deterministic cache, and runs containers using chroot-based isolation.

🏗️ Architecture

CLI → Parser → Builder → (Cache + Layer + Image)
                           ↓
                        Runtime

⚠️ Requirements (Read This)

• Linux or WSL2 is required (the runtime uses Linux chroot(2)). macOS/Windows are not supported for build/run.
• Offline only: no downloads during build or run (don’t use apt-get, curl, etc. in RUN).
• Only COPY and RUN create layers. Other instructions only update build state.
• Cache reporting is printed only for COPY and RUN steps: Step i/n : ... [CACHE HIT|MISS] X.XXs.

✅ Prerequisites

• Go 1.22+
• Linux machine or WSL2 (Ubuntu recommended)
• sudo access (needed for chroot)

🎬 Demo Script (Copy/Paste)

This repo includes a required offline sample app in sample-app/ that uses all six instructions: FROM, WORKDIR, COPY, ENV, RUN, CMD.

Rule: use the same user for build + run

Use sudo for both build and run so everything is stored under the same ~/.docksmith/ location (for root).

0) One-time base image import (offline FROM base:latest)

sudo go run ./cmd base base:latest

1) Cold build (expect cache MISS)

sudo go run ./cmd build -t sample:latest ./sample-app

Expected behavior:

• COPY → [CACHE MISS]
• RUN → [CACHE MISS]

2) Warm build (expect cache HIT)

sudo go run ./cmd build -t sample:latest ./sample-app

Expected behavior:

• COPY → [CACHE HIT]
• RUN → [CACHE HIT]

3) Cache invalidation + cascade (COPY MISS → RUN MISS)

Create/change a temporary file in the build context, then rebuild:

date > sample-app/.demo-change.txt
sudo go run ./cmd build -t sample:latest ./sample-app

(Optional cleanup)

rm -f sample-app/.demo-change.txt

Expected behavior:

• COPY → [CACHE MISS]
• RUN → [CACHE MISS] (cascade)

4) Run (visible output)

sudo go run ./cmd run sample:latest

5) ENV override demo

sudo go run ./cmd run -e MESSAGE="Hi Professor" sample:latest

6) Isolation proof (container write must NOT appear on host)

Run a command that writes /test.txt inside the container rootfs:

sudo go run ./cmd run sample:latest sh -c 'echo hacked > /test.txt'

Now check the host filesystem:

ls /test.txt

Expected:

ls: cannot access '/test.txt': No such file or directory

7) List images + remove image

go run ./cmd images
go run ./cmd rmi sample:latest

(Optional) Force rebuild (skip cache)

sudo go run ./cmd build -t sample:latest --no-cache ./sample-app

🚀 General Usage (Linux / WSL2)

Build

sudo go run ./cmd build -t test:latest .

Run

sudo go run ./cmd run test:latest

Run with ENV override

sudo go run ./cmd run -e KEY=value test:latest

List / Remove

go run ./cmd images
go run ./cmd rmi test:latest

🧪 Tests

go test ./... -v