# Development Setup Guide

## Quick Start for Local Development

The `run_app.py` script mimics Docker production conditions while enabling fast iteration.

### Standard Development Mode (Recommended)
```bash
python run_app.py
```

**Features:**
- ✓ Loads environment variables from `.env` file
- ✓ Single Uvicorn worker with **fast auto-reload**
- ✓ Mimics Docker environment (`PYTHONUNBUFFERED=1`)
- ✓ Creates upload directory automatically
- ✓ Binds to `0.0.0.0:8000` (same as Docker)

**Best for:** Quick code iterations, template changes, debugging

### Production-Like Mode
```bash
python run_app.py --gunicorn
```

**Features:**
- ✓ Gunicorn with 4 Uvicorn workers (exactly like Docker)
- ✓ 120s timeout (same as Docker)
- ✓ Gunicorn's reload (slower but tests production server)
- ✓ Tests multi-worker behavior

**Best for:** Testing before deploying to Docker, load testing

## Environment Variables

The script automatically loads `.env` file variables:
- `RATE_PER_M2_BLACK` - Black & white print rate (default: 4.0)
- `RATE_PER_M2_COLOR` - Color print rate (default: 5.0)
- `SERVER_HOSTNAME` - Server hostname (default: einszwovier.local)
- `BOOKSTACK_PORT`, `OPENWEBUI_PORT`, `PORTAINER_PORT` - Service ports
- `MATRIX_USER`, `MATRIX_PASS`, `MATRIX_HOMESERVER` - Matrix integration

## Comparison: Dev vs Docker

| Feature | `python run_app.py` | `docker-compose up` |
|---------|---------------------|---------------------|
| Server | Uvicorn (single worker) | Gunicorn + Uvicorn (4 workers) |
| Auto-reload | ✓ Fast (watches all files) | ✓ Slow (Docker rebuild) |
| Env loading | `.env` file | `.env` file |
| Port | 8000 | 80→8000 |
| Memory limit | None | 1GB limit |
| Health checks | No | Yes |
| Dependencies | All services | Isolated |

## Troubleshooting

### `.env` file not found
Create `.env` file from template:
```bash
cp .env.example .env
```

### Port 8000 already in use
```bash
# Find and kill process
lsof -ti:8000 | xargs kill -9
```

### Environment variables not loading
Ensure `python-dotenv` is installed:
```bash
pip install python-dotenv
```

### Testing Matrix integration locally
1. Start Matrix server: `docker-compose up synapse -d`
2. Run app: `python run_app.py`
3. Submit test order via `/cost` endpoint