124-webapp/DEV_SETUP.md

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)

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

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:

cp .env.example .env

Port 8000 already in use

# Find and kill process
lsof -ti:8000 | xargs kill -9

Environment variables not loading

Ensure python-dotenv is installed:

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