How nilsirl/dockerc works
Project Type and Purpose
• Project Type: A command-line tool written in Zig.
• Purpose: Fetch a Docker/OCI image (via Skopeo), unpack its filesystem layers, repackage them along with a minimal container runtime (crun + fuse-overlayfs + libfuse), and emit a single standalone binary that runs the container rootlessly.
File Structure
• Top-Level Files & Directories:
• build.zig / build.zig.zon – Zig build scripts
• src/ – Core Zig source files (CLI entrypoint, common utilities, extraction, runtime glue)
• argp-standalone, crun, fuse-overlayfs, libfuse, skopeo, squashfs-tools, squashfuse, umoci, zstd – Git submodules providing:
– Image loading (skopeo, umoci)
– Filesystem extraction and overlay (squashfs-tools, squashfuse, fuse-overlayfs, libfuse)
– Runtime execution (crun)
– Compression (zstd)
• src/tools/policy.json – Configuration for image policy
• .github/workflows/ci.yml – CI pipeline
• Patterns: A linear pipeline of components glued together in Zig, each coming from a Git submodule or from native Zig code.
README for Additional Insights
• Confirms:
• Use of Skopeo for fetching images (supports docker://, docker-daemon:)
• Rootless container execution
• CLI flags (-e, -v) mirror docker run
• Targets x86_64 and arm64 via Zig + MUSL
a. Main Components
1. CLI Frontend (src/main.zig + src/dockerc.zig)
2. Image Loader Module (Skopeo + Umoci)
3. Filesystem Extractor & Compressor (squashfs-tools, squashfuse, zstd)
4. Overlay Setup (fuse-overlayfs + libfuse)
5. Container Runtime (crun)
6. Binary Packager (Zig linker + embedded runtime libraries)
7. Host Environment (OS kernel + user namespaces)
b. Relationships & Data Flow
1. User invokes dockerc --image ... → CLI Frontend parses args
2. CLI calls Image Loader → fetches layers from registry or local daemon
3. Layers passed to Filesystem Extractor → decompress & assemble rootfs
4. Overlay Setup glues rootfs into an ephemeral filesystem mount
5. Container Runtime (crun) is embedded and configured to use user namespaces + FUSE overlay
6. Zig Binary Packager links all code + submodule artifacts into a single executable
7. Final Binary runs directly on Host → sets up rootfs & launches payload
c. Architectural Patterns & Principles
• Pipeline pattern: discrete stages (fetch → extract → package → run)
• Single-binary distribution: embed runtime + fs tools to avoid external deps
• Rootless container execution leveraging Linux namespaces + FUSE
d. Key Technologies & Libraries
• Language & build: Zig, Zig build scripts, Zig’s musl-linked target
• Image handling: Skopeo (Go), Umoci (Go)
• Filesystems: squashfs-tools (C), squashfuse, fuse-overlayfs, libfuse
• Runtime: crun (C)
• Compression: zstd (C)
• OS interfaces: FUSE, user namespaces, Linux kernel
Final Checklist
• Have you separated Build-time vs Runtime components?
• Are all Git submodules represented in their functional group?
• Are all interfaces (FUSE, user namespaces, registry APIs) clearly labeled?