This document provides comprehensive instructions for using VSCode Dev Containers with the IndexAgent project, enabling consistent development environments across macOS and Windows.
- Overview
- Prerequisites
- Getting Started
- Architecture
- Features
- Usage
- Troubleshooting
- Advanced Configuration
- Cross-Platform Considerations
VSCode Dev Containers provide a consistent, isolated development environment that works identically across different operating systems. This setup allows you to:
- Work on the same codebase from both macOS and Windows
- Ensure all team members have identical development environments
- Isolate project dependencies from your host system
- Run Docker containers within the development environment
- Access all necessary development tools pre-configured
-
VSCode with the Dev Containers extension
# Install the Remote Development extension pack code --install-extension ms-vscode-remote.vscode-remote-extensionpack -
Docker Desktop
- macOS: Docker Desktop for Mac
- Windows: Docker Desktop for Windows
-
Git (usually pre-installed or available through system package managers)
- macOS: macOS 10.15 or later
- Windows: Windows 10/11 with WSL2 enabled
- RAM: Minimum 8GB, recommended 16GB
- Storage: At least 10GB free space for containers and images
git clone https://github.com/your-org/IndexAgent.git
cd IndexAgentcode .When you open the project, VSCode will detect the Dev Container configuration and prompt you to reopen in a container. Click "Reopen in Container" or:
- Press
Ctrl+Shift+P(orCmd+Shift+Pon macOS) - Type "Dev Containers: Reopen in Container"
- Select the command
The first time you open the container, it will:
- Build the development image (5-10 minutes)
- Install all dependencies
- Configure the development environment
- Set up helpful scripts and tools
Dev Container
├── Python 3.11 Environment
├── Docker-in-Docker Support
├── Development Tools
│ ├── black (code formatting)
│ ├── ruff (linting)
│ ├── mypy (type checking)
│ ├── pytest (testing)
│ └── coverage (test coverage)
├── Node.js Tools
│ ├── Claude CLI
│ └── markdownlint
└── System Tools
├── git
├── make
└── various utilities
- Project Code:
/workspaces/IndexAgent(your project directory) - Host Repos:
~/repos→/repos(for accessing other repositories) - Docker Socket: Host Docker socket mounted for Docker-in-Docker
- 6070: Zoekt UI
- 3000: Sourcebot UI
- 8080: IndexAgent API
- black: Code formatting with 100-character line length
- ruff: Fast Python linter with comprehensive rules
- mypy: Static type checking
- pytest: Testing framework with coverage support
- invoke: Task runner for automation
- Claude CLI: AI-powered code assistance
- markdownlint: Markdown linting and formatting
- Docker CLI: Full Docker functionality
- docker-compose: Container orchestration
- git: Version control with sensible defaults
- make: Build automation
The Dev Container automatically installs and configures:
-
Python Development
- Python extension with Pylance
- Black formatter
- MyPy type checker
- Ruff linter
- Pytest test runner
-
Docker & Infrastructure
- Docker extension
- Makefile tools
-
Code Quality
- Coverage gutters
- Test adapters
-
Documentation
- Markdown support
- Markdownlint
The setup includes several convenience scripts in ~/.local/bin:
Runs the complete test suite with coverage reporting:
run-testsFormats code and runs all linting checks:
lint-codeStarts the full IndexAgent Docker stack:
start-stack-
Start Development Session
# Open VSCode and reopen in container code . # VSCode will prompt to reopen in container
-
Run Tests
run-tests # Or use VSCode's integrated test runner -
Format and Lint Code
lint-code # Or save files to auto-format with black -
Work with Docker
# Start the full stack start-stack # Or run individual containers docker run -d --name test-container nginx # Use docker-compose cd config docker-compose up -d
# Run all tests
pytest
# Run with coverage
pytest --cov=indexagent --cov-report=term-missing
# Run specific test file
pytest tests/test_example.py
# Run with verbose output
pytest -v# Run integration tests
pytest tests/integration/
# Run specific integration test
pytest tests/integration/test_high_load_20.py# Format all Python files
black .
# Check what would be formatted
black --check .# Lint all files
ruff check .
# Fix auto-fixable issues
ruff check --fix .# Type check the indexagent package
mypy indexagent/
# Type check with configuration
mypy --config-file=pyproject.toml indexagent/# Start all services
cd config
docker-compose up -d
# View logs
docker-compose logs -f
# Stop all services
docker-compose down# List running containers
docker ps
# View container logs
docker logs <container-name>
# Execute commands in containers
docker exec -it <container-name> bashSymptoms: VSCode shows "Failed to start container"
Solutions:
# Check Docker is running
docker version
# Rebuild the container
# In VSCode: Ctrl+Shift+P → "Dev Containers: Rebuild Container"
# Or manually rebuild
docker build -t indexagent-devcontainer .devcontainer/Symptoms: "Permission denied" when running Docker commands
Solutions:
# On Linux/WSL2, ensure user is in docker group
sudo usermod -aG docker $USER
# Then restart your session
# On macOS/Windows, restart Docker DesktopSymptoms: "Port already in use" errors
Solutions:
# Check what's using the port
lsof -i :6070 # or :3000, :8080
# Kill the process or change port in devcontainer.jsonSymptoms: Container operations are slow
Solutions:
- Increase Docker Desktop memory allocation (8GB+)
- Use volume mounts instead of bind mounts for large directories
- Enable Docker Desktop's "Use the WSL 2 based engine" on Windows
Symptoms: Import errors or missing packages
Solutions:
# Reinstall dependencies
pip install -r requirements-dev.txt
# Clear pip cache
pip cache purge
# Rebuild container with clean slate
# VSCode: "Dev Containers: Rebuild Container Without Cache"File Permission Issues:
# If you see permission errors with mounted volumes
sudo chown -R $(whoami) ~/reposDocker Desktop Not Starting:
- Check System Preferences → Security & Privacy for blocked software
- Restart Docker Desktop
- Reset Docker Desktop to factory defaults if needed
WSL2 Integration Issues:
# Ensure WSL2 is enabled
wsl --set-default-version 2
# Update WSL2 kernel
wsl --updateLine Ending Issues:
# Configure git to handle line endings
git config --global core.autocrlf input
git config --global core.eol lfPath Issues:
- Ensure Docker Desktop has access to your drives
- Use WSL2 paths when possible:
/mnt/c/Users/...
Edit .devcontainer/devcontainer.json:
{
"customizations": {
"vscode": {
"extensions": [
"existing-extensions...",
"new.extension.id"
]
}
}
}Edit .devcontainer/Dockerfile:
RUN apt-get update \
&& apt-get -y install --no-install-recommends \
your-new-package \
&& apt-get clean -yAdd to devcontainer.json:
{
"remoteEnv": {
"YOUR_VAR": "value"
}
}For better performance, consider using named volumes for large directories:
{
"mounts": [
"source=indexagent-node-modules,target=/workspaces/IndexAgent/node_modules,type=volume"
]
}Configure Docker Desktop resource limits:
- Memory: 8GB minimum, 16GB recommended
- CPU: Use all available cores
- Disk: At least 64GB for container images
The Dev Container handles path differences automatically:
- Windows:
C:\Users\username\repos→/repos - macOS:
/Users/username/repos→/repos - Linux:
/home/username/repos→/repos
Git is configured to handle line endings consistently:
# These are set automatically in the container
git config core.autocrlf input
git config core.eol lfUse the localEnv feature for platform-specific paths:
{
"mounts": [
"source=${localEnv:HOME}${localEnv:USERPROFILE}/repos,target=/repos,type=bind"
]
}The container automatically mounts the correct Docker socket:
- Unix systems:
/var/run/docker.sock - Windows: Named pipe (handled by Docker Desktop)
The Dev Container has access to the host Docker daemon. This means:
- Containers started inside can access the host network
- Be cautious with untrusted code or containers
- Consider using Docker-in-Docker for complete isolation if needed
Never commit secrets to the repository. Use:
- Environment variables
- Docker secrets
- External secret management systems
Example .env file (not committed):
CLAUDE_API_KEY=your-secret-key
DATABASE_PASSWORD=your-db-passwordWhen contributing to the Dev Container configuration:
- Test changes on both macOS and Windows
- Update this documentation for any new features
- Ensure backward compatibility when possible
- Add appropriate comments to configuration files
For issues with the Dev Container setup:
- Check this documentation first
- Search existing GitHub issues
- Create a new issue with:
- Your operating system
- Docker Desktop version
- VSCode version
- Error messages and logs