ausgaben-next/DEPLOYMENT.md

Deployment Guide - Ausgaben-Next

Lokale Entwicklung

Voraussetzungen

• Node.js 22+
• MySQL 8+ (Docker container läuft bereits)
• npm oder yarn

Setup

1. Dependencies installieren:

npm install

2. Umgebungsvariablen konfigurieren:

cp .env.example .env
# Bearbeiten Sie .env mit Ihren Datenbankzugangsdaten

3. Development Server starten:

npm run dev

Die Anwendung ist dann unter http://localhost:3000 erreichbar.

Production Deployment

Mit Docker (Empfohlen)

1. Lokaler Build:

docker-compose -f docker-compose.local.yml build
docker-compose -f docker-compose.local.yml up -d

Die Anwendung läuft dann auf Port 3001 (konfigurierbar in docker-compose.local.yml).

2. Logs prüfen:

docker logs ausgaben-next-app

Ohne Docker

1. Production Build:

npm run build

2. Production Server starten:

npm start

Datenbank

Schema erstellen

Falls die Tabelle Ausgaben noch nicht existiert:

mysql -u root -p RXF < create_table.sql

Das Script legt auch die Tabelle ausgaben_passkeys für die Passkey-Anmeldung an. Die Anwendung erstellt diese Tabelle beim ersten Zugriff selbst — hat der DB-Benutzer keine CREATE-Rechte, das SQL aus create_table.sql manuell ausführen.

Passkeys (WebAuthn) konfigurieren

Im Container erwartet die Anwendung RP_ID, RP_ORIGIN und RP_NAME. In der Compose-Datei werden diese aus den app-eigenen Variablen AUSGABEN_RP_* befüllt — mit den Produktionswerten als Default:

- RP_ID=${AUSGABEN_RP_ID:-ausgaben.fuerst-stuttgart.de}
- RP_ORIGIN=${AUSGABEN_RP_ORIGIN:-https://ausgaben.fuerst-stuttgart.de}
- RP_NAME=${AUSGABEN_RP_NAME:-Ausgaben-Log}

Warum eigene Namen: Auf dem Server (/opt/stacks/myapp/) laufen mehrere Apps im selben Stack und teilen sich eine .env. Dort sind RP_ID/RP_ORIGIN bereits für werte-next gesetzt. Würde diese App dieselben Namen lesen, bekäme sie werte's Host — und die Passkey-Anmeldung schlüge fehl. Die Defaults oben greifen, solange in der geteilten .env keine AUSGABEN_RP_* stehen; ein Eintrag dort überschreibt sie.

Wichtig: RP_ID muss exakt dem Hostnamen entsprechen (ohne https:// und ohne Port), RP_ORIGIN der vollen URL. Passen die Werte nicht zur aufgerufenen Adresse, schlägt die Passkey-Anmeldung fehl. Bereits registrierte Passkeys werden bei einer Änderung von RP_ID ungültig. WebAuthn setzt HTTPS voraus (via Traefik).

Datenbank-Verbindung

Die Anwendung verwendet die gleiche MySQL-Datenbank wie die alte Ausgaben-Anwendung:

• Host: gitea-db (oder localhost für lokale Entwicklung)
• Database: RXF
• Table: Ausgaben

Die Zugangsdaten werden über Umgebungsvariablen in .env konfiguriert.

Umgebungsvariablen

Erforderliche Variablen in .env:

DB_HOST=gitea-db          # oder localhost für lokale Entwicklung
DB_USER=root
DB_PASS=Ihr_Passwort
DB_NAME=RXF

Port-Konfiguration

• Development: Port 3000 (npm run dev)
• Production (lokal): Port 3000 (npm start)
• Docker (lokal): Port 3001 (gemappt auf internen Port 3000)

Ändern Sie den Port in docker-compose.local.yml falls nötig:

ports:
  - "0.0.0.0:DEIN_PORT:3000"

Troubleshooting

Datenbankverbindung schlägt fehl

1. Prüfen Sie die Umgebungsvariablen in .env
2. Stellen Sie sicher, dass der MySQL-Container läuft:

   docker ps | grep mysql
   

3. Falls Docker verwendet wird, prüfen Sie ob die Container im gleichen Netzwerk sind

Build-Fehler

1. Löschen Sie .next und node_modules:

   rm -rf .next node_modules
   npm install
   npm run build
   

2. Prüfen Sie die Node.js Version:

   node --version  # Sollte >= 22.x sein
   

Port bereits belegt

Ändern Sie den Port in docker-compose.local.yml oder verwenden Sie einen anderen Port:

PORT=3002 npm run dev

Monitoring

Logs ansehen

Docker:

docker logs -f ausgaben-next-app

Ohne Docker: Logs werden in der Konsole angezeigt wo npm start läuft.

Updates

1. Code aktualisieren:

git pull  # falls Git verwendet wird

2. Dependencies aktualisieren:

npm install

3. Neu bauen und starten:

npm run build
# Dann entweder:
npm start
# oder:
docker-compose -f docker-compose.local.yml up -d --build

Backup

Datenbank

Die Datenbank sollte regelmäßig gesichert werden:

mysqldump -u root -p RXF Ausgaben > backup_$(date +%Y%m%d).sql

Application Files

Wichtige Dateien für Backup:

• .env (Konfiguration)
• public/ (falls custom Dateien hinzugefügt wurden)
• Die Datenbank (siehe oben)

Security

1. Niemals .env ins Git-Repository einchecken!
2. Verwenden Sie starke Datenbankpasswörter
3. Halten Sie Dependencies aktuell:

   npm audit
   npm update