mi/werkator
1
0
Fork 0
Code Issues Pull Requests 1 Actions Packages Projects Releases Wiki Activity

Werkdock RFC 0002: docker-compatible surface in three levels

Browse Source 
Level 1: docker-compatible CLI (verbs, flags, loud refusal of isolation
flags the filesystem-only contract cannot honor) — built in session B.
Level 2: OCI image pull, flattened to a rootfs — deferred, stdlib-doable.
Level 3: a daemon speaking the Docker Engine API subset Testcontainers
actually uses (Testcontainers never calls the CLI) — deferred, but the
CLI is built as a thin frontend over the same internal service from the
start. Records the port-mapping crux of host networking and the
unprivileged-netns escape hatch as a future RFC.

Step 21 session B and the werkdock README follow the docker-shaped
semantics: run takes an image, instances correspond to containers.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
mhoennig
2026-09-01 06:44:35 +02:00
co-authored by Claude Fable 5
parent c1ff830a3c
commit 4fba73a1d0
3 changed files with 94 additions and 5 deletions
Download Patch File Download Diff File Expand all files Collapse all files
docs/plan/21-werkdock-extraction-and-webspace-install.md
+2 -1
View File
@@ -55,7 +55,8 @@ The `BuildRunner` half is a keeper regardless of the extraction; it is merged (P
A docker-like CLI over `bwrap`, filesystem isolation only.
- Semantics: an *image* is a rootfs archive; an *instance* is an unpacked, writable directory tree; `werkdock run <instance> -- <command>` executes in the sandbox with uid 0 mapped to the calling user.
- Semantics: 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...]` executes in the sandbox with uid 0 mapped to the calling user.
- The surface is docker-compatible as far as the filesystem-only contract allows — verbs, flags, and (deferred) a Docker-Engine-API daemon for Testcontainers; levels and limits in Werkdock RFC 0002.
- Host-shared by design, not by omission: network, uid mapping, `/proc`, `/dev`, `/tmp` come from the host; document this as the contract, since it is what makes the tool work without root on a Managed Webspace.
- Moves in from Werkator: `tools/build-bwrap-rootfs.sh` (becomes the image build), the generic half of `tools/werkator-build-prerequisites.sh` (becomes `werkdock doctor`: userns capability, quota headroom), and the invocation logic of `BwrapBuildRunner` (mount ordering, mountpoint pre-creation, uid mapping — the parts hardened on the real webspace; the squash commit `71f1fc6` preserves the individual fix messages).
- Known floor: bubblewrap 0.8.0 on the webspaces has no `--overlay`; writable spots are tmpfs/bind mounts until the platform reaches 0.9.