design final

DEV_SETUP.md

@@ -0,0 +1,78 @@
+# 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