Gocker 🐳

A minimal, fully-functional Linux container runtime built from scratch in Go — demonstrating deep knowledge of namespaces, cgroups v2, OverlayFS, networking, OCI images, and observability.

MVP 1 → MVP 2 → MVP 3 → MVP 4 → MVP 5 → MVP 6
NS    cgroups  Overlay  Network  CLI+Pull  TUI

---

Why This Exists

Most engineers use Docker daily without understanding what it actually does. This project builds a real container runtime from first principles. Every feature maps directly to a core Linux concept

---

Quick Start

Prerequisites

• Linux kernel ≥ 5.10 (cgroup v2 required)
• Go 1.21+
• Root / sudo access (namespaces and cgroups require it)
• iptables and nsenter installed

# 1. Clone and build
git clone <repo-url> && cd gocker
make build

# 2. Set up the Alpine root filesystem
sudo make rootfs

# 3. Enable IP forwarding for container NAT
sudo make setup-nat

# 4. Run your first container
sudo ./gocker run /bin/sh

# 5. Run an image from Docker Hub
sudo ./gocker pull redis
sudo ./gocker run -it redis /bin/sh

---

Architecture

cmd/
  gocker/
    main.go               ← CLI entrypoint (run, ps, stop, rm, pull, exec, logs, top)
internal/
  container/
    namespace.go          ← clone() flags, pivot_root, hostname, /proc + /dev + /tmp mounts
    cgroup.go             ← cgroup v2 setup / teardown (memory, cpu, pids)
    fs.go                 ← OverlayFS mount / unmount
    network.go            ← veth pairs, bridge, iptables NAT + port mapping
    image.go              ← image ID helpers
  image/
    pull.go               ← Docker Registry v2 API client
    layers.go             ← layer tar extraction with whiteout support
  state/
    store.go              ← JSON container state (/var/lib/gocker/state.json)
  metrics/
    poller.go             ← 500ms cgroup + /proc metric poller
    buffer.go             ← 60-sample circular buffer per metric
  tui/
    app.go                ← bubbletea root model — tabbed dashboard (Containers / Logs / Info)
    styles.go             ← lipgloss dark-navy palette, tab/chip/badge/panel styles
    sparkline.go          ← Unicode block chart renderer (bars + sparklines)
tests/
  mvp1_namespace_test.go  ← PID/hostname/FS/process isolation
  mvp2_cgroup_test.go     ← memory OOM, pids limit, CPU limit, cleanup
  mvp3_overlay_test.go    ← overlay mount, write isolation, /proc
  mvp4_network_test.go    ← bridge, container IP, outbound NAT
  mvp5_e2e_test.go        ← pull, run, ps, logs
  mvp6_tui_test.go        ← circular buffer, history, poller (unit tests)

---

MVPs

MVP 1 — Process Isolation (Namespaces)

Linux concepts: clone(), CLONE_NEWUTS, CLONE_NEWPID, CLONE_NEWNS, CLONE_NEWIPC, CLONE_NEWNET, pivot_root, /proc mount

sudo ./gocker run /bin/sh
# Inside the container:
echo $$          # → 1
hostname         # → <container-id>
ls /             # → alpine rootfs, not host
ps aux           # → only container processes

Implementation notes:

