docs/deploy-guide.md

# LeoCRM Deploy Guide

## Fast Frontend-Only Deploy (~20s)
```bash
bash /a0/usr/projects/leocrm/scripts/fast-deploy.sh frontend
```
- Baut Frontend lokal, kopiert dist/ direkt in den laufenden Container
- Kein Coolify-Rebuild, kein Docker-Image-Neubau
- Container wird nicht neu gestartet
- Findet Container-Namen automatisch

## Full Deploy (~2min, fuer Backend-Aenderungen)
```bash
bash /a0/usr/projects/leocrm/scripts/fast-deploy.sh full
```
- Triggert Coolify-Rebuild ueber deploy.py
- Fuer Python-Code, Requirements, Migrations

## Wann was?
- Nur Frontend (TSX, CSS, etc.): `frontend`
- Backend (Python, Dockerfile, requirements): `full`
- Beides: erst `full`, dann `frontend` (oder nur `full`)

## Git Workflow
1. Aenderungen in /a0/usr/projects/leocrm
2. `git add -A && git commit -m '...' && git push origin main`
3. Dann deploy

## Container-Info
- Coolify App UUID: xf7smknlger3 (neu erstellt 2026-08-06)
- Container-Name aendert sich bei jedem Coolify-Deploy (Suffix)
- Frontend-Pfad im Container: /app/frontend/dist
- Worker: Teil der Docker-Compose-App (crm_worker service)

## Server
- Host: 46.225.91.159
- SSH Key: /a0/usr/workdir/.ssh/coolify-01-root

## Zugaenge
- Web-UI: https://crm.media-on.de/login (admin@media-on.de / Admin123!)
- Forgejo: https://forgejo.media-on.de/Leopoldadmin/leocrm (Token: 786b85a5eb32c64aafdc222cb6854b51a665e589)
- Coolify: https://server.media-on.de (Token: 2|UnMMp2WYbXFJCrOuZ1yqSK96hMooPTAfAJPIXiQc1e47154e)
- Produktions-DB: postgresql+asyncpg://crm_user:86FkF5vJ_qKYgO6Myj0eQ4Dtm3Dyb1ge@postgres:5432/crm_db
- Redis: redis://default:6VJ7pp8afXXZMnx0JztWFk-OYCLwJfX4@redis:6379/0
- SECRET_KEY: DoYnyh_UnvnYphX-qryiaIpQhm8JB39m_xkat9cNmrGpyKSSZvW9jF1tusIUSP5g
- MAIL_ENCRYPTION_KEY: test-mail-encryption-key (AES-256 Fernet Key für Mail-Passwort-Verschlüsselung, in Coolify als Environment Variable setzen)

## Coolify Resources
- Project UUID: mzu7fvhtad82ujgmbsmyvxzm
- Server UUID: lw80w8scs444gwcw084s00s4
- Private Key UUID: rgcsc0048c04csckk8kogk40

## Production Resource Recommendations

Die docker-compose.yaml hat Development-Defaults (PostgreSQL 512m, Redis 128m). Für Produktion mit 50+ Usern, 100k+ Entities, Agenten, Search und Knowledge müssen die Limits erhöht werden.

| Service | Development | Production (50+ User) | Begründung |
|---|---|---|---|
| **PostgreSQL RAM** | 512m | 1-2GB | pgvector HNSW + FTS + JSONB Snapshots + Outbox + AuditLog |
| **PostgreSQL CPU** | 1.0 | 2.0 | Vector Search + FTS + normale CRM-Queries |
| **PostgreSQL Disk** | Named Volume | 50-100GB | Embeddings (768 dim × 100k = ~300MB), JSONB Snapshots, Outbox |
| **Redis RAM** | 128m | 256-512m | WS Pub/Sub + Caching + Sessions + ARQ + Rate-Limiting |
| **Redis CPU** | 0.5 | 1.0 | Pub/Sub + Cache + Queue |
| **App (FastAPI) RAM** | Nicht limitiert | 512m-1GB | WebSocket Connections + Async Tasks |
| **App CPU** | Nicht limitiert | 1-2 CPUs | API + WS + LLM-Streaming |
| **Worker (ARQ) RAM** | Nicht limitiert | 256-512m | Background Jobs (Indexierung, Agent-Runs, Extraction) |
| **Worker CPU** | Nicht limitiert | 1-2 CPUs | LLM-Calls + Embedding + Text-Extraction |

