Arch DevOps Development Container

A production-ready DevOps development container based on Arch Linux with a full Wayland desktop environment accessible via VNC. Pre-configured with infrastructure tools, Docker-from-Docker support, AWS CLI, DevContainer CLI, and Claude Code.

Features

• Full Wayland Desktop: Sway compositor with waybar status bar and wofi application launcher
• VNC Access: KRDC-compatible VNC server on port 5900 (no password)
• Docker-from-Docker: Mount host Docker socket for seamless container operations
• Pre-installed Tools:
  • Cloud: AWS CLI, Scaleway CLI
  • IaC: OpenTofu (Terraform)
  • Kubernetes: kubectl, Helm
  • Containers: Docker, docker-compose, docker-buildx
  • DevContainer: DevContainer CLI (@devcontainers/cli)
  • AI Development: Claude CLI (@anthropic-ai/claude-code)
  • Development: Node.js, npm, neovim, git, GitHub CLI
  • Task Runners: pixi, just
  • Browser: Google Chrome
• Service Management: s6-overlay for reliable process supervision
• Auto GID Sync: Automatic Docker socket permission synchronization
• VS Code Ready: Full DevContainer support with recommended extensions

Quick Start

Using Pre-built Image (Recommended)

Pull and run the pre-built image from GitHub Container Registry:

# Pull the latest image
docker pull ghcr.io/atrawog/arch-devops:latest

# Run the container
docker run -d \
    --name arch-devops \
    --hostname=arch-devops \
    --privileged \
    --cap-add=SYS_PTRACE \
    --security-opt seccomp=unconfined \
    --shm-size=2g \
    -v $(pwd):/workspace:cached \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -p 5900:5900 \
    ghcr.io/atrawog/arch-devops:latest

# Access via VNC
# Connect to localhost:5900 with any VNC client (KRDC, TigerVNC, etc.)

Using Pixi (Task Runner)

This project uses Pixi for streamlined task management:

# Install pixi (if not already installed)
curl -fsSL https://pixi.sh/install.sh | bash

# Pull pre-built image and run
pixi run ghcr-pull
pixi run up

# Or build locally and run
pixi run dev

# View all available tasks
pixi task list

Using DevContainer CLI

For DevContainer workflows:

# Start DevContainer (pulls pre-built image)
pixi run dc-up

# Open shell in DevContainer
pixi run dc-shell

# Verify Docker access
pixi run dc-verify-docker

Using VS Code

1. Install the "Dev Containers" extension
2. Open this folder in VS Code
3. Press F1 → "Dev Containers: Reopen in Container"
4. VS Code will pull the pre-built image or fall back to building
5. Connect to VNC at localhost:5900 to access the desktop

Using the Template

The template/ directory provides a self-contained, portable configuration for using the pre-built image in your own projects. This is the recommended way to use arch-devops as a development environment.

What's Included

The template contains:

• .devcontainer/devcontainer.json - Simplified DevContainer config (no build)
• pixi.toml - Minimal task configuration with dc-* commands only
• scripts/ - Real copies of dc-down.sh and load-env.sh (no symlinks)
• .env.example - Environment variable template
• .gitignore - Standard ignore patterns
• README.md - Comprehensive usage guide

Quick Setup

# 1. Copy template to your project
cp -r /path/to/arch-devops/template/* /path/to/your/project/

# 2. Configure environment
cd /path/to/your/project
cp .env.example .env
nano .env  # Add your credentials

# 3. Start using the container
pixi run dc-up              # Start DevContainer
pixi run dc-verify-docker   # Verify Docker access
pixi run dc-shell           # Open shell

Or with VS Code:

1. Copy template files to your project
2. Open project in VS Code
3. F1 → "Dev Containers: Reopen in Container"
4. Connect to VNC at localhost:5900

Key Features

• Fully Portable: Copy anywhere, no dependencies on parent repo
• No Symlinks: All files are real copies
• Pre-built Image: Uses ghcr.io/atrawog/arch-devops:latest
• Self-Contained: Works immediately after copying
• Your Workspace: Your project directory becomes /workspace in container

See template/README.md for complete documentation.

GitHub Container Registry

The image is published to GitHub Container Registry at:

• Latest: ghcr.io/atrawog/arch-devops:latest
• Version: ghcr.io/atrawog/arch-devops:v1.0.0

Publishing to GHCR

If you want to publish your own version:

# 1. Create GitHub Personal Access Token with write:packages scope
#    https://github.com/settings/tokens/new

# 2. Authenticate
export GITHUB_TOKEN=your_token_here
pixi run ghcr-login

# 3. Build and publish
pixi run ghcr-publish

See REGISTRY.md for complete publishing documentation.

Building from Source

If you prefer to build locally:

# Using Pixi
pixi run build

# Using Docker directly
docker build -t arch-devops:latest .

# With no cache (clean build)
pixi run rebuild

Build time: 10-15 minutes (first build), 2-5 minutes (with cache)

Image size: ~3.79GB

Usage

Common Pixi Commands

Command	Description
pixi run dev	Build and run container
pixi run up	Start container
pixi run down	Stop container
pixi run shell	Open bash shell
pixi run logs	View container logs
pixi run status	Show container status
pixi run vnc	Display VNC info
pixi run reset	Clean rebuild

Docker-from-Docker Usage

The container automatically syncs Docker GID at startup:

# Connect to the container
docker exec -it arch-devops bash

# Docker commands work immediately (no sudo needed)
docker ps
docker build -t myimage .
docker-compose up

AWS CLI Usage

# Configure credentials (first time)
docker exec -it arch-devops aws configure

# Or mount your credentials
docker run -v ~/.aws:/home/jovian/.aws:ro ...

# Use AWS commands
docker exec -it arch-devops aws s3 ls
docker exec -it arch-devops aws sts get-caller-identity

Or via pixi tasks:

pixi run aws-whoami
pixi run aws-configure
pixi run aws-s3-ls
pixi run aws-regions

Desktop Environment

Connect via VNC to localhost:5900 to access:

Keybindings (Mod4 = Windows/Super key):

• Mod4+Return - Open terminal
• Mod4+d - Application launcher
• Mod4+c - Google Chrome
• Mod4+Shift+q - Close window
• Right-click - Application launcher

Installed applications:

• Foot terminal
• Google Chrome
• Application launcher (wofi)

Docker-from-Docker Architecture

This container uses Docker-from-Docker (NOT Docker-in-Docker):

Host Machine
  └── Docker Daemon (dockerd)
      └── arch-devops Container
          ├── Docker CLI tools ✓
          ├── /var/run/docker.sock → Host socket ✓
          └── jovian user in docker group ✓

Benefits:

• No nested Docker daemon overhead
• Shares host's Docker image cache
• More efficient resource usage
• Automatic GID synchronization

How it works:

1. Container entrypoint detects host Docker socket GID
2. Updates container's docker group to match
3. Ensures jovian user has access
4. Bashrc auto-refreshes group membership if needed

See CLAUDE.md for complete technical documentation.

Testing

Run the comprehensive test suite:

# All tests
pixi run test-all

# Individual test suites
pixi run test-tools          # Verify all tools installed
pixi run test-docker         # Test Docker integration
pixi run test-devcontainer   # Test DevContainer config
pixi run verify-docker       # Verify Docker permissions

See TEST-PLAN.md for complete testing documentation.

Troubleshooting

Docker Permission Denied

If docker ps fails with permission denied:

# Refresh group membership
exec bash

# Or manually sync GID
docker exec -it arch-devops /usr/local/bin/sync-docker-gid.sh

VNC Not Connecting

Check if services are running:

pixi run health

Should show:

• ✓ Sway running
• ✓ WayVNC running
• ✓ VNC port listening

DevContainer Build Issues

If DevContainer CLI fails to pull image:

# Expected behavior: Falls back to building from Dockerfile

# To use pre-built image, authenticate first:
export GITHUB_TOKEN=your_token
pixi run ghcr-login
pixi run dc-up

Project Structure

arch-devops/
├── .devcontainer/
│   └── devcontainer.json        # VS Code DevContainer config
├── config/
│   ├── s6/                      # Service definitions
│   ├── sway/config              # Window manager config
│   ├── wayvnc/config            # VNC server config
│   ├── wofi/                    # App launcher styling
│   ├── waybar/                  # Status bar config
│   ├── bashrc/bashrc            # User bash config
│   └── applications/            # Desktop entries
├── scripts/
│   ├── docker-entrypoint.sh     # GID sync entrypoint
│   ├── sync-docker-gid.sh       # Docker GID sync script
│   ├── dc-down.sh               # DevContainer lifecycle
│   └── test-*.sh                # Test suites
├── Dockerfile                   # Container definition
├── pixi.toml                    # Task runner config
├── CLAUDE.md                    # Technical documentation
├── REGISTRY.md                  # GHCR publishing guide
└── README.md                    # This file

Documentation

• CLAUDE.md - Complete technical documentation and architecture
• REGISTRY.md - GitHub Container Registry publishing guide
• TEST-PLAN.md - Comprehensive testing strategy
• pixi.toml - All available tasks and commands

Requirements

• Docker: Version 20.10+ (BuildKit support)
• VNC Client: KRDC, TigerVNC, or any VNC viewer
• Pixi (optional): For task automation
• VS Code (optional): For DevContainer support

Environment Variables

Variable	Default	Description
DISPLAY_WIDTH	1920	VNC display width
DISPLAY_HEIGHT	1080	VNC display height
PROJECT_NAME	arch-devops	Project identifier
USER	jovian	Default user

User Configuration

• User: jovian (UID/GID 1000)
• Groups: wheel (sudo), docker
• Workspace: /workspace (mounted from host)
• Home: /home/jovian

Security Notes

• Container runs in privileged mode for nested Docker and device access
• VNC has no authentication (development convenience)
• Docker socket is mounted from host (full access to host Docker)
• Suitable for development environments, not production

Contributing

Contributions welcome! Please:

1. Test changes with pixi run test-all
2. Update documentation as needed
3. Follow existing code style
4. Submit pull requests

License

This project is provided as-is for development use.

Support

For issues, questions, or contributions:

• File issues on GitHub
• Check existing documentation in CLAUDE.md
• Review test plans in TEST-PLAN.md
• Consult GHCR guide in REGISTRY.md

Version

Current version: 1.0.0

See REGISTRY.md for version history and release notes.