mhoennigandClaude Fable 5
e4bfeacf5a
The minimal build-capable CLI decided in RFC 0002's outcome: stdlib-only Go module, one static binary. - engine: RunSpec behind the Engine interface (RFC 0001); the Bwrap engine ports Werkator's hardened invocation — uid-0 mapping, read-only rootfs at /, proc/dev/tmp/root before the user binds so binds below them land inside, mountpoint pre-creation in the rootfs including file mountpoints, and a guard against binds escaping the rootfs. --clearenv gives docker-style clean environments (HOME/PATH set explicitly). - store: images under $WERKDOCK_HOME (default ~/.werkdock), load unpacks via the tar CLI into a tmp dir and renames atomically. - cli: docker-shaped run flags (-v/-e/-w/--rm); refused docker flags (-p, --network, --memory, --cpus, --user, -d) fail loudly with the reason; exit codes follow docker (125 CLI errors, child code through). - doctor: port of werkator-build-prerequisites.sh — userns probe with the three signals, tar/zstd, free space and group-quota headroom via testable df/quota parsers, same PASS/FAIL output. - tests: argv golden test, mountpoint and escape tests, flag refusals, store round trip, doctor parsers — plus real-sandbox integration tests that skip where bwrap or userns are unavailable. Also records in step 21: RFC 0002 levels 2/3 deferred; next goal is sandbox builds of Werkator, Werkbaum, and Werkdock itself. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
35 lines
2.0 KiB
Markdown
35 lines
2.0 KiB
Markdown
# Werkdock
|
|
|
|
A docker-like sandbox CLI over `bwrap` — filesystem isolation only.
|
|
A dock is the enclosed basin in which ships are built: the dock gate controls what passes, the water outside is shared with the whole harbor.
|
|
Accordingly, network, uid, `/proc`, `/dev`, and `/tmp` come from the host by contract; that is what makes Werkdock work without root on a Hostsharing Managed Webspace.
|
|
|
|
Semantics — docker-compatible as far as the filesystem-only contract allows (see [RFC 0002](docs/rfcs/0002-docker-compatible-surface.md)):
|
|
|
|
- An *image* is a rootfs archive; an *instance* is an unpacked, writable directory tree and corresponds to a docker container.
|
|
- `werkdock run [flags] IMAGE [CMD...]` creates an instance and executes in the sandbox with uid 0 mapped to the calling user; verbs and flags follow docker, unsupported docker flags fail loudly.
|
|
- `werkdock doctor` checks the host: user-namespace capability, disk and quota headroom.
|
|
- A daemon speaking the Docker Engine API subset (for Testcontainers) is designed for but deferred.
|
|
|
|
## Build and Test
|
|
|
|
```bash
|
|
go test ./... # all tests; sandbox integration tests skip without bwrap/userns
|
|
go vet ./... && gofmt -l . # quality gates (gofmt must print nothing)
|
|
CGO_ENABLED=0 go build . # one static linux binary, ~3 MB
|
|
```
|
|
|
|
First steps on a host:
|
|
|
|
```bash
|
|
werkdock doctor # can this host run sandboxes?
|
|
werkdock load -i rootfs.tar.zst # import a rootfs archive as an image
|
|
werkdock run --rm -v /repo:/repo -w /repo IMAGE sh -c './gradlew build'
|
|
```
|
|
|
|
Status: bootstrap.
|
|
The implementation language is Go, decided in [RFC 0001](docs/rfcs/0001-implementation-language.md).
|
|
Werkdock grows in this subdirectory of the Werkator repository and moves to its own repository once it stands on its own.
|
|
It must stay self-contained: no imports from Werkator code, no Gradle coupling to the Werkator build.
|
|
The roadmap is session B of [docs/plan/21-werkdock-extraction-and-webspace-install.md](../docs/plan/21-werkdock-extraction-and-webspace-install.md).
|