# fewbytes/rubber-docker architecture

> Architecture diagram of the GitHub repository fewbytes/rubber-docker, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-27). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/fewbytes/rubber-docker
- Repository: https://github.com/fewbytes/rubber-docker

## Overview

Rubber Docker is a hands-on workshop for building a Linux container runtime one feature at a time. Learners start with process creation and command execution, then add image-root setup, filesystem and namespace isolation, resource controls, and non-root execution. The level scripts are successive teaching stages rather than modules in one assembled application. The README also identifies the `linux.c` syscall bindings, preparation material, and workshop slides. Runtime wiring below reflects the sampled scripts; later capabilities are represented as documented lessons.

Main entry points: [`levels/10_setuid/rd.py`](https://github.com/fewbytes/rubber-docker/blob/master/levels/10_setuid/rd.py) (Containment setup), [`levels/00_fork_exec/rd.py`](https://github.com/fewbytes/rubber-docker/blob/master/levels/00_fork_exec/rd.py) (Fork and exec), [`levels/01_chroot_image/rd.py`](https://github.com/fewbytes/rubber-docker/blob/master/levels/01_chroot_image/rd.py) (Image and chroot), [`levels/02_mount_ns/rd.py`](https://github.com/fewbytes/rubber-docker/blob/master/levels/02_mount_ns/rd.py) (Mount namespace)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_curriculum["Container lessons"]
  node_lesson00["Fork and exec<br/>[rd.py]"]
  node_lesson01["Image and chroot<br/>[rd.py]"]
  node_lesson02["Mount namespace<br/>[rd.py]"]
  node_lesson03["Pivot root<br/>[rd.py]"]
  node_lesson04["Overlay filesystem<br/>[rd.py]"]
  node_lesson05["UTS namespace<br/>[rd.py]"]
  node_lesson06["PID namespace<br/>[rd.py]"]
  node_lesson07["Network namespace<br/>[rd.py]"]
  node_lesson08["CPU cgroup<br/>[rd.py]"]
  node_lesson09["Memory cgroup<br/>[rd.py]"]
  node_lesson10["Non-root user<br/>[rd.py]"]
end

subgraph group_runtime["Runtime implementation"]
  node_runner["Container runner<br/>[rd.py]"]
  node_rootfs["Image root setup<br/>[rd.py]"]
  node_contain["Containment setup<br/>[rd.py]"]
  node_exec["Container command<br/>[rd.py]"]
end

subgraph group_syscalls["Linux syscall layer"]
  node_bindings["Syscall bindings<br/>[linux.c]"]
end

subgraph group_materials["Workshop materials"]
  node_prep["Preparation guides<br/>[prep.md]"]
  node_slides["Workshop slides<br/>[workshop.html]"]
end

node_learner(("Workshop learner"))
node_image["Image tarballs"]
node_host(("Linux host"))

node_learner -->|"starts lessons"| node_lesson00
node_lesson00 -->|"next lesson"| node_lesson01
node_lesson01 -->|"next lesson"| node_lesson02
node_lesson02 -->|"next lesson"| node_lesson03
node_lesson03 -->|"next lesson"| node_lesson04
node_lesson04 -->|"next lesson"| node_lesson05
node_lesson05 -->|"next lesson"| node_lesson06
node_lesson06 -->|"next lesson"| node_lesson07
node_lesson07 -->|"next lesson"| node_lesson08
node_lesson08 -->|"next lesson"| node_lesson09
node_lesson09 -->|"next lesson"| node_lesson10
node_learner -->|"runs command"| node_runner
node_runner -->|"prepares image"| node_rootfs
node_image -->|"extracts image"| node_rootfs
node_runner -->|"clones child"| node_contain
node_contain -->|"mounts root"| node_rootfs
node_contain -->|"calls syscalls"| node_bindings
node_contain -->|"executes command"| node_exec
node_bindings -->|"invokes kernel"| node_host
node_learner -->|"reads preparation"| node_prep
node_learner -->|"follows slides"| node_slides

click node_lesson00 "https://github.com/fewbytes/rubber-docker/blob/master/levels/00_fork_exec/rd.py"
click node_lesson01 "https://github.com/fewbytes/rubber-docker/blob/master/levels/01_chroot_image/rd.py"
click node_lesson02 "https://github.com/fewbytes/rubber-docker/blob/master/levels/02_mount_ns/rd.py"
click node_lesson03 "https://github.com/fewbytes/rubber-docker/blob/master/levels/03_pivot_root/rd.py"
click node_lesson04 "https://github.com/fewbytes/rubber-docker/blob/master/levels/04_overlay/rd.py"
click node_lesson05 "https://github.com/fewbytes/rubber-docker/blob/master/levels/05_uts_namespace/rd.py"
click node_lesson06 "https://github.com/fewbytes/rubber-docker/blob/master/levels/06_pid_namespace/rd.py"
click node_lesson07 "https://github.com/fewbytes/rubber-docker/blob/master/levels/07_net_namespace/rd.py"
click node_lesson08 "https://github.com/fewbytes/rubber-docker/blob/master/levels/08_cpu_cgroup/rd.py"
click node_lesson09 "https://github.com/fewbytes/rubber-docker/blob/master/levels/09_memory_cgorup/rd.py"
click node_lesson10 "https://github.com/fewbytes/rubber-docker/blob/master/levels/10_setuid/rd.py"
click node_runner "https://github.com/fewbytes/rubber-docker/blob/master/levels/10_setuid/rd.py"
click node_rootfs "https://github.com/fewbytes/rubber-docker/blob/master/levels/10_setuid/rd.py"
click node_contain "https://github.com/fewbytes/rubber-docker/blob/master/levels/10_setuid/rd.py"
click node_exec "https://github.com/fewbytes/rubber-docker/blob/master/levels/10_setuid/rd.py"
click node_bindings "https://github.com/fewbytes/rubber-docker/blob/master/linux.c"
click node_prep "https://github.com/fewbytes/rubber-docker/blob/master/docs/prep.md"
click node_slides "https://github.com/fewbytes/rubber-docker/blob/master/slides/workshop.html"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_lesson00,node_lesson01,node_lesson02,node_lesson03,node_lesson04,node_lesson05,node_lesson06,node_lesson07,node_lesson08,node_lesson09,node_lesson10 toneBlue
class node_runner,node_rootfs,node_contain,node_exec toneAmber
class node_bindings toneMint
class node_prep,node_slides toneRose
class node_learner,node_image,node_host toneIndigo
```

## Components

### Container lessons

- [Fork and exec](https://github.com/fewbytes/rubber-docker/blob/master/levels/00_fork_exec/rd.py): `levels/00_fork_exec/rd.py`
- [Image and chroot](https://github.com/fewbytes/rubber-docker/blob/master/levels/01_chroot_image/rd.py): `levels/01_chroot_image/rd.py`
- [Mount namespace](https://github.com/fewbytes/rubber-docker/blob/master/levels/02_mount_ns/rd.py): `levels/02_mount_ns/rd.py`
- [Pivot root](https://github.com/fewbytes/rubber-docker/blob/master/levels/03_pivot_root/rd.py): `levels/03_pivot_root/rd.py`
- [Overlay filesystem](https://github.com/fewbytes/rubber-docker/blob/master/levels/04_overlay/rd.py): `levels/04_overlay/rd.py`
- [UTS namespace](https://github.com/fewbytes/rubber-docker/blob/master/levels/05_uts_namespace/rd.py): `levels/05_uts_namespace/rd.py`
- [PID namespace](https://github.com/fewbytes/rubber-docker/blob/master/levels/06_pid_namespace/rd.py): `levels/06_pid_namespace/rd.py`
- [Network namespace](https://github.com/fewbytes/rubber-docker/blob/master/levels/07_net_namespace/rd.py): `levels/07_net_namespace/rd.py`
- [CPU cgroup](https://github.com/fewbytes/rubber-docker/blob/master/levels/08_cpu_cgroup/rd.py): `levels/08_cpu_cgroup/rd.py`
- [Memory cgroup](https://github.com/fewbytes/rubber-docker/blob/master/levels/09_memory_cgorup/rd.py): `levels/09_memory_cgorup/rd.py`
- [Non-root user](https://github.com/fewbytes/rubber-docker/blob/master/levels/10_setuid/rd.py): `levels/10_setuid/rd.py`

### Runtime implementation

- [Container runner](https://github.com/fewbytes/rubber-docker/blob/master/levels/10_setuid/rd.py): `levels/10_setuid/rd.py`
- [Image root setup](https://github.com/fewbytes/rubber-docker/blob/master/levels/10_setuid/rd.py): `levels/10_setuid/rd.py`
- [Containment setup](https://github.com/fewbytes/rubber-docker/blob/master/levels/10_setuid/rd.py): `levels/10_setuid/rd.py`
- [Container command](https://github.com/fewbytes/rubber-docker/blob/master/levels/10_setuid/rd.py): `levels/10_setuid/rd.py`

### Linux syscall layer

- [Syscall bindings](https://github.com/fewbytes/rubber-docker/blob/master/linux.c): `linux.c`

### Workshop materials

- [Preparation guides](https://github.com/fewbytes/rubber-docker/blob/master/docs/prep.md): `docs/prep.md`
- [Workshop slides](https://github.com/fewbytes/rubber-docker/blob/master/slides/workshop.html): `slides/workshop.html`

### Other components

- **Workshop learner**
- **Image tarballs**
- **Linux host**

## Connections

- Workshop learner → Fork and exec: starts lessons
- Fork and exec → Image and chroot: next lesson
- Image and chroot → Mount namespace: next lesson
- Mount namespace → Pivot root: next lesson
- Pivot root → Overlay filesystem: next lesson
- Overlay filesystem → UTS namespace: next lesson
- UTS namespace → PID namespace: next lesson
- PID namespace → Network namespace: next lesson
- Network namespace → CPU cgroup: next lesson
- CPU cgroup → Memory cgroup: next lesson
- Memory cgroup → Non-root user: next lesson
- Workshop learner → Container runner: runs command
- Container runner → Image root setup: prepares image
- Image tarballs → Image root setup: extracts image
- Container runner → Containment setup: clones child
- Containment setup → Image root setup: mounts root
- Containment setup → Syscall bindings: calls syscalls
- Containment setup → Container command: executes command
- Syscall bindings → Linux host: invokes kernel
- Workshop learner → Preparation guides: reads preparation
- Workshop learner → Workshop slides: follows slides