Container Runtime Simulator

A Docker/OCI-inspired container runtime simulator built entirely in pure Python with zero external dependencies. Implements process isolation via namespaces, cgroup resource limits, a layered union filesystem with copy-on-write semantics, image management with Dockerfile parsing, and virtual networking.

Architecture

┌─────────────────────────────────────────────────────┐
│                   Docker-like CLI                    │
│  run · ps · exec · logs · build · images · stats    │
├─────────────────────────────────────────────────────┤
│              Container Runtime Engine                │
│     lifecycle · registry · config · logging          │
├──────────┬──────────┬───────────┬──────────────────┤
│ PID NS   │ Mount NS │  Net NS   │    UTS NS        │
│ isolated │ UnionFS  │  veth     │    hostname      │
│ PID tree │ layers   │  bridge   │    domain        │
├──────────┴──────────┴───────────┴──────────────────┤
│              Control Groups (cgroups)                │
│     memory limits · CPU shares · PID limits         │
├─────────────────────────────────────────────────────┤
│                Image Management                      │
│   layered images · Dockerfile parser · build cache   │
└─────────────────────────────────────────────────────┘

Features

Container Lifecycle

• Full lifecycle management: create, start, stop, pause, unpause, remove
• Container registry with name/ID/prefix lookup
• Auto-generated container names and SHA-256 based IDs
• Environment variable injection and command execution

Namespace Isolation

• PID Namespace — Each container gets an isolated PID tree starting at PID 1
• Mount Namespace — Union filesystem with read-only image layers and a writable top layer
• Network Namespace — Virtual IP assignment (172.17.0.0/16), port mappings, TX/RX byte tracking
• UTS Namespace — Per-container hostname isolation

Control Groups (cgroups)

• Memory — Configurable limits with OOM kill tracking and peak usage stats
• CPU — CPU shares (relative weight) and quota/period throttling
• PIDs — Process count limits per container

Image Management

• Built-in images: alpine (5MB), ubuntu (70MB), python (120MB), node (140MB)
• Realistic filesystem entries (/bin/sh, /etc/os-release, /usr/bin/python3, etc.)
• Dockerfile parser supporting: FROM, RUN, COPY, ADD, ENV, WORKDIR, EXPOSE, CMD, ENTRYPOINT, LABEL, ARG, USER, VOLUME
• Line continuation and comment handling
• Layer caching during builds

Union Filesystem

• Layered storage with copy-on-write semantics
• Whiteout files for deletions
• diff command showing added/modified/deleted files
• Read-only image layers with writable container layer

Docker CLI Comparison

Command	Docker	This Simulator
run	✅	✅ -d, -p, -e, --name, --memory, --cpus
ps	✅	✅ -a flag
stop	✅	✅
rm	✅	✅ -f flag
exec	✅	✅ simulated commands
logs	✅	✅ --tail N
images	✅	✅
pull	✅	✅ built-in registry
rmi	✅	✅
build	✅	✅ Dockerfile instructions
inspect	✅	✅ JSON output
stats	✅	✅ CPU, memory, PIDs
top	✅	✅ PID namespace processes
diff	✅	✅ filesystem changes

Quick Start

# Run the interactive demo
python3 main.py demo

# Pull and run a container
python3 main.py pull alpine
python3 main.py run -d --name web --memory 64m -p 8080:80 alpine

# Execute commands
python3 main.py exec web echo hello
python3 main.py exec web cat /etc/os-release

# View status
python3 main.py ps
python3 main.py stats
python3 main.py logs web
python3 main.py inspect web

# Build a custom image
python3 main.py build -t myapp "FROM python;WORKDIR /app;ENV VERSION=1.0;CMD python3 app.py"

# Cleanup
python3 main.py stop web
python3 main.py rm web

Running Tests

pip install pytest
python3 -m pytest tests/ -v

Project Structure

container-runtime-from-scratch/
├── main.py                    # CLI entry point
├── src/
│   ├── container/
│   │   ├── container.py       # Container lifecycle & state machine
│   │   └── registry.py        # Container registry & lookup
│   ├── namespace/
│   │   ├── pid.py             # PID namespace isolation
│   │   ├── mount.py           # UnionFS with copy-on-write
│   │   ├── net.py             # Network namespace & virtual networking
│   │   └── uts.py             # UTS namespace (hostname)
│   ├── cgroup/
│   │   ├── memory.py          # Memory limits & OOM tracking
│   │   ├── cpu.py             # CPU shares & quota throttling
│   │   └── pids.py            # Process count limits
│   └── image/
│       ├── image.py           # Image model & store with built-ins
│       └── dockerfile.py      # Dockerfile parser
├── tests/
│   └── test_runtime.py        # 25 comprehensive tests
├── requirements.txt
└── README.md

Technical Highlights

• Pure Python — Zero external dependencies (pytest for testing only)
• Union Filesystem — True layered storage with whiteout-based deletions and copy-on-write
• Namespace Isolation — Each container gets independent PID, network, mount, and UTS namespaces
• cgroup Simulation — Memory OOM kills, CPU throttling with quota/period, PID fork limits
• Dockerfile Parser — Handles line continuations, comments, multi-stage validation
• Docker-compatible CLI — Familiar command interface with formatted table output

Author

Mo Shirmohammadi

License

MIT