• We re-exec /proc/self/exe child ... to apply namespaces before the user command starts
• exec.LookPath MUST NOT be called before pivot_root — it searches the host PATH
• /dev is a fresh in-memory tmpfs with hand-crafted minimal device nodes — the host /dev is never bind-mounted (avoids SIGWINCH leaks)
• /tmp is mounted as tmpfs with mode=1777 (sticky bit) so privilege-dropping subprocesses (e.g. apt's GPG helper) can use mkstemp() without EACCES
• /run and optionally /var/run also get fresh tmpfs mounts for daemon lock files
• The rootfs path is configurable via GOCKER_ROOTFS env var (default: /var/lib/gocker/rootfs/alpine)

MVP 2 — Resource Limits (cgroups v2)

Linux concepts: cgroup v2 unified hierarchy, memory.max, cpu.max, pids.max, cgroup.procs

sudo ./gocker run --memory 64m --cpus 0.5 --pids-limit 20 /bin/sh

File	Purpose
memory.max	Hard memory cap (bytes)
cpu.max	quota period — e.g. 50000 100000 = 50% of one core
pids.max	Max processes in the container
cgroup.procs	Enroll a PID

Cleanup: TeardownCgroups polls until cgroup.procs is empty before rmdir (kernel returns EBUSY otherwise).

MVP 3 — Filesystem Layers (OverlayFS)

Linux concepts: OverlayFS, copy-on-write, lowerdir, upperdir, workdir, merged

# Directory layout
/var/lib/gocker/
  images/<image-id>/rootfs/    ← lower (read-only base layers)
  containers/<id>/
    upper/                     ← container writes (copy-on-write)
    work/                      ← overlayfs internal
    merged/                    ← final view used as rootfs

Each container gets its own upper/ so writes in container A are invisible to B.

MVP 4 — Container Networking

Linux concepts: Linux bridge, veth pairs, network namespaces, iptables MASQUERADE (NAT), DNAT (port mapping)

sudo make setup-nat            # enable ip_forward
sudo ./gocker run -p 8080:80 /bin/sh
# Inside:
ip addr      # → 10.0.0.x/24
ping 8.8.8.8 # outbound NAT works

Network setup per container:

1. gocker0 bridge created at 10.0.0.1/24
2. veth pair: host end → bridge, container end → container net namespace
3. IP 10.0.0.x assigned inside container
4. Default route → 10.0.0.1
5. iptables -t nat -A POSTROUTING -j MASQUERADE for outbound
6. iptables -t nat -A PREROUTING -j DNAT for port mapping
7. iptables -I FORWARD -i gocker0 -o gocker0 -j ACCEPT for inter-container traffic

MVP 5 — CLI and OCI Image Pull

Linux concepts: Docker Registry v2 API, OCI image format, setns() for exec

# Pull from Docker Hub
sudo ./gocker pull alpine
sudo ./gocker pull redis
sudo ./gocker pull nginx

# Run using pulled image
sudo ./gocker run alpine /bin/sh
sudo ./gocker run -it redis /bin/sh

# Container management
sudo ./gocker ps -a
sudo ./gocker stop <id>
sudo ./gocker rm <id>
sudo ./gocker exec <id> /bin/sh
sudo ./gocker logs <id>

State store: /var/lib/gocker/state.json tracks ID, image, command, status, PID, IP, ports, timestamps.

OCI pull flow: anonymous token → manifest v2 → layer blobs (gzip tar) → SHA256 verify → extract with whiteout support.

MVP 6 — TUI Dashboard (gocker top)

Libraries: bubbletea, lipgloss

sudo ./gocker top

The dashboard uses a professional dark-navy theme built entirely with Lip Gloss:

┌─────────────────────────────────────────────────── 21:03:42 ─┐
│  🐳 gocker top                                               │  ← header + live clock
├──[Containers]──[Logs]──[Info]────────────────────────────────┤  ← tab bar
│  TOTAL 3   ● RUN 2   ● EXIT 1   FILTER: 5m                  │  ← summary chips
├──────────────────────────────────────────────────────────────┤
│  ID         IMAGE          STATUS   CPU         MEM    NET   │  ← table header
│  a1b2c3d4  alpine         ● RUN    ████░ 54%  32 MB  ↑1KB   │
│> b2c3d4e5  nginx:latest   ● RUN    ██░░░ 12%  56 MB  ↑4KB   │  ← selected (blue)
│  c3d4e5f6  redis          ○ STOP   ────        ─      ─     │  ← exited (dim)
├──────────────────────────────────────────────────────────────┤
│ ╭─ INSPECT  nginx:latest  (b2c3d4e5) ──────────────────────╮ │
│ │  Status   ● RUN        CPU    12.3%   CPU history (30s)   │ │
│ │  IP       10.0.0.3     Mem   56.1MB   ▁▂▃▄▅▆▇█░░         │ │
│ │  Uptime   4m32s        TX    4.1 KB   Mem history (30s)   │ │
│ │  PID      1234         RX    1.2 KB   ▇▇▆▅▅▄▃▂▁░         │ │
│ ╰───────────────────────────────────────────────────────────╯ │
├──────────────────────────────────────────────────────────────┤
│  [/] search  [↑↓/jk] navigate  [Tab] switch tab  [q] quit   │  ← footer
└──────────────────────────────────────────────────────────────┘

Keyboard bindings:

Key	Action
↑ / k	Move selection up
↓ / j	Move selection down
Tab	Cycle tabs (Containers → Logs → Info)
Shift+Tab	Cycle tabs backwards
/	Open search overlay
a	Toggle show-all (include exited > 5m)
1 2 3 4	Sort by image / CPU / mem / status
r	Force refresh container list
q / Ctrl+C	Quit

Architecture (3 goroutines):

Poller goroutine ──metrics──▶ CircularBuffer ──render──▶ bubbletea renderer
(500ms ticker)                  (60 samples)              (lipgloss layout)

---

Root Filesystem Strategy

We use the official Alpine Linux minirootfs tarball (~5 MB). Here's why:

Option	Size	Pros	Cons
Alpine minirootfs ✅	~5 MB	Tiny, fully offline after setup, has sh/apk	Must be extracted once
BusyBox static	~1 MB	Smallest possible	No package manager
Ubuntu base	~100 MB	More tools	Very large
Dynamic OCI pull	Varies	Any image	Needs network + MVP 5

make rootfs downloads the Alpine 3.19 x86_64 minirootfs from the official CDN and extracts it to /var/lib/gocker/rootfs/alpine. MVP 5 adds the ability to pull and run any Docker Hub image dynamically.

---

Testing

# Build the binary first
make build

# Set up rootfs
sudo make rootfs

# Unit tests only (safe, no root)
make test-unit

# All integration tests (requires root + rootfs)
sudo make test

# Individual MVPs
sudo go test ./tests/ -run TestMVP1 -v
sudo go test ./tests/ -run TestMVP2 -v
go test ./tests/ -run TestMVP6 -v   # unit tests, no root needed

Test	What it checks	Root?
TestMVP1_PIDIsolation	Container sees PID 1	✓
TestMVP1_HostnameIsolation	Hostname = container ID	✓
TestMVP1_FilesystemIsolation	Alpine rootfs visible inside	✓
TestMVP2_MemoryLimit	OOM kills process over limit	✓
TestMVP2_PidsLimit	Fork fails when limit exceeded	✓
TestMVP2_CPULimit	CPU-limited container exits cleanly	✓
TestMVP2_CgroupCleanup	No orphan cgroup dirs after exit	✓
TestMVP3_OverlayMount	Alpine rootfs visible via overlay	✓
TestMVP3_WriteIsolation	Host rootfs not polluted	✓
TestMVP3_ProcMount	/proc mounted and usable	✓
TestMVP4_BridgeExists	gocker0 bridge present	✓
TestMVP4_ContainerHasIP	Container gets 10.0.0.x	✓
TestMVP5_PullAndRun	Pull alpine, run echo hello	✓
TestMVP6_CircularBuffer	Ring buffer overflow correct	✗
TestMVP6_ContainerHistory	Metrics pushed to all buffers	✗

---

Talking Points

MVP	Question it answers
1 — Namespaces	"How do containers differ from VMs?"
2 — cgroups	"How does Docker enforce memory limits?"
3 — OverlayFS	"How does Docker's image layering work?"
4 — Networking	"How does container networking work?"
5 — CLI + Pull	"Can you ship a usable tool end-to-end?"
6 — TUI Dashboard	"How do you approach observability tooling?"

---

Key Linux Concepts Demonstrated

• clone() with CLONE_NEW* namespace flags
• pivot_root + mount namespace manipulation
• tmpfs mounts for /dev, /tmp (sticky 1777), /run — all ephemeral and isolated
• cgroups v2 unified hierarchy via /sys/fs/cgroup/
• OverlayFS: lowerdir, upperdir, workdir, merged
• Linux bridge devices and veth pairs
• iptables MASQUERADE (NAT) and DNAT (port mapping)
• setns() for joining existing namespaces (exec command)
• Docker Registry v2 API + OCI image format
• /proc/<pid>/stat, /proc/<pid>/io, /proc/<pid>/net/dev for live metrics
• Circular buffer for time-series metric history
• TUI architecture with bubbletea (Elm model/update/view pattern)
• Lip Gloss layout composition (JoinVertical, JoinHorizontal, style chaining)
• Unicode block characters for terminal bar and sparkline charts