Your Name
595 lines
14 KiB
Markdown
595 lines
14 KiB
Markdown
# Development Containers
|
|
|
|
## What is a Development Container?
|
|
|
|
A **Development Container** (devcontainer) is a containerized development environment that provides:
|
|
|
|
- ✅ **Consistent development environment** across all team members
|
|
- ✅ **Pre-configured tools and dependencies** ready to use
|
|
- ✅ **Instant setup** - no manual installation of dependencies
|
|
- ✅ **Isolated environment** that won't conflict with your host system
|
|
- ✅ **Version-controlled configuration** shared with the team
|
|
|
|
The devcontainer includes Python 3.13, all project dependencies, development tools, and shell customizations pre-installed and configured.
|
|
|
|
## Prerequisites
|
|
|
|
You need Docker installed on your system:
|
|
|
|
- [Docker Desktop](https://www.docker.com/products/docker-desktop/) (macOS/Windows)
|
|
- [Docker Engine](https://docs.docker.com/engine/install/) (Linux)
|
|
|
|
Check Docker is working:
|
|
```bash
|
|
docker --version
|
|
docker ps
|
|
```
|
|
|
|
## Quick Start (Terminal-First Approach)
|
|
|
|
### 1. Clone and Build Container
|
|
|
|
```bash
|
|
# Clone the repository
|
|
git clone https://git.cleverthis.com/cleverthis/base/base-python
|
|
cd base-python
|
|
|
|
# Build the development container
|
|
docker build -f .devcontainer/Dockerfile -t cleverclaude-dev .
|
|
|
|
# Run the development container
|
|
docker run -it --rm \
|
|
-v $(pwd):/workspaces/cleverclaude \
|
|
-w /workspaces/cleverclaude \
|
|
--name cleverclaude-dev \
|
|
cleverclaude-dev bash
|
|
```
|
|
|
|
### 2. Inside the Container
|
|
|
|
Once inside the container, everything is pre-configured:
|
|
|
|
```bash
|
|
# Check Python environment
|
|
python --version # Python 3.13.x
|
|
which python # /usr/local/bin/python
|
|
|
|
# Virtual environment is auto-activated
|
|
echo $VIRTUAL_ENV # /workspaces/cleverclaude/.venv
|
|
|
|
# Check tools are installed
|
|
ruff --version # Linting and formatting
|
|
pyright --version # Type checking
|
|
behave --version # BDD testing
|
|
nox --version # Test automation
|
|
|
|
# Run development commands
|
|
nox -s behave # Run BDD tests
|
|
nox -s lint # Run linting
|
|
nox -s format # Format code
|
|
nox -s typecheck # Type checking
|
|
|
|
# Test the CLI
|
|
python -m cleverclaude --name "DevContainer" --count 2
|
|
```
|
|
|
|
### 3. Available Shell Aliases
|
|
|
|
The container includes pre-configured aliases for faster development:
|
|
|
|
```bash
|
|
# Development shortcuts
|
|
dev-test # nox -s behave
|
|
dev-lint # nox -s lint
|
|
dev-format # nox -s format
|
|
dev-type # nox -s typecheck
|
|
dev-docs # nox -s serve_docs
|
|
dev-all # nox (run all checks)
|
|
|
|
# Docker shortcuts
|
|
d # docker
|
|
build-docker # docker build -t cleverclaude:dev .
|
|
|
|
# Git shortcuts
|
|
gs # git status
|
|
ga # git add
|
|
gc # git commit
|
|
gp # git push
|
|
gl # git pull
|
|
|
|
# Python shortcuts
|
|
py # python
|
|
pip # uv pip (faster package manager)
|
|
venv # uv venv
|
|
```
|
|
|
|
### 4. Persistent Development
|
|
|
|
For ongoing development with persistent changes:
|
|
|
|
```bash
|
|
# Create a named container for persistence
|
|
docker run -it \
|
|
-v $(pwd):/workspaces/cleverclaude \
|
|
-v cleverclaude-venv:/workspaces/cleverclaude/.venv \
|
|
-v cleverclaude-cache:/tmp/uv-cache \
|
|
-w /workspaces/cleverclaude \
|
|
--name cleverclaude-dev-persistent \
|
|
cleverclaude-dev bash
|
|
|
|
# Later, restart the same container
|
|
docker start -ai cleverclaude-dev-persistent
|
|
```
|
|
|
|
## IDE Integration
|
|
|
|
### Emacs with TRAMP
|
|
|
|
Connect to your running container from Emacs:
|
|
|
|
```bash
|
|
# 1. Start container with SSH (add to Dockerfile if needed)
|
|
docker run -it --name cleverclaude-dev \
|
|
-v $(pwd):/workspaces/cleverclaude \
|
|
-p 2222:22 \
|
|
cleverclaude-dev
|
|
|
|
# 2. In Emacs, connect via TRAMP
|
|
# M-x find-file
|
|
# /docker:cleverclaude-dev:/workspaces/cleverclaude/
|
|
```
|
|
|
|
**Emacs Configuration:**
|
|
```elisp
|
|
;; .emacs or init.el
|
|
(require 'tramp)
|
|
(setq tramp-default-method "docker")
|
|
|
|
;; Python development
|
|
(use-package python-mode)
|
|
(use-package lsp-mode
|
|
:hook ((python-mode . lsp)))
|
|
(use-package lsp-pyright
|
|
:after lsp-mode)
|
|
|
|
;; Connect to container Python
|
|
(setq python-interpreter "/usr/local/bin/python")
|
|
```
|
|
|
|
### Vim/Neovim
|
|
|
|
#### Option 1: Terminal Vim Inside Container
|
|
|
|
```bash
|
|
# Run container with vim pre-installed
|
|
docker run -it --rm \
|
|
-v $(pwd):/workspaces/cleverclaude \
|
|
-w /workspaces/cleverclaude \
|
|
cleverclaude-dev vim
|
|
|
|
# Or use neovim if installed
|
|
docker run -it --rm \
|
|
-v $(pwd):/workspaces/cleverclaude \
|
|
-w /workspaces/cleverclaude \
|
|
cleverclaude-dev nvim
|
|
```
|
|
|
|
#### Option 2: Host Vim with Container Tools
|
|
|
|
```bash
|
|
# 1. Start container as daemon
|
|
docker run -d --name cleverclaude-tools \
|
|
-v $(pwd):/workspaces/cleverclaude \
|
|
-w /workspaces/cleverclaude \
|
|
cleverclaude-dev tail -f /dev/null
|
|
|
|
# 2. Create wrapper scripts
|
|
cat > vim-ruff << 'EOF'
|
|
#!/bin/bash
|
|
docker exec cleverclaude-tools ruff "$@"
|
|
EOF
|
|
chmod +x vim-ruff
|
|
|
|
# 3. Configure Vim to use container tools
|
|
```
|
|
|
|
**Vim Configuration:**
|
|
```vim
|
|
" .vimrc or init.vim
|
|
" Python development setup
|
|
let g:python3_host_prog = 'docker exec cleverclaude-tools python'
|
|
|
|
" Use container tools for linting
|
|
let g:ale_linters = {
|
|
\ 'python': ['ruff'],
|
|
\}
|
|
let g:ale_python_ruff_executable = './vim-ruff'
|
|
|
|
" Use container tools for formatting
|
|
let g:ale_fixers = {
|
|
\ 'python': ['ruff'],
|
|
\}
|
|
```
|
|
|
|
### VS Code
|
|
|
|
#### Option 1: Terminal-First with VS Code Terminal
|
|
|
|
```bash
|
|
# 1. Start container
|
|
docker run -it --name cleverclaude-dev \
|
|
-v $(pwd):/workspaces/cleverclaude \
|
|
-w /workspaces/cleverclaude \
|
|
cleverclaude-dev bash
|
|
|
|
# 2. Open VS Code and connect to terminal
|
|
# Terminal → New Terminal
|
|
# Select "Docker" or connect to running container
|
|
```
|
|
|
|
#### Option 2: Dev Containers Extension
|
|
|
|
```bash
|
|
# 1. Install Dev Containers extension
|
|
# Extensions → Search "Dev Containers" → Install
|
|
|
|
# 2. Open project folder
|
|
code .
|
|
|
|
# 3. Reopen in container
|
|
# Ctrl+Shift+P → "Dev Containers: Reopen in Container"
|
|
```
|
|
|
|
**VS Code Configuration:**
|
|
The `.devcontainer/devcontainer.json` is pre-configured with:
|
|
- Python 3.13 environment
|
|
- 15+ relevant extensions
|
|
- Proper settings for ruff, pyright
|
|
- Integrated terminal with aliases
|
|
- Port forwarding for development servers
|
|
|
|
### PyCharm
|
|
|
|
#### Option 1: Remote Python Interpreter
|
|
|
|
```bash
|
|
# 1. Start container as daemon
|
|
docker run -d --name cleverclaude-pycharm \
|
|
-v $(pwd):/workspaces/cleverclaude \
|
|
-p 2222:22 \
|
|
cleverclaude-dev
|
|
|
|
# 2. Configure PyCharm remote interpreter
|
|
# File → Settings → Project → Python Interpreter
|
|
# Add Interpreter → Docker → Existing container
|
|
# Container: cleverclaude-pycharm
|
|
# Python path: /usr/local/bin/python
|
|
```
|
|
|
|
#### Option 2: Docker Compose Integration
|
|
|
|
Create `docker-compose.dev.yml`:
|
|
```yaml
|
|
version: '3.8'
|
|
services:
|
|
dev:
|
|
build:
|
|
context: .
|
|
dockerfile: .devcontainer/Dockerfile
|
|
volumes:
|
|
- .:/workspaces/cleverclaude
|
|
- cleverclaude-venv:/workspaces/cleverclaude/.venv
|
|
working_dir: /workspaces/cleverclaude
|
|
command: tail -f /dev/null
|
|
ports:
|
|
- "8000:8000"
|
|
- "3000:3000"
|
|
|
|
volumes:
|
|
cleverclaude-venv:
|
|
```
|
|
|
|
```bash
|
|
# Start development environment
|
|
docker-compose -f docker-compose.dev.yml up -d
|
|
|
|
# PyCharm configuration
|
|
# File → Settings → Build, Execution, Deployment → Docker
|
|
# Add Docker server (usually auto-detected)
|
|
# Configure Python interpreter to use docker-compose service
|
|
```
|
|
|
|
**PyCharm Configuration Steps:**
|
|
1. **Settings** → **Project** → **Python Interpreter**
|
|
2. **Add Interpreter** → **Docker Compose**
|
|
3. **Configuration file**: `docker-compose.dev.yml`
|
|
4. **Service**: `dev`
|
|
5. **Python interpreter path**: `/usr/local/bin/python`
|
|
6. **Apply** and **OK**
|
|
|
|
## What's Included in the Container
|
|
|
|
### 🐍 **Python Environment**
|
|
```bash
|
|
python --version # Python 3.13.x
|
|
pip --version # uv-powered pip replacement
|
|
which python # /usr/local/bin/python
|
|
echo $PYTHONPATH # /workspaces/cleverclaude/src
|
|
```
|
|
|
|
### 🛠️ **Development Tools**
|
|
```bash
|
|
ruff --version # Lightning-fast linting and formatting
|
|
pyright --version # Strict type checking
|
|
nox --version # Test automation across Python versions
|
|
behave --version # BDD testing framework
|
|
hypothesis --version # Property-based testing
|
|
pre-commit --version # Git hooks for code quality
|
|
```
|
|
|
|
### 🔧 **System Tools**
|
|
```bash
|
|
git --version # Git with helpful aliases
|
|
docker --version # Docker-in-Docker for building containers
|
|
kubectl version --client # Kubernetes CLI
|
|
helm version # Helm package manager
|
|
gh --version # GitHub CLI for repository management
|
|
```
|
|
|
|
### 📝 **Shell Environment**
|
|
```bash
|
|
echo $SHELL # /bin/zsh (Oh My Zsh configured)
|
|
alias # List all available aliases
|
|
env | grep PYTHON # Python-related environment variables
|
|
```
|
|
|
|
## Advanced Usage
|
|
|
|
### Port Forwarding
|
|
|
|
Forward ports from container to host:
|
|
|
|
```bash
|
|
# Forward development server ports
|
|
docker run -it --rm \
|
|
-v $(pwd):/workspaces/cleverclaude \
|
|
-w /workspaces/cleverclaude \
|
|
-p 8000:8000 \
|
|
-p 3000:3000 \
|
|
-p 8080:8080 \
|
|
cleverclaude-dev bash
|
|
|
|
# Now you can access:
|
|
# http://localhost:8000 - Application server
|
|
# http://localhost:3000 - MkDocs development server
|
|
# http://localhost:8080 - Development server
|
|
```
|
|
|
|
### Volume Mounts for Performance
|
|
|
|
For better performance, especially on macOS/Windows:
|
|
|
|
```bash
|
|
# Use named volumes for dependencies
|
|
docker run -it --rm \
|
|
-v $(pwd):/workspaces/cleverclaude \
|
|
-v cleverclaude-venv:/workspaces/cleverclaude/.venv \
|
|
-v cleverclaude-cache:/tmp/uv-cache \
|
|
-v cleverclaude-node-modules:/workspaces/cleverclaude/node_modules \
|
|
-w /workspaces/cleverclaude \
|
|
cleverclaude-dev bash
|
|
```
|
|
|
|
### Custom Configuration
|
|
|
|
Mount custom configuration files:
|
|
|
|
```bash
|
|
# Mount custom git config
|
|
docker run -it --rm \
|
|
-v $(pwd):/workspaces/cleverclaude \
|
|
-v ~/.gitconfig:/home/vscode/.gitconfig:ro \
|
|
-v ~/.ssh:/home/vscode/.ssh:ro \
|
|
-w /workspaces/cleverclaude \
|
|
cleverclaude-dev bash
|
|
|
|
# Mount custom shell config
|
|
docker run -it --rm \
|
|
-v $(pwd):/workspaces/cleverclaude \
|
|
-v ~/.zshrc:/home/vscode/.zshrc.local:ro \
|
|
-w /workspaces/cleverclaude \
|
|
cleverclaude-dev bash
|
|
```
|
|
|
|
### Development Workflow
|
|
|
|
```bash
|
|
# 1. Start development container
|
|
docker run -it --name dev-session \
|
|
-v $(pwd):/workspaces/cleverclaude \
|
|
-v cleverclaude-venv:/workspaces/cleverclaude/.venv \
|
|
-p 3000:3000 \
|
|
-w /workspaces/cleverclaude \
|
|
cleverclaude-dev bash
|
|
|
|
# 2. Inside container - start documentation server
|
|
nox -s serve_docs & # Runs in background
|
|
|
|
# 3. Make changes to code
|
|
vim src/cleverclaude/cli.py
|
|
|
|
# 4. Run tests
|
|
dev-test # Quick BDD tests
|
|
|
|
# 5. Check code quality
|
|
dev-lint # Linting
|
|
dev-format # Auto-format code
|
|
dev-type # Type checking
|
|
|
|
# 6. Run full test suite
|
|
dev-all # All checks
|
|
|
|
# 7. Exit container (preserves named volumes)
|
|
exit
|
|
|
|
# 8. Later, restart same session
|
|
docker start -ai dev-session
|
|
```
|
|
|
|
## GitHub Codespaces Alternative
|
|
|
|
For cloud-based development without local Docker:
|
|
|
|
```bash
|
|
# 1. Go to your GitHub repository
|
|
# 2. Click "Code" → "Codespaces" → "Create codespace on main"
|
|
# 3. Wait 2-3 minutes for automatic setup
|
|
# 4. Everything is pre-configured and ready!
|
|
|
|
# Inside Codespace, same commands work:
|
|
nox -s behave # Run tests
|
|
dev-all # Run all checks
|
|
python -m cleverclaude --help
|
|
```
|
|
|
|
**Codespace Features:**
|
|
- 🌐 **Browser-based**: No local setup required
|
|
- ⚡ **Fast SSD storage**: 32GB workspace storage
|
|
- 🔄 **Persistent**: Your work is saved automatically
|
|
- 💰 **Free tier**: 60 hours/month for personal accounts
|
|
- 🔒 **Secure**: Runs in GitHub's infrastructure
|
|
|
|
## Troubleshooting
|
|
|
|
### Container Won't Start
|
|
|
|
```bash
|
|
# Check Docker is running
|
|
docker --version
|
|
docker ps
|
|
|
|
# Free up disk space
|
|
docker system prune -f
|
|
|
|
# Rebuild container
|
|
docker build -f .devcontainer/Dockerfile -t cleverclaude-dev . --no-cache
|
|
```
|
|
|
|
### Permission Issues
|
|
|
|
```bash
|
|
# Run as your user ID
|
|
docker run -it --rm \
|
|
-u $(id -u):$(id -g) \
|
|
-v $(pwd):/workspaces/cleverclaude \
|
|
-w /workspaces/cleverclaude \
|
|
cleverclaude-dev bash
|
|
|
|
# Or fix permissions after
|
|
sudo chown -R $(id -u):$(id -g) .
|
|
```
|
|
|
|
### Tools Not Working
|
|
|
|
```bash
|
|
# Check if tools are installed
|
|
docker run --rm cleverclaude-dev which ruff pyright behave nox
|
|
|
|
# Check PATH
|
|
docker run --rm cleverclaude-dev echo $PATH
|
|
|
|
# Reinstall dependencies
|
|
docker run -it --rm \
|
|
-v $(pwd):/workspaces/cleverclaude \
|
|
-w /workspaces/cleverclaude \
|
|
cleverclaude-dev bash -c "uv pip install -e .[dev]"
|
|
```
|
|
|
|
### Performance Issues
|
|
|
|
```bash
|
|
# Allocate more resources to Docker
|
|
# Docker Desktop → Settings → Resources
|
|
# Memory: 4GB+, CPU: 2+ cores
|
|
|
|
# Use volumes for better performance
|
|
docker run -it --rm \
|
|
-v $(pwd):/workspaces/cleverclaude \
|
|
-v cleverclaude-cache:/tmp/uv-cache \
|
|
-w /workspaces/cleverclaude \
|
|
cleverclaude-dev bash
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
### 🔄 **Container Lifecycle**
|
|
```bash
|
|
# For short tasks - use --rm
|
|
docker run --rm cleverclaude-dev nox -s lint
|
|
|
|
# For development sessions - use named containers
|
|
docker run --name dev-session cleverclaude-dev bash
|
|
docker start -ai dev-session # Resume later
|
|
```
|
|
|
|
### 📁 **Volume Management**
|
|
```bash
|
|
# List volumes
|
|
docker volume ls
|
|
|
|
# Clean up unused volumes
|
|
docker volume prune
|
|
|
|
# Backup important data
|
|
docker run --rm -v cleverclaude-venv:/data -v $(pwd):/backup \
|
|
alpine tar czf /backup/venv-backup.tar.gz -C /data .
|
|
```
|
|
|
|
### 🔒 **Security**
|
|
```bash
|
|
# Don't store secrets in container images
|
|
# Use environment variables or mounted secrets
|
|
docker run -e SECRET_KEY="$SECRET_KEY" cleverclaude-dev
|
|
|
|
# Use read-only mounts when possible
|
|
docker run -v $(pwd):/workspace:ro cleverclaude-dev
|
|
```
|
|
|
|
### ⚡ **Performance**
|
|
```bash
|
|
# Use named volumes for dependencies
|
|
-v cleverclaude-venv:/workspaces/cleverclaude/.venv
|
|
|
|
# Enable BuildKit for faster builds
|
|
export DOCKER_BUILDKIT=1
|
|
docker build -f .devcontainer/Dockerfile -t cleverclaude-dev .
|
|
|
|
# Use multi-stage builds for smaller images (already configured)
|
|
```
|
|
|
|
## Integration with CI/CD
|
|
|
|
The devcontainer environment matches your CI/CD pipeline exactly:
|
|
|
|
- ✅ **Same Python version** (3.13)
|
|
- ✅ **Same tools** (ruff, pyright, behave)
|
|
- ✅ **Same dependencies** (from pyproject.toml)
|
|
- ✅ **Same commands** (nox sessions)
|
|
|
|
This eliminates "works on my machine" problems completely!
|
|
|
|
```bash
|
|
# What works in container will work in CI
|
|
dev-all # Local testing
|
|
# Same as CI pipeline commands in .forgejo/workflows/ci.yml
|
|
```
|
|
|
|
## Further Reading
|
|
|
|
- [Development Containers Specification](https://containers.dev/)
|
|
- [Docker Best Practices](https://docs.docker.com/develop/dev-best-practices/)
|
|
- [Container Security Guide](https://docs.docker.com/engine/security/)
|
|
|
|
---
|
|
|
|
**Ready to develop?** Start with the terminal-first approach and choose your preferred editor integration! |