https://github.com/kirkchen/devbox
https://github.com/kirkchen/devbox
Last synced: 4 months ago
JSON representation
- Host: GitHub
- URL: https://github.com/kirkchen/devbox
- Owner: kirkchen
- Created: 2025-08-12T09:18:28.000Z (11 months ago)
- Default Branch: main
- Last Pushed: 2026-02-20T14:35:29.000Z (5 months ago)
- Last Synced: 2026-02-20T18:20:01.348Z (5 months ago)
- Language: Shell
- Size: 171 KB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
Awesome Lists containing this project
README
# Universal DevContainer with Chezmoi Dotfiles
A minimal, robust development container setup with intelligent cross-platform dotfiles management using Chezmoi.
## Features
- ๐ณ **DevContainer**: Pre-configured Ubuntu 22.04 environment with VS Code integration
- ๐ฆ **Prebuilt Image**: Published to GitHub Container Registry for fast startup in other projects
- ๐ง **Chezmoi**: Smart dotfiles management with automatic environment detection
- ๐ **Oh-My-Zsh**: Bullet-train theme with essential plugins
- ๐ ๏ธ **Modern CLI Tools**: fzf, eza, bat, ag, lazygit, delta, and more
- ๐ฅ๏ธ **Multi-Environment Support**: Automatic detection for macOS, Linux, and DevContainers
- โ๏ธ **Minimal Configuration**: Only asks for name and email
- ๐ก๏ธ **Defensive Programming**: Robust error handling and fallback mechanisms
- ๐ค **Claude Code Integration**: Pre-configured settings, plugins, and MCP servers
## Quick Start
### Option 1: Use Prebuilt Image in Your Projects (Fastest)
For the fastest setup in your other projects, use the prebuilt image from GitHub Container Registry:
1. Copy the `.devcontainer/devcontainer.json` from this repo to your project
2. Replace the `build` section with:
```json
"image": "ghcr.io/kirkchen/devbox-devcontainer:latest"
```
3. Keep only the features you need (most are already in the image):
```json
"features": {
"ghcr.io/schlich/devcontainer-features/playwright:0": {}
}
```
4. Open in VS Code with Dev Containers extension
**Startup time: ~30 seconds** instead of 5-10 minutes!
### Option 2: Using This DevContainer (Development)
1. Open this folder in VS Code
2. Install the "Dev Containers" extension if not already installed
3. Press `Cmd/Ctrl + Shift + P` and select "Dev Containers: Reopen in Container"
4. After the container builds, run `setup-dotfiles` to configure your environment
5. Follow the prompts to enter your name and email
### Option 3: Local Setup (macOS/Linux)
1. Install Chezmoi:
```bash
# macOS
brew install chezmoi
# Linux
sh -c "$(curl -fsLS get.chezmoi.io)"
```
2. Initialize from this repository:
```bash
# From the devbox directory
chezmoi init --source="./chezmoi" --apply
```
3. Follow the interactive prompts to configure:
- Your name
- Your email
- GitHub token (optional, for MCP server)
## Directory Structure
```
devbox/
โโโ .devcontainer/ # DevContainer configuration
โ โโโ devcontainer.json # Container settings
โ โโโ Dockerfile # Multi-arch container image
โ โโโ scripts/
โ โโโ setup-dotfiles.sh # Interactive dotfiles setup
โ โโโ welcome.sh # Welcome message
โโโ .github/
โ โโโ workflows/
โ โโโ build-devcontainer.yml # Automated image building
โโโ chezmoi/ # Chezmoi-managed dotfiles
โ โโโ .chezmoi.toml.tmpl # Interactive configuration template
โ โโโ .chezmoiignore # Files to ignore
โ โโโ .chezmoiscripts/ # One-time setup scripts
โ โ โโโ run_once_01-install-oh-my-zsh.sh
โ โ โโโ run_once_02-install-cli-tools.sh.tmpl
โ โ โโโ run_once_04-install-claude-plugins.sh
โ โโโ dot_gitconfig.tmpl # Git configuration
โ โโโ dot_zshrc.tmpl # Zsh configuration
โ โโโ dot_claude.json.tmpl # Claude Code MCP servers
โ โโโ dot_vimrc # Vim configuration
โ โโโ private_dot_claude/ # Claude Code settings
โ โ โโโ settings.json.tmpl
โ โ โโโ settings.md # Settings documentation
โ โ โโโ CLAUDE.md.tmpl # Development guidelines
โ โโโ private_dot_config/
โ โโโ lazygit/
โ โ โโโ config.yml # Lazygit config (delta pager)
โ โโโ zsh/ # Modular Zsh configs
โ โ โโโ oh-my-zsh.zsh
โ โ โโโ core.zsh.tmpl
โ โ โโโ tools.zsh # macOS: Homebrew, rbenv, NVM, pnpm
โ โ โโโ functions.zsh # Cross-platform: now(), fixup()
โ โ โโโ functions-macos.zsh # macOS: code()
โ โ โโโ aliases.zsh # Git, K8s, tools aliases
โ โ โโโ gitpod.zsh # Gitpod environment management
โ โโโ raycast/
โ โโโ scripts/ # macOS Raycast scripts
โโโ install.sh # Automated installation script
```
## Included Tools
### Shell & Terminal
- **Zsh**: Modern shell with Oh-My-Zsh framework
- **Theme**: Bullet-train theme with proper font support
### CLI Tools
- **fzf**: Fuzzy finder with intelligent fallback (ag โ rg โ find)
- **eza**: Modern replacement for ls (successor to exa)
- **bat**: Cat with syntax highlighting (multi-architecture support)
- **ag**: The Silver Searcher for fast code search
- **lazygit**: Git TUI (uses delta as pager)
- **delta**: Modern git diff viewer (side-by-side, line numbers)
- **htop**: Interactive process viewer
- **direnv**: Environment variable management
### Development
- **Git**: Version control with defensive aliases
- **Vim**: Text editor with essential plugins (NERDTree, fzf.vim, CoC)
- **VS Code**: Integrated with DevContainer
- **Claude Code**: Pre-configured with plugins and MCP servers
### macOS Specific
- **Homebrew**: Package manager integration
- **rbenv**: Ruby version management (if installed)
- **NVM**: Node.js version management (if installed)
- **pnpm**: Fast package manager (if installed)
- **Raycast**: WiFi management scripts
## Configuration
### Interactive Setup
When you first run `chezmoi init` or `setup-dotfiles`, you'll be prompted for:
- **Name**: Used in Git commits and configurations
- **Email**: Used in Git configuration
- **GitHub Token**: Optional, for Claude Code MCP server
The system automatically detects your environment (macOS, Linux, or DevContainer) and configures accordingly.
### Shell Aliases
#### Git Aliases (with comments)
| Alias | Command | Description |
|-------|---------|-------------|
| `gbr` | `git branch` | ๅๅบๅๆฏ |
| `gcbr` | `git rev-parse --abbrev-ref HEAD` | ้กฏ็คบ็ฎๅๅๆฏๅ็จฑ |
| `gpsu` | `git push --set-upstream origin $(gcbr)` | ๆจ้ไธฆ่จญๅฎ upstream |
| `gcoi` | Interactive checkout with fzf | ไบๅๅผๅๆๅๆฏ |
| `gmi` | Interactive merge with fzf | ไบๅๅผๅไฝตๅๆฏ |
| `gmdb` | Delete branches by namespace | ๅช้คๆๅฎ namespace ็ๅๆฏ |
| `gdt` | `git difftool` | ้ๅ diff ๅทฅๅ
ท |
| `,,` | `cd $(git rev-parse --show-toplevel)` | ่ทณๅฐ git repo ๆ น็ฎ้ |
#### Kubernetes Aliases
| Alias | Description |
|-------|-------------|
| `kctxi` | ไบๅๅผๅๆ Kubernetes context |
| `knsi` | ไบๅๅผๅๆ Kubernetes namespace |
#### Tool Aliases
| Alias | Description |
|-------|-------------|
| `lg` | lazygit |
| `cat` | bat (if installed) |
| `ls/ll/lt` | eza with icons (if installed) |
### Shell Functions
| Function | Description |
|----------|-------------|
| `now` | ่ผธๅบ UTC ๆ้ๆณ่จ (YYYYMMDDHHmmss) |
| `fixup ` | ๅปบ็ซ fixup commit ไธฆ่ชๅ rebase |
| `code [path]` | ็จ VS Code ้ๅๆชๆกๆ็ฎ้ (macOS) |
### Gitpod Environment Management (Linux/DevContainer)
```bash
gpenv start # Start a stopped environment and optionally SSH into it
gpenv stop # Stop a running environment
gpenv ssh # SSH into a running environment
gpenv open # Open a running environment in browser
gpenv list # List all environments
# Shortcut aliases
gps / gpt / gpsh / gpo / gpl
```
### Claude Code Configuration
Pre-configured with:
- **Status Line**: Shows `๐ฟ branch | model | directory`
- **Plugins**: code-review, superpowers
- **Language**: Traditional Chinese (zh-TW)
- **Security**: Blocks reading `.env*` and `secrets/` files
- **MCP Servers**: sequential-thinking, context7, github (if token provided)
## Prebuilt Image
This repository automatically publishes a prebuilt Docker image to GitHub Container Registry, perfect for use in other projects.
### Available Image
- `ghcr.io/kirkchen/devbox-devcontainer:latest`
### Automatic Updates
GitHub Actions automatically builds and publishes new images when:
- `.devcontainer/Dockerfile` is modified (pushed to main branch)
- Manually triggered via GitHub Actions
## Updating Dotfiles
### Modify Templates
1. Edit files in the `chezmoi/` directory
2. Apply changes: `chezmoi apply --source="./chezmoi"`
### Add New Files
1. Add to chezmoi: `chezmoi add ~/.config/newfile --source="./chezmoi"`
2. Commit changes to repository
### Sync Across Machines
```bash
# Pull latest changes
cd ~/Code/devbox
git pull
# Apply to current machine
chezmoi apply --source="./chezmoi"
```
## Key Features
### Defensive Programming
- **Command existence checks**: Aliases only created if commands exist
- **Intelligent fallbacks**: FZF uses ag โ rg โ find chain
- **Confirmation prompts**: Destructive operations require confirmation
- **Error handling**: Proper error suppression and handling
- **Platform detection**: Automatic environment adaptation
### Environment Detection
The configuration automatically detects and adapts to:
- **macOS**: Homebrew paths, version managers, Raycast scripts
- **Linux**: APT/DNF package managers, Linux paths
- **DevContainer**: Container-optimized settings, Gitpod management
## Troubleshooting
### Font Issues
If Powerline symbols don't align:
1. Install a Nerd Font (see Fonts section)
2. Set terminal font to the Mono variant
3. Restart terminal
### Permission Issues
```bash
# Fix script permissions
chmod +x .devcontainer/scripts/*.sh
chmod +x chezmoi/.chezmoiscripts/*.sh
```
### Chezmoi Not Found
```bash
# Install manually
curl -fsLS get.chezmoi.io | sh
export PATH="$HOME/.local/bin:$PATH"
```
### Tool Not Available
The configuration includes fallbacks for missing tools:
- If `bat` is not available, `cat` works normally
- If `eza` is not available, `ls` is used
- If `ag` is not available, `rg` or `find` is used for FZF
## Fonts
For the best terminal experience, install a Nerd Font:
- [SauceCodePro Nerd Font](https://github.com/ryanoasis/nerd-fonts/tree/master/patched-fonts/SourceCodePro)
- [MesloLGS NF](https://github.com/romkatv/powerlevel10k#meslo-nerd-font-patched-for-powerlevel10k)
## License
MIT
## Contributing
Feel free to submit issues and pull requests to improve this setup!