🐳 Gocker

A simple yet powerful container runtime written in Go, demonstrating Linux namespaces and container isolation.

Gocker is a lightweight container runtime that shows how Docker-like containers work under the hood. It uses Linux namespaces, chroot, and filesystem isolation to run processes in isolated environments.

✨ Features

• 🏗️ Image-based architecture - Pull and manage base images (Alpine Linux)
• 🔒 Process isolation - PID namespace (every container sees itself as PID 1)
• 🏠 Hostname isolation - UTS namespace (custom hostname per container)
• 📁 Filesystem isolation - Mount namespace + chroot
• 🆔 Unique container IDs - Docker-style container identification
• 🚀 Simple CLI - Easy-to-use Docker-inspired commands
• 📦 Portable - All data stored in ~/.gocker (no hardcoded paths)
• 🎯 OverlayFS support - Efficient layered filesystem (automatic detection)
• 🌐 Network isolation - Network namespace for container networking

🏗️ Architecture

~/.gocker/
├── images/
│   └── alpine/
│       └── rootfs/           # Base Alpine Linux filesystem (shared)
├── containers/
│   ├── <container-id-1>/
│   │   └── rootfs/           # Container 1's isolated filesystem
│   ├── <container-id-2>/
│   │   └── ...
│   └── ...
└── metadata/

OverlayFS Mode (Recommended):

• Base image is mounted as read-only lower layer
• Container changes are written to the upper layer
• Fast container creation (no copying needed)
• Space-efficient (changes only stored once)

Fallback Mode:

• Full filesystem copy for each container
• Works on any Linux system
• More disk space usage but simpler

🚀 Quick Start

1. Build

go build -o gocker

2. Initialize

# Download Alpine base image and set up directory structure
./gocker init

This will:

• Create ~/.gocker directory structure
• Download Alpine Linux minirootfs (~3MB)
• Extract it to ~/.gocker/images/alpine/rootfs

3. Run containers

# Run a shell
./gocker run alpine /bin/sh

# Run a command
./gocker run alpine /bin/ls -la /

# Check container hostname
./gocker run alpine /bin/hostname

# View processes (PID isolation)
./gocker run alpine /bin/ps aux

# Check OS version
./gocker run alpine /bin/cat /etc/os-release

📚 Commands

gocker init

Initialize gocker environment by creating directory structure and downloading the Alpine base image.

./gocker init

gocker run [image] [command] [args...]

Run a command in a new container.

./gocker run alpine /bin/sh
./gocker run alpine /bin/ls -la /
./gocker run alpine /bin/ps aux

# Disable OverlayFS (use filesystem copy instead)
./gocker run --no-overlay alpine /bin/sh

# Disable network namespace isolation
./gocker run --no-network alpine /bin/sh

Arguments:

• image - Image name (currently only alpine is supported)
• command - Command to execute inside the container
• args... - Arguments for the command

Flags:

• --no-overlay - Disable OverlayFS and use full filesystem copy
• --no-network - Disable network namespace isolation

🔧 How It Works

1. Initialization (gocker init)

• Creates ~/.gocker directory structure
• Downloads Alpine Linux minirootfs from official CDN
• Extracts it to ~/.gocker/images/alpine/rootfs

2. Container Creation (gocker run)

1. Verify image exists - Check if the base image is available
2. Generate container ID - Create a unique 12-character identifier
3. Setup filesystem:
   • OverlayFS mode (default) - Mount overlay with base image as lower layer
   • Fallback mode - Copy base image to container-specific directory
4. Create namespaces - Fork process with isolated namespaces:
   • PID namespace - Process isolation (container sees itself as PID 1)
   • UTS namespace - Hostname isolation
   • Mount namespace - Filesystem mount isolation
   • User namespace - User/UID mapping (allows unprivileged containers)
   • Network namespace - Network isolation (if enabled)
5. Setup UID/GID mapping - Map container root (UID 0) to host user
6. Setup environment:
   • chroot into container filesystem
   • Mount /proc filesystem
   • Set custom hostname
7. Execute command - Run the requested command
8. Cleanup - Unmount /proc and exit

3. Linux Namespaces Used

Namespace	Purpose	Example
PID	Process ID isolation	Container sees only its own processes (PID 1)
UTS	Hostname isolation	Container has its own hostname (gocker-container)
Mount	Filesystem mount isolation	Container has its own mount table
User	User/UID isolation	Maps container root (UID 0) to host user (unprivileged)
Network	Network isolation	Container has its own network stack (optional)

🔍 Technical Details

Directory Structure

// Paths in ~/.gocker/
type Paths struct {
    Root       string  // ~/.gocker
    Images     string  // ~/.gocker/images
    Containers string  // ~/.gocker/containers
    Metadata   string  // ~/.gocker/metadata
}

Container Lifecycle

User runs: gocker run alpine /bin/sh
    ↓
1. Check if gocker initialized
    ↓
2. Verify alpine image exists
    ↓
3. Generate container ID (e.g., a8317726)
    ↓
4. Copy image rootfs → container rootfs
   (~/.gocker/images/alpine/rootfs → ~/.gocker/containers/a8317726/rootfs)
    ↓
5. Create parent process with namespaces (PID, UTS, Mount, User)
    ↓
6. Setup UID/GID mapping (container UID 0 → host UID)
    ↓
7. Fork child process (PID 1 in new namespace)
    ↓
8. Child: chroot + mount /proc + set hostname + exec /bin/sh
    ↓
9. User interacts with container
    ↓
10. Exit → cleanup /proc → done

System Calls Used

• syscall.Sethostname() - Set container hostname
• syscall.Chroot() - Change root directory
• syscall.Chdir() - Change working directory
• syscall.Mount() - Mount /proc filesystem
• syscall.Unmount() - Unmount /proc on exit
• syscall.CLONE_NEWUSER - Create new user namespace (enables unprivileged containers)
• syscall.CLONE_NEWPID - Create new PID namespace
• syscall.CLONE_NEWUTS - Create new UTS namespace
• syscall.CLONE_NEWNS - Create new mount namespace

📁 Project Structure

gocker/
├── cmd/
│   ├── root.go          # Root cobra command
│   ├── init.go          # Initialize gocker
│   ├── run.go           # Run containers
│   └── child.go         # Internal child process handler
├── internal/
│   ├── paths/
│   │   └── paths.go     # Path management
│   ├── image/
│   │   └── image.go     # Image download & management
│   ├── containerops/
│   │   └── container.go # Container creation & execution
│   └── container/
│       └── container.go # Legacy container operations
├── main.go              # Entry point
├── go.mod               # Dependencies
└── README.md            # This file

🎯 Design Decisions

Why copy-on-create instead of OverlayFS?

For educational purposes and simplicity:

• ✅ Easy to understand - Direct filesystem copy is conceptually simple
• ✅ No kernel dependencies - Works on any Linux system
• ✅ Complete isolation - Each container has its own filesystem
• ⚠️ Trade-off - Uses more disk space and slower to create

Future improvement: Implement OverlayFS for Docker-like layered filesystem.

Why ~/.gocker directory?

• ✅ Portable - No hardcoded paths
• ✅ User-specific - Each user has their own containers
• ✅ No root filesystem pollution - Clean separation
• ✅ Easy cleanup - Just remove ~/.gocker

🧪 Examples

Example 1: Interactive Shell

$ ./gocker run alpine /bin/sh
Container bf116791 created successfully
🐳 Container ID: bf116791
Running command in container: [/bin/sh]
Starting container (PID: 1)
/ # hostname
gocker-container
/ # ps aux
PID   USER     TIME  COMMAND
    1 root      0:00 /proc/self/exe child --rootfs ...
    8 root      0:00 /bin/sh
   14 root      0:00 ps aux
/ # exit
✅ Container bf116791 finished

Example 2: List Files

$ ./gocker run alpine /bin/ls -la /
Container d8ac5809 created successfully
🐳 Container ID: d8ac5809
Running command in container: [/bin/ls -la /]
Starting container (PID: 1)
total 72
drwxr-xr-x   19 1000     1000          4096 Jan  2 15:22 .
drwxr-xr-x   19 1000     1000          4096 Jan  2 15:22 ..
drwxr-xr-x    2 1000     1000          4096 Jan  2 15:22 bin
drwxr-xr-x    2 1000     1000          4096 Jan  2 15:22 dev
...
✅ Container d8ac5809 finished

Example 3: Check OS Version

$ ./gocker run alpine /bin/cat /etc/os-release
Container 94e0358a created successfully
🐳 Container ID: 94e0358a
Running command in container: [/bin/cat /etc/os-release]
Starting container (PID: 1)
NAME="Alpine Linux"
ID=alpine
VERSION_ID=3.19.0
PRETTY_NAME="Alpine Linux v3.19"
✅ Container 94e0358a finished

🛠️ Requirements

• OS: Linux (kernel 3.8+)
• Go: 1.21 or higher

🚧 Limitations

• Only Alpine Linux is supported as base image
• No network namespace isolation (yet)
• No cgroups resource limiting (yet)
• No container persistence/restart
• No overlay filesystem (uses full copy)

🔮 Future Improvements

• OverlayFS support for efficient storage
• Network namespace isolation
• Cgroups for resource limiting (CPU, memory)
• Container lifecycle management (start/stop/rm)
• Support for custom images
• Volume mounting
• Environment variable passing

📖 Learning Resources

This project demonstrates:

• Linux namespaces (PID, UTS, Mount, User, Network)
• User/UID mapping for unprivileged containers
• Process isolation techniques
• chroot jails
• OverlayFS and layered filesystems
• Network namespace isolation
• Copy-on-Write filesystems
• Filesystem management
• Go system programming
• CLI design with Cobra and flags

🤝 Contributing

This is an educational project. Feel free to:

• Add new features
• Improve documentation
• Fix bugs
• Add tests

📝 License

MIT License - See LICENSE file for details

🙏 Acknowledgments

• Inspired by Docker and container runtimes
• Uses Alpine Linux minirootfs
• Built with Cobra CLI framework

---

Made with ❤️ for learning how containers work