Setup Guide

Setup Guide

Voraussetzungen

• Docker & Docker Compose
• Git
• Flutter SDK (für App-Entwicklung)
• Python 3.13 (für Backend-Entwicklung ohne Docker)

Zwei Compose-Dateien — welche nehmen?

Datei	Zweck
docker-compose.yml	Joshuas persönliches Dev-Setup. Kein eigener Postgres-Service, keine Port-Mappings — setzt ein extern existierendes Docker-Netzwerk (core_network) und einen zentralen Postgres-Host voraus. Nicht direkt für Dritte nutzbar.
docker-compose.prod.yml	Eigenständiger Stack mit Postgres, Redis, Backend, Celery, Celery-Beat, Frontend und Nginx. Empfohlener Weg für eigenes Self-Hosting. Nutzt vorgebaute Images von ghcr.io/commanderphu/workmate_private/* — bei einem Fork müssen diese selbst gebaut werden.

Self-Hosting mit docker-compose.prod.yml

# Repo clonen
git clone https://github.com/commanderphu/workmate_private.git
cd workmate_private

# Umgebungsvariablen konfigurieren
cp .env.example .env
# .env anpassen (POSTGRES_PASSWORD, SECRET_KEY, CLAUDE_API_KEY, ...)

# Falls kein Firebase-Projekt vorhanden: Platzhalter-Datei anlegen,
# sonst startet der Container nicht (Pfad ist fest gemountet)
echo '{}' > firebase-credentials.json

# Container starten
docker compose -f docker-compose.prod.yml up -d

# Datenbank initialisieren
docker compose -f docker-compose.prod.yml exec backend alembic upgrade head

Die App ist danach über die in nginx/conf.d/ konfigurierte Domain erreichbar (Nginx terminiert TLS auf Port 80/443 und routet intern an Backend/Frontend). Es gibt in diesem Setup keine direkt exponierten localhost:8000/:3000-Ports.

• API Docs: https://<deine-domain>/api/v1/docs
• Health: https://<deine-domain>/health/ui

Umgebungsvariablen (siehe .env.example)

Variable	Beschreibung
DATABASE_URL	PostgreSQL Connection String
POSTGRES_PASSWORD	Postgres-Passwort (nur docker-compose.prod.yml)
SECRET_KEY	JWT Secret Key (min. 32 Zeichen)
ACCESS_TOKEN_EXPIRE_MINUTES	Access-Token-Laufzeit (Default 30)
REFRESH_TOKEN_EXPIRE_DAYS	Refresh-Token-Laufzeit (Default 7)
CLAUDE_API_KEY	Anthropic API Key für Dokumentenanalyse
CELERY_BROKER_URL / CELERY_RESULT_BACKEND	Redis-Connection für Celery (nicht REDIS_URL)
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET / GOOGLE_REDIRECT_URI	Google Calendar OAuth (optional)
FIREBASE_CREDENTIALS_PATH	Pfad zur Firebase-Service-Account-JSON (optional, aber Datei muss existieren wenn gemountet)
PAPERLESS_URL / PAPERLESS_TOKEN	Paperless-ngx Integration (optional)
ALLOWED_ORIGINS	CORS, kommagetrennt oder JSON-Array
ENVIRONMENT	development oder production
DEBUG	true / false

Flutter App

cd frontend
flutter pub get
flutter run --dart-define=API_URL=https://<deine-domain>/api/v1

Release-APK-Build und Keystore-Handling siehe Deployment.

Datenbank-Migrationen

# Neue Migration erstellen
docker compose -f docker-compose.prod.yml exec backend alembic revision --autogenerate -m "beschreibung"

# Migration anwenden
docker compose -f docker-compose.prod.yml exec backend alembic upgrade head

# Migration rückgängig machen
docker compose -f docker-compose.prod.yml exec backend alembic downgrade -1

---

← Integrationen | → API Reference