Configuration

libreStage wird über zwei Konfigurationsdateien gesteuert: die .env-Datei für serverseitige Einstellungen und appConfig.json für anwendungsspezifische Anpassungen.

Environment variables (`.env`)

First copy the template:

cp .env.example .env

Then fill in all relevant values:

Variable	Default	Beschreibung
`SECRET_KEY`	–	Pflichtfeld. Langer, zufälliger String zum Signieren von JWTs. Niemals öffentlich!
`ENVIRONMENT`	`production`	`development` deaktiviert das Secure-Flag für Cookies (nötig auf `localhost`)
`CORS_ORIGINS`	`http://localhost:5173`	Allowed frontend origins (comma-separated)
`FRONTEND_URL`	`http://localhost:5173`	Base URL of the frontend (used in emails)
`DATABASE_URL`	`sqlite:///./backend/db/app.db`	SQLAlchemy database URL (SQLite or PostgreSQL)
`TIMEZONE`	`Europe/Berlin`	Application timezone (IANA format)
`SMTP_HOST`	–	SMTP server for email sending (optional)
`SMTP_PORT`	`587`	SMTP port
`SMTP_USER`	–	SMTP username
`SMTP_PASSWORD`	–	SMTP password
`MATTERMOST_WEBHOOK_URL`	–	Webhook-URL für Mattermost-Benachrichtigungen (optional)

Application configuration (`appConfig.json`)

Die Datei appConfig.json im Projekt-Root enthält alle band-spezifischen Einstellungen, die ohne erneutes Bauen des Frontends geändert werden können.

Ab v0.4.0 koennen Admins die weichen Parameter auch direkt in der Weboberflaeche unter Admin-Konfiguration pflegen.

{
  "app_name": "libreStage",
  "app_name_short": "LS",
  "timezone": "Europe/Berlin",
  "default_break_seconds": 30
}

Field	Beschreibung
`app_name`	Full application name (appears in the header)
`app_name_short`	Kurzname / Kürzel der Band
`app_title`	Application subtitle
`timezone`	Zeitzone (IANA-Format, muss mit `.env` übereinstimmen)
`default_break_seconds`	Standard-Pausenlänge zwischen Sets in Sekunden (Standard: 30)
`genres`	Liste verfügbarer Genres für Songs
`gigTypes`	Auswahlliste für den Veranstaltungstyp
`tonekeys`	Verfügbare Tonarten
`rehearsalSongStatuses`	Song-Statuswerte für Proben-Ansichten

Song status

Status	Meaning
`vorschlag`	Song has been proposed but not yet reviewed
`angenommen`	Song ist grundsätzlich akzeptiert
`proben`	Song is actively being rehearsed
`spielbar`	Song ist bühnenreif und kann in Setlists eingesetzt werden
`bedarfsweise_proben`	Song ist spielbar, wird aber bei Bedarf nochmals geprobt

Gig status

Status	Meaning
`anfrage`	Gig request received, no confirmation yet
`angenommen`	Performance has been confirmed
`abgelehnt`	Gig request was declined

Frontend configuration

Das Frontend lädt die Konfiguration zur Laufzeit vom Backend-Endpoint /public/app_config. Für den Entwicklungsmodus wird die API-URL über VITE_API_URL gesteuert:

# frontend/.env (für lokale Entwicklung)
VITE_API_URL=http://localhost:8000

Selbstheilung bei fehlenden Keys

Ab v0.5.22 prüft das Backend beim Start automatisch, ob alle Pflicht-Keys in appConfig.json vorhanden sind. Fehlt ein Key, wird er sofort mit einem leeren Standardwert befüllt und die Datei atomar zurückgeschrieben – die Anwendung startet damit fehlerfrei weiter.

Key	Standardwert bei fehlendem Eintrag
`genres`	`[]` (leere Liste)
`gigTypes`	`[]` (leere Liste)
`songStatuses`	`[]` (leere Liste)
`gigStatuses`	`[]` (leere Liste)
`tonekeys`	`[]` (leere Liste)
`rehearsalSongStatuses`	`[]` (leere Liste)
`danceStyles`	`[]` (leere Liste)
`setlist_timing`	Standard-Timings: Song 240 s, Pause zwischen Songs 30 s, Set-Pause 600 s

Note

Alle automatisch ergänzten Keys werden im Server-Log mit WARNING-Level gemeldet. Die ergänzte appConfig.json sollte anschliessend über die Admin-Oberfläche (Admin-Konfiguration) mit den gewünschten Werten befüllt werden.