Skip to content

Week 21 - Scaffolding: Project Setup, OCI Bundle Reading

21.1 Conceptual Core

  • The mini-Docker takes an OCI runtime bundle (a directory with config.json and rootfs/), sets up the appropriate kernel features, executes the configured command, and supervises until exit.
  • Scope: the project will not implement all of the OCI runtime spec-focus on the core: namespaces, capabilities, mounts, cgroups v2 (memory + cpu + pids), seccomp.
  • Two language tracks:
  • Go-leverages runc/libcontainer learnings, golang.org/x/sys/unix for syscalls. Closer to runc.
  • Rust-leverages nix crate for syscalls; closer to youki. Stronger memory safety; uses unsafe sparingly.

21.2 Mechanical Detail

  • Project layout (Go example): 
    minidocker/
  cmd/minidocker/main.go         # CLI: create, start, run, kill, delete
  internal/
    bundle/                       # parse config.json
    ns/                           # namespace setup
    mount/                        # rootfs mount, masked paths
    cgroup/                       # cgroup v2 limits
    seccomp/                      # filter compilation
    cap/                          # capability dropping
    runtime/                      # the orchestrator
  examples/
    bundle-alpine/
      config.json
      rootfs/                     # umoci-extracted Alpine
  • Subcommands:
  • `minidocker run - create + start in one step (foreground).
  • minidocker create <id> / start <id> / `delete - split lifecycle.
  • `minidocker state - print state.

21.3 Lab-"Parse and Run"

  1. Implement config.json parsing (the runtime-spec repo has a Go reference type definition).
  2. Implement a no-isolation mode: just chdir(rootfs), chroot(rootfs), execve. Verify it runs.
  3. Add command-line plumbing for the lifecycle subcommands.

21.4 Hardening Drill

  • Validate config.json against the spec's JSON schema. Reject malformed bundles before any syscall.

21.5 Production Readiness Slice

  • Add unit tests with a synthetic bundle. CI runs them on every commit.

Comments