Project 11: Mini Container Runtime (Docker-lite)

A minimal container runtime that uses Linux namespaces and cgroups to isolate processes—like a simplified Docker without the image handling.

Quick Reference

Attribute Value
Primary Language Go
Alternative Languages Rust, C
Difficulty Level 5: Master
Time Estimate 1 month+
Knowledge Area Linux Internals, Containers, Namespaces
Tooling Linux kernel features (namespaces, cgroups)
Prerequisites All previous projects. Linux environment required. Understanding of system calls.

What You Will Build

A minimal container runtime that uses Linux namespaces and cgroups to isolate processes—like a simplified Docker without the image handling.

Why It Matters

This project builds core skills that appear repeatedly in real-world systems and tooling.

Core Challenges

  • Linux namespaces → maps to process isolation, system calls
  • cgroups for resource limits → maps to file system manipulation, kernel interfaces
  • Pivot root and mount namespaces → maps to filesystem isolation
  • Network namespaces → maps to virtual networking

Key Concepts

  • Namespaces: “Linux Kernel Development” or container documentation
  • cgroups: Linux documentation and LWN articles
  • syscalls in Go: “The Linux Programming Interface” by Kerrisk
  • Container theory: “Container Security” by Liz Rice

Real-World Outcome

$ sudo ./minicontainer run --rootfs ./alpine-rootfs --cmd /bin/sh
[minicontainer] Creating new container...
[minicontainer] Setting up namespaces: user, pid, net, uts, mnt
[minicontainer] Setting up cgroups: memory=512M, cpu=50%
[minicontainer] Pivoting root to ./alpine-rootfs
[minicontainer] Container started with PID 1 (inside namespace)

/ # hostname
container-abc123

/ # cat /etc/hostname
container-abc123

/ # ps aux
PID   USER     COMMAND
    1 root     /bin/sh
   10 root     ps aux

/ # echo $$
1    # We ARE PID 1 inside the container!

# From host (another terminal):
$ ps aux | grep alpine
root  54321  0.0  0.0  minicontainer run --rootfs ./alpine-rootfs

$ cat /sys/fs/cgroup/minicontainer-abc123/memory.max
536870912   # 512MB limit

# Network isolation:
/ # ip addr
1: lo: <LOOPBACK,UP>
    inet 127.0.0.1/8
2: eth0: <UP>
    inet 10.0.0.2/24

/ # ping -c 1 10.0.0.1  # Host
PING 10.0.0.1: 64 bytes from 10.0.0.1

Implementation Guide

  1. Reproduce the simplest happy-path scenario.
  2. Build the smallest working version of the core feature.
  3. Add input validation and error handling.
  4. Add instrumentation/logging to confirm behavior.
  5. Refactor into clean modules with tests.

Milestones

  • Milestone 1: Minimal working program that runs end-to-end.
  • Milestone 2: Correct outputs for typical inputs.
  • Milestone 3: Robust handling of edge cases.
  • Milestone 4: Clean structure and documented usage.

Validation Checklist

  • Output matches the real-world outcome example
  • Handles invalid inputs safely
  • Provides clear errors and exit codes
  • Repeatable results across runs

References

  • Main guide: LEARN_GO_DEEP_DIVE.md
  • “Linux Kernel Development” by Robert Love