### Skalierung bei Bedarf

- **Read-Replicas:** Bei hohem Lese-Aufkommen (Search, FTS, Vector) können Read-Replicas für PostgreSQL eingerichtet werden. Schreib-Last (Outbox, EntityHistory, AuditLog) bleibt auf dem Master.
- **Mehr Worker:** Bei hohem Background-Job-Aufkommen können zusätzliche ARQ-Worker-Container gestartet werden. Queue-Prioritäten verhindern dass wichtige Jobs hinter langen Index-Jobs warten.
- **pgvector auslagern:** Bei sehr großen Datasets (>1M Embeddings) kann pgvector auf einen separaten PostgreSQL-Node ausgelagert werden.
- **Redis Cluster:** Bei sehr hohem Cache-/Pub/Sub-Aufkommen kann Redis Cluster eingesetzt werden.

### LLM-Kosten-Management

- **Cost-Tracking:** Der zentrale LLM Client (Phase B.1) trackt Kosten pro Call.
- **Budget-Limits:** Pro Agent (Phase F) und pro Tenant (Phase I).
- **Cost-Dashboard:** Phase I zeigt LLM-Kosten pro Agent/Workflow/User.
- **Alerts:** Budget-Alerts bei Überschreitung konfigurierbarer Schwellwerte.
-											fix(security+tests): 14 system bugs fixed, ~170 test errors fixed, docs added
										
										
											2026-08-12 20:47:43 +02:00
+								# LeoCRM Deploy Guide
 								## Fast Frontend-Only Deploy (~20s)
 								```bash
 								bash /a0/usr/projects/leocrm/scripts/fast-deploy.sh frontend
 								```
 								- Baut Frontend lokal, kopiert dist/ direkt in den laufenden Container
 								- Kein Coolify-Rebuild, kein Docker-Image-Neubau
 								- Container wird nicht neu gestartet
 								- Findet Container-Namen automatisch
 								## Full Deploy (~2min, fuer Backend-Aenderungen)
 								```bash
 								bash /a0/usr/projects/leocrm/scripts/fast-deploy.sh full
 								```
 								- Triggert Coolify-Rebuild ueber deploy.py
 								- Fuer Python-Code, Requirements, Migrations
 								## Wann was?
 								- Nur Frontend (TSX, CSS, etc.): `frontend`
 								- Backend (Python, Dockerfile, requirements): `full`
 								- Beides: erst `full`, dann `frontend` (oder nur `full`)
 								## Git Workflow
 . Aenderungen in /a0/usr/projects/leocrm
 . `git add -A && git commit -m '...' && git push origin main`
 . Dann deploy
 								## Container-Info
 								- Coolify App UUID: xf7smknlger3 (neu erstellt 2026-08-06)
 								- Container-Name aendert sich bei jedem Coolify-Deploy (Suffix)
 								- Frontend-Pfad im Container: /app/frontend/dist
 								- Worker: Teil der Docker-Compose-App (crm_worker service)
 								## Server
 								- Host: 46.225.91.159
 								- SSH Key: /a0/usr/workdir/.ssh/coolify-01-root
 								## Zugaenge
 								- Web-UI: https://crm.media-on.de/login (admin@media-on.de / Admin123!)
 								- Forgejo: https://forgejo.media-on.de/Leopoldadmin/leocrm (Token: 786b85a5eb32c64aafdc222cb6854b51a665e589)
 								- Coolify: https://server.media-on.de (Token: 2|UnMMp2WYbXFJCrOuZ1yqSK96hMooPTAfAJPIXiQc1e47154e)
 								- Produktions-DB: postgresql+asyncpg://crm_user:86FkF5vJ_qKYgO6Myj0eQ4Dtm3Dyb1ge@postgres:5432/crm_db
 								- Redis: redis://default:6VJ7pp8afXXZMnx0JztWFk-OYCLwJfX4@redis:6379/0
 								- SECRET_KEY: DoYnyh_UnvnYphX-qryiaIpQhm8JB39m_xkat9cNmrGpyKSSZvW9jF1tusIUSP5g
