DevContainer with Sidecar Builders

A modern DevContainer setup using Podman with sidecar containers for building (Rust, Geant4, etc.) without bloating your dev environment.

Quick Start

1. Bootstrap Installation

# Clone the repository
git clone <repo-url>
cd devc-sidecar-tests

# Run the install script (installs just and checks dependencies)
./install.sh

2. Configure Personal Settings

# Edit your personal Git config
nano .devcontainer/.config/git/host
# Set: user.name and user.email

3. Build and Start

# Build containers
just containers-build

# Start development environment
just start

4. Open in VS Code

code .
# Then: Command Palette → "Dev Containers: Reopen in Container"

What You Get

• 🐍 Python 3.11 development environment (slim)
• 🦀 Rust builder sidecar (build without installing Rust locally)
• 🔬 Geant4 sidecar example (heavy simulation tools isolated)
• 🔐 SSH commit signing (via agent forwarding, no keys in container)
• 🐙 GitHub CLI (gh) pre-configured
• ⚡ Modern CLI tools (ripgrep, fd, bat, eza, yq, jq)
• 🚀 uv for blazing fast Python package management
• 📋 just as single entry point for all commands

Architecture

Main Container (slim)    Builder Sidecars (isolated)
┌─────────────────┐      ┌──────────────┬──────────────┐
│                 │      │              │              │
│  Python Dev     │◄────►│ Rust Builder │ Geant4       │
│  + Tools        │ sock │ ~2GB         │ Builder      │
│  + Editor       │ exec │              │ ~3GB         │
│  ~500MB         │      │              │              │
│                 │      │              │              │
└─────────────────┘      └──────────────┴──────────────┘
        │                         │
        └─────────────────────────┘
          Shared volumes + network

Communication: Docker-out-of-Docker (DooD) pattern - industry standard used by GitLab CI, GitHub Actions, Jenkins

Key Benefits:

• ✅ Dev container stays slim (~500MB vs ~5GB+)
• ✅ Build tools isolated in sidecars
• ✅ No private keys in containers (SSH agent forwarding)
• ✅ Fast rebuilds with caching
• ✅ Multi-architecture support (Intel + Apple Silicon)
• ✅ Standard Docker socket communication (industry best practice)

Common Commands

New! The justfile is now modular for better organization. Run just init for interactive setup.

All commands use just as the entry point:

# Setup & Help
just init               # Interactive workspace setup
just init-quick         # Quick init with defaults (non-interactive)
just init-list          # List all modules and their status
just                    # List all commands
just help-modules       # Explain modular justfile system
just show-config        # Show current configuration

# Workspace
just init-workspace     # Check dependencies & config
just check-deps         # Verify all tools installed

# Setup (one-time)
just setup              # Setup Git, GitHub CLI, signing
just setup-git-config   # Load Git configs
just setup-gh-config    # Load GitHub CLI config
just setup-signing      # Configure SSH commit signing

# Containers
just containers-build   # Build with cache (fast)
just containers-build-clean  # Clean build
just start              # Start all containers
just stop               # Stop all containers
just restart            # Rebuild and restart
just ps                 # Show running containers

# Development
just install            # Install Python dependencies
just py-add requests    # Add Python package
just rust-build         # Build Rust project
just test               # Run tests

# CI Simulation (test prod builds locally!)
just build-prod         # Build production image
just test-prod          # Test production image
just ci-simulate        # Quick CI simulation
just ci-full            # Full CI pipeline simulation
just scan-prod          # Security vulnerability scan
just compare-images     # Compare dev vs prod sizes

# Performance Testing
just bench              # Run benchmarks (measure speed)

# Documentation
just docs               # Build and serve documentation
just docs-build         # Build documentation
just docs-serve         # Serve docs locally on port 8000
just docs-list          # List all markdown files
just docs-spell         # Spell check documentation

# Git & GitHub
just status             # git status
just ac "message"       # Add, commit, push
just gh-pr              # Create pull request
just gh-status          # Check GitHub auth

# Utilities
just versions           # Show tool versions
just logs app           # View container logs
just shell app          # Shell into container
just prune              # Clean up unused images

Project Structure

.
├── install.sh                    # Bootstrap script
├── justfile                      # Command definitions
├── main.py                       # Your Python code
├── pyproject.toml               # Python project config
│
├── .devcontainer/
│   ├── Dockerfile               # Main container definition
│   ├── docker-compose.yml       # Multi-container setup
│   ├── devcontainer.json        # VS Code config
│   │
│   ├── .config/
│   │   ├── git/
│   │   │   ├── config           # Team Git config (committed)
│   │   │   ├── host.example     # Template (committed)
│   │   │   └── host             # Personal config (gitignored)
│   │   └── gh/
│   │       ├── config.yml       # Team GitHub CLI config (committed)
│   │       └── hosts.example.yml # Reference (committed)
│   │
│   ├── geant4-example/          # Example Geant4 sidecar setup
│   │
│   └── docs/
│       ├── ARCHITECTURE.md      # Architecture overview
│       ├── CONTAINERS.md        # Container build guide
│       ├── MULTIARCH.md         # Multi-arch support
│       ├── SECURITY.md          # Security model
│       ├── SIGNING.md           # Commit signing guide
│       ├── PODMAN.md            # Podman usage
│       ├── GIT.md               # Git commands
│       ├── GH.md                # GitHub CLI
│       ├── UV.md                # uv package manager
│       ├── TOOLS.md             # CLI tools reference
│       ├── JUSTFILE_MODULES.md  # Modular justfile system
│       └── BENCHMARKING_GUIDE.md # Performance testing guide
│
└── .gitignore                   # Git ignore rules

Requirements

• Podman 3.0+ (with compose support)
• Git 2.0+
• just (installed by install.sh)
• SSH (for git authentication)
• VS Code (optional, for devcontainer)

All checked by just check-deps.

Configuration

Team Settings (Committed)

Git (.devcontainer/.config/git/config):

• Commit signing required
• SSH format
• Default branch: main
• Useful aliases

GitHub CLI (.devcontainer/.config/gh/config.yml):

• Git protocol: SSH
• Useful aliases (co, pv, pl, etc.)

Personal Settings (Gitignored)

Git (.devcontainer/.config/git/host):

• Your name and email
• Signing key (optional)
• Personal preferences

Created from template on first run.

Security

Zero-Trust Key Management

• 🔒 Private keys NEVER enter containers
• 🔐 SSH agent forwarding from host (via VS Code)
• 🔓 Only public keys visible in containers
• ✅ Container compromise = no key theft

Authentication

1. Git operations: SSH agent (forwarded from host)
2. Commit signing: SSH signing (via agent)
3. GitHub API: gh auth login (token in ~/.config/gh/)

See .devcontainer/SECURITY.md for complete security model.

Multi-Architecture Support

Works natively on:

• ✅ x86_64 (Intel/AMD)
• ✅ ARM64 (Apple Silicon M1/M2/M3/M4, AWS Graviton)

Auto-detects architecture and downloads correct binaries.

Sidecar Pattern

Why Sidecars?

Instead of:

❌ One huge container with everything
   - Python + Rust + Geant4 + tools
   - 5GB+, slow to build, bloated

We use:

✅ Slim dev container + builder sidecars
   - Dev: 500MB (fast, focused)
   - Builders: Isolated, cacheable
   - Total: Same size but organized

Using Sidecars

Rust example:

# Build in sidecar (transparent)
just rust-build

# Or directly
just cargo build --release

# The cargo wrapper uses the sidecar automatically

Geant4 example:

# Build simulation in sidecar
just g4-build

# Run in runtime sidecar
just g4-run ./build/simulation

See .devcontainer/geant4-example/ for complete Geant4 setup.

Troubleshooting

Podman compose not found

# Check Podman version (needs 3.0+)
podman version

# Test compose
podman compose version

SSH agent not available

# On host, add your key
ssh-add ~/.ssh/id_ed25519

# Verify
ssh-add -l

# Restart VS Code/container

Containers won't start

# Check logs
just logs app

# Check Podman
podman ps -a

# Clean rebuild
just stop
just containers-build-clean
just start

Build fails on ARM

# Should auto-detect, but verify
uname -m  # Should show arm64 or aarch64

# Clean build
just containers-build-clean

Documentation

Comprehensive docs in .devcontainer/:

• DEV_TO_PROD_WORKFLOW.md ⭐ - Complete dev → staging → prod guide
• JUSTFILE_MODULES.md ⭐ - Modular justfile system explained
• ARCHITECTURE.md - How everything fits together
• SIDECAR_COMMUNICATION.md - How sidecars communicate (DooD pattern)
• CONTAINERS.md - Container build optimization
• MULTIARCH.md - Multi-architecture support
• SECURITY.md - Security model and best practices
• SIGNING.md - SSH commit signing setup
• PODMAN.md - Podman usage and tips
• GIT.md - Git commands and workflows
• GH.md - GitHub CLI usage
• UV.md - uv package manager guide
• TOOLS.md - Modern CLI tools reference
• TROUBLESHOOTING_SIDECARS.md - Sidecar connectivity issues

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make changes
4. Commit with signing: git commit -s -m "Add feature"
5. Push: git push origin feature-name
6. Create PR: just gh-pr

License

[Your License Here]

Credits

Built with:

• Podman - Container engine
• just - Command runner
• uv - Python package manager
• GitHub CLI - GitHub automation
• Modern CLI tools (ripgrep, fd, bat, eza, yq)

Support

• 📖 Documentation: .devcontainer/ directory
• 🐛 Issues: [GitHub Issues]
• 💬 Discussions: [GitHub Discussions]