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:**
```bash
npm install
```

2. **Umgebungsvariablen konfigurieren:**
```bash
cp .env.example .env
# Bearbeiten Sie .env mit Ihren Datenbankzugangsdaten
```

3. **Development Server starten:**
```bash
npm run dev
```

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

## Production Deployment

### Mit Docker (Empfohlen)

1. **Lokaler Build:**
```bash
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:**
```bash
docker logs ausgaben-next-app
```

### Ohne Docker

1. **Production Build:**
```bash
npm run build
```

2. **Production Server starten:**
```bash
npm start
```

## Datenbank

### Schema erstellen

Falls die Tabelle `Ausgaben` noch nicht existiert:

```bash
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:

```yaml
- 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`:

```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:

```yaml
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:
   ```bash
   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`:
   ```bash
   rm -rf .next node_modules
   npm install
   npm run build
   ```

2. Prüfen Sie die Node.js Version:
   ```bash
   node --version  # Sollte >= 22.x sein
   ```

### Port bereits belegt

Ändern Sie den Port in `docker-compose.local.yml` oder verwenden Sie einen anderen Port:
```bash
PORT=3002 npm run dev
```

## Monitoring

### Logs ansehen

**Docker:**
```bash
docker logs -f ausgaben-next-app
```

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

## Updates

1. **Code aktualisieren:**
```bash
git pull  # falls Git verwendet wird
```

2. **Dependencies aktualisieren:**
```bash
npm install
```

3. **Neu bauen und starten:**
```bash
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:

```bash
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:
   ```bash
   npm audit
   npm update
   ```