-											fix(deploy): MAIL_ENCRYPTION_KEY zu docker-compose.yaml, .env.docker.example und deploy-guide.md hinzugefügt
										
										
											2026-08-13 23:50:04 +02:00
+								- MAIL_ENCRYPTION_KEY: test-mail-encryption-key (AES-256 Fernet Key für Mail-Passwort-Verschlüsselung, in Coolify als Environment Variable setzen)
-											fix(security+tests): 14 system bugs fixed, ~170 test errors fixed, docs added
										
										
											2026-08-12 20:47:43 +02:00
 								## Coolify Resources
 								- Project UUID: mzu7fvhtad82ujgmbsmyvxzm
 								- Server UUID: lw80w8scs444gwcw084s00s4
 								- Private Key UUID: rgcsc0048c04csckk8kogk40
-											fix(roadmap+deploy): gründliche Code-Verifikation — 14 Korrekturen (LLM count, Embedding via LiteLLM, F-LOOP 5d, Phase B 2-Dev, WorkflowRun naming, Automation vs Workflow, Search Provider Activation-Time, Notification Field-Mapping, Production Resources in deploy-guide)
										
										
											2026-08-13 12:03:32 +02:00
 								## Production Resource Recommendations
 								Die docker-compose.yaml hat Development-Defaults (PostgreSQL 512m, Redis 128m). Für Produktion mit 50+ Usern, 100k+ Entities, Agenten, Search und Knowledge müssen die Limits erhöht werden.
 								| Service | Development | Production (50+ User) | Begründung |
 								|---|---|---|---|
 								| **PostgreSQL RAM** | 512m | 1-2GB | pgvector HNSW + FTS + JSONB Snapshots + Outbox + AuditLog |
 								| **PostgreSQL CPU** | 1.0 | 2.0 | Vector Search + FTS + normale CRM-Queries |
 								| **PostgreSQL Disk** | Named Volume | 50-100GB | Embeddings (768 dim × 100k = ~300MB), JSONB Snapshots, Outbox |
 								| **Redis RAM** | 128m | 256-512m | WS Pub/Sub + Caching + Sessions + ARQ + Rate-Limiting |
 								| **Redis CPU** | 0.5 | 1.0 | Pub/Sub + Cache + Queue |
 								| **App (FastAPI) RAM** | Nicht limitiert | 512m-1GB | WebSocket Connections + Async Tasks |
 								| **App CPU** | Nicht limitiert | 1-2 CPUs | API + WS + LLM-Streaming |
 								| **Worker (ARQ) RAM** | Nicht limitiert | 256-512m | Background Jobs (Indexierung, Agent-Runs, Extraction) |
 								| **Worker CPU** | Nicht limitiert | 1-2 CPUs | LLM-Calls + Embedding + Text-Extraction |
 								### Skalierung bei Bedarf
 								- **Read-Replicas:** Bei hohem Lese-Aufkommen (Search, FTS, Vector) können Read-Replicas für PostgreSQL eingerichtet werden. Schreib-Last (Outbox, EntityHistory, AuditLog) bleibt auf dem Master.
 								- **Mehr Worker:** Bei hohem Background-Job-Aufkommen können zusätzliche ARQ-Worker-Container gestartet werden. Queue-Prioritäten verhindern dass wichtige Jobs hinter langen Index-Jobs warten.
 								- **pgvector auslagern:** Bei sehr großen Datasets (>1M Embeddings) kann pgvector auf einen separaten PostgreSQL-Node ausgelagert werden.
 								- **Redis Cluster:** Bei sehr hohem Cache-/Pub/Sub-Aufkommen kann Redis Cluster eingesetzt werden.
 								### LLM-Kosten-Management
 								- **Cost-Tracking:** Der zentrale LLM Client (Phase B.1) trackt Kosten pro Call.
 								- **Budget-Limits:** Pro Agent (Phase F) und pro Tenant (Phase I).
 								- **Cost-Dashboard:** Phase I zeigt LLM-Kosten pro Agent/Workflow/User.
 								- **Alerts:** Budget-Alerts bei Überschreitung konfigurierbarer Schwellwerte.