code-tools/WARP.md

# WARP.md

This file provides guidance to WARP (warp.dev) when working with code in this repository.

## Common Commands

### Python Development
```bash
# Run the main application
python main.py

# Install dependencies with uv (modern Python package manager)
uv pip install -r requirements.txt  # If requirements file exists
uv add <package>                     # Add new dependency
uv remove <package>                  # Remove dependency

# Alternative with pip
pip install -e .                     # Install in development mode
```

### Container Development
```bash
# Build devcontainer (safe - no coolify disruption)
docker compose -f .devcontainer/docker-compose.yml build

# Build coder workspace container
docker compose -f coder-compose.yaml build

# Note: Avoid docker compose up/down/restart - services run in coolify
```

### Terraform Workspace Management
```bash
# Initialize and work with Coder workspace templates
cd tf-dockerfile
terraform init
terraform plan
terraform apply

# Check workspace status
terraform show
terraform output
```

### Development Tools
```bash
# Run development info script (if available in devcontainer)
devinfo

# Claude CLI helpers (if installed)
claude auth login
claude chat
claude edit <file>
claude-help

# Git with credential helper (configured as 'store')
git clone <repo>
git push  # Uses stored credentials
```

## Architecture Overview

### Repository Structure
- **`main.py`**: Simple Python entry point application
- **`.devcontainer/`**: VS Code devcontainer configuration with comprehensive tooling
- **`tf-dockerfile/`**: Terraform module for provisioning Coder workspaces
- **`coder-compose.yaml`**: Docker Compose configuration for Coder service
- **`pyproject.toml`**: Python project configuration (requires Python >=3.12)

### Development Environment Layers
1. **Base Layer**: Universal devcontainer image (`mcr.microsoft.com/devcontainers/universal:2-linux`)
2. **Language Support**: Python 3.12, Node.js LTS, Go, Rust, Terraform
3. **Development Tools**: Git, GitHub CLI, Docker-in-Docker, various CLI utilities
4. **AI Integration**: Claude Code CLI, Cursor IDE, Windsurf IDE support
5. **Database Services**: Optional PostgreSQL, Redis, Qdrant with pgAdmin

### Coder Workspace Architecture
- **Workspace Container**: Runs development environment with mounted home directory
- **Service Network**: Isolated Docker network for workspace services
- **Data Persistence**: Separate volumes for workspace data and user home
- **Port Forwarding**: Automatic setup for development services (3000, 5000, 8000, 8080, etc.)

## Development Environment Setup

### Prerequisites
- Docker and Docker Compose
- VS Code with Dev Containers extension (for devcontainer)
- Terraform >= 1.3.0 (for workspace management)
- Python >= 3.12 (if running outside container)

### Environment Configuration
The devcontainer automatically configures:
- **Shell**: Zsh with Oh My Zsh and enhanced aliases
- **Git**: Credential helper set to 'store', configured for lab SSL certificates
- **CLI Tools**: bat, fd, ripgrep, eza, lazygit, htop, and others
- **AI Tools**: Claude Code CLI, IDE integrations for Cursor and Windsurf

### Key Environment Variables
- `POSTGRES_URL`: Database connection string (when services enabled)
- `REDIS_URL`: Redis connection string (when services enabled) 
- `QDRANT_URL`: Vector database connection string (when services enabled)
- `CODER_WORKSPACE_ID`: Unique workspace identifier
- `ENABLE_SERVICES`: Toggle for database services
- `ENABLE_PGADMIN`/`ENABLE_MARIMO`: Toggle for admin interfaces

## Terraform Workspace Template

The `tf-dockerfile/` directory contains a complete Terraform module for provisioning Coder workspaces:

### Key Features
- **Customizable Base Image**: Defaults to universal devcontainer but configurable
- **Optional Services**: Toggle PostgreSQL, Redis, Qdrant with single parameter
- **AI Tool Integration**: Automated setup of Claude, Cursor, Windsurf tooling
- **Repository Cloning**: Automatic git clone of specified repositories
- **SSL Certificate Handling**: Automatic lab certificate installation and Git configuration

### Workspace Parameters
- `project_repository`: Git URL to clone into workspace
- `enable_services`: Boolean for database services
- `enable_ai_tools`: Boolean for AI helper installation
- `enable_pgadmin`: Boolean for database admin interface
- `enable_marimo`: Boolean for notebook interface
- `enable_jetbrains`: Boolean for JetBrains Gateway integration

### Important Files
- `main.tf`: Core infrastructure and Docker resources
- `workspace.tf`: Coder agent and workspace container configuration
- `services.tf`: Database and service definitions
- `apps.tf`: Coder application definitions and port forwarding
- `scripts.tf`: Startup script resources for development tools

## Development Workflow

### Starting Development
1. Use devcontainer in VS Code or deploy Terraform workspace in Coder
2. Workspace automatically installs development tools and configures environment
3. Git credentials and SSH keys are mounted from host system
4. Services (if enabled) start automatically with health checks

### Working with Services
- PostgreSQL: Available at `postgres-{workspace-id}:5432`
- Redis: Available at `redis-{workspace-id}:6379`
- Qdrant: Available at `qdrant-{workspace-id}:6333`
- pgAdmin: Accessible via port forwarding on localhost:5050
- Marimo: Accessible via port forwarding on localhost:6333

### Port Forwarding
The workspace automatically forwards common development ports and provides scripts for accessing database services on the local machine when services are enabled.