# Avaria Team OS — Betrieb (Server / `screen`)

Kurzanleitung, um den Server dauerhaft über `screen` laufen zu lassen.

## Voraussetzungen

- **Node.js 20+** und **npm**
- **MySQL/MariaDB** erreichbar (Datenbank `avaria_team_os` + zugehöriger Benutzer)
- Eine gepflegte **`.env`** (siehe `.env.example`)

## 1. `.env` konfigurieren

Aus `.env.example` kopieren und mindestens setzen:

| Variable | Bedeutung |
|---|---|
| `DATABASE_URL` | Verbindung zur MariaDB |
| `AUTH_SECRET` | zufälliges Secret (`npx auth secret`) |
| `AUTH_URL` / `APP_URL` | öffentliche URL des Servers (z. B. `https://os.avaria-media.de`) |
| `AUTH_TRUST_HOST` | `true` hinter Reverse-Proxy |
| `ADMIN_EMAIL` / `ADMIN_PASSWORD` | initiales Admin-Konto (vom Seed angelegt) |
| `VAULT_MASTER_KEY` | Hauptschlüssel des Passwortmanagers (`openssl rand -base64 32`) |

> **Passwortmanager:** `VAULT_MASTER_KEY` einmalig setzen und wie ein Backup-Schlüssel
> verwahren. Fehlt er, wird ersatzweise ein Schlüssel aus `AUTH_SECRET` abgeleitet —
> dann macht ein Wechsel des `AUTH_SECRET` alle gespeicherten Zugangsdaten
> unlesbar. Der Schlüssel gehört **nicht** in dieselbe Sicherung wie der Datenbank-Dump,
> sonst hebt man die Verschlüsselung praktisch auf.

Optional: `MAIL_*` (Passwort-Reset-Mails), `TWITCH_*` / `YOUTUBE_API_KEY` (Creator-Tracking, aktuell deaktiviert), `CREATORS_SYNC_SECRET`.

### Ausschreibungen, Bewerbungen & Kontaktanfragen — `FORMS_DATABASE_URL`

Die drei Module **Ausschreibungen**, **Bewerbungen** und **Kontaktanfragen** lesen und
schreiben in der Datenbank, die sich Team OS mit der öffentlichen Website teilt.
Diese Verbindung ist bewusst getrennt von `DATABASE_URL`:

```
FORMS_DATABASE_URL="mysql://forms_user:PASSWORT@127.0.0.1:3306/avaria_web"
```

* **Eigener Datenbankbenutzer**, nicht der von Team OS. Nötige Rechte: `SELECT`,
  `INSERT`, `UPDATE`, `DELETE` und einmalig `CREATE` für das Anlegen der drei Tabellen.
* Die Tabellen `avaria_positions`, `avaria_applications`, `avaria_contact_messages`
  werden **nur** per `CREATE TABLE IF NOT EXISTS` angelegt — vorhandene Tabellen und
  Daten der Website bleiben unangetastet. Der Knopf dafür steht im Modul selbst.
* Bleibt der Wert leer oder ist die Datenbank offline, zeigen die Module einen Hinweis;
  der Rest von Team OS ist davon **nicht** betroffen.
* Nach dem Eintragen den Server neu starten (Umgebungsvariablen werden beim Start gelesen).
* Rechte: `forms.view` / `forms.manage` für Ausschreibungen und Bewerbungen,
  `contact.view` / `contact.manage` für Kontaktanfragen — getrennt, weil Bewerbungen
  personenbezogene Daten Außenstehender enthalten.

## 2. Datenbank vorbereiten (einmalig)

```bash
npm ci
npx prisma db push          # Schema anlegen (erzeugt auch den Prisma-Client)
npm run db:seed             # Berechtigungen, Rollen + Admin-Konto (aus .env)
```

> Der Seed legt **nur** Berechtigungen, Rollen und **ein** Admin-Konto an — keine Demodaten.
> Das Admin-Passwort wird bei jedem `db:seed` auf den `.env`-Wert gesetzt (Bootstrap).
> Danach kann der Admin im System weitere Nutzer, Teams und Inhalte anlegen.

## 3. Über `screen` starten

```bash
screen -S avaria     # neue Session
./start.sh           # baut (falls nötig) und startet den Server
# Session verlassen ohne zu stoppen:  Strg+A, dann D
```

Wieder anhängen / stoppen:

```bash
screen -r avaria     # anhängen
screen -ls           # laufende Sessions anzeigen
# im Screen: Strg+C beendet den Server
```

`start.sh` liest optional `PORT` (Standard `3000`) und `HOST` (Standard `0.0.0.0`).

> **Bei zerschossenem Layout nach einem Update:** `rm -rf .next && npm run build`.
> Ein abgebrochener Build hinterlässt ein unvollständiges `.next`-Verzeichnis;
> der Server startet dann mit fehlenden Bausteinen, und die Oberfläche wirkt
> zerschossen (Elemente ohne Abstände, fehlende Teile). `start.sh` erkennt das
> inzwischen selbst und baut in dem Fall neu, statt den kaputten Stand zu starten.

## 4. Update einspielen

```bash
git pull                      # bzw. neue Dateien einspielen
npm ci
npx prisma db push            # falls sich das Schema geändert hat
npm run build
# im screen: Server neu starten (Strg+C, dann ./start.sh)
```

## Dateien & Backups

Alle Uploads liegen im Ordner **`storage/`** (Chat-Anhänge, Profil- und Kanalbilder,
Cloud-Speicher unter `storage/cloud/`)
und werden zur Laufzeit über die App ausgeliefert — nicht über `public/`, da Next.js
das `public`-Verzeichnis nur beim Serverstart einliest und später hinzugefügte
Dateien sonst nicht ausgeliefert würden.

- `storage/` in die Datensicherung aufnehmen und bei Updates **nicht** löschen.
- Bestehende Bilder aus früheren Versionen unter `public/uploads/` funktionieren
  weiterhin; sie können bei Bedarf nach `storage/uploads/` verschoben werden.

## Hinweise

- Für HTTPS/öffentlichen Zugriff einen Reverse-Proxy (nginx/Caddy) vor Port 3000 setzen und `AUTH_URL`/`APP_URL` auf die öffentliche URL zeigen lassen.
- Das **Creator-Modul** ist derzeit als „Coming soon" sichtbar; das Backend bleibt vorhanden und kann später ohne Datenmigration reaktiviert werden.