https://github.com/atrawog/arch-devops
DevOps development container based on Arch Linux with Wayland desktop, VNC access, and Docker-from-Docker support
https://github.com/atrawog/arch-devops
arch-linux devcontainer devops docker infrastructure-as-code kubernetes vnc wayland
Last synced: about 2 months ago
JSON representation
DevOps development container based on Arch Linux with Wayland desktop, VNC access, and Docker-from-Docker support
- Host: GitHub
- URL: https://github.com/atrawog/arch-devops
- Owner: atrawog
- Created: 2025-10-29T16:00:11.000Z (8 months ago)
- Default Branch: main
- Last Pushed: 2025-10-29T16:03:19.000Z (8 months ago)
- Last Synced: 2025-10-29T18:08:20.152Z (8 months ago)
- Topics: arch-linux, devcontainer, devops, docker, infrastructure-as-code, kubernetes, vnc, wayland
- Language: Shell
- Size: 64.5 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# 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:
```bash
# 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](https://pixi.sh) for streamlined task management:
```bash
# 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:
```bash
# 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
```bash
# 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](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:
```bash
# 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](REGISTRY.md) for complete publishing documentation.
## Building from Source
If you prefer to build locally:
```bash
# 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:
```bash
# 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
```bash
# 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:
```bash
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](CLAUDE.md) for complete technical documentation.
## Testing
Run the comprehensive test suite:
```bash
# 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](TEST-PLAN.md) for complete testing documentation.
## Troubleshooting
### Docker Permission Denied
If `docker ps` fails with permission denied:
```bash
# 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:
```bash
pixi run health
```
Should show:
- ✓ Sway running
- ✓ WayVNC running
- ✓ VNC port listening
### DevContainer Build Issues
If DevContainer CLI fails to pull image:
```bash
# 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](CLAUDE.md)** - Complete technical documentation and architecture
- **[REGISTRY.md](REGISTRY.md)** - GitHub Container Registry publishing guide
- **[TEST-PLAN.md](TEST-PLAN.md)** - Comprehensive testing strategy
- **[pixi.toml](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](REGISTRY.md) for version history and release notes.