# EK-DOS-WEB betreiben

Zielsystem: Debian/Ubuntu mit nginx und php8.5-fpm. Postgres und Redis laufen
bereits für n8n und werden mitbenutzt (eigene Datenbank, eigene Redis-Nummer).

## 1. Pakete

```bash
sudo apt update
sudo apt install -y nginx php8.5-fpm php8.5-cli php8.5-pgsql php8.5-redis \
                    php8.5-mbstring php8.5-curl php8.5-intl php8.5-xml
```

`php8.5-intl` ist optional, verbessert aber die Erkennung der Kundenrücksprache
in Ticketberichten (Unicode-Normalisierung). Ohne die Erweiterung greift ein
Rückfall ohne Normalisierung.

## 2. Datenbank und Redis

```bash
sudo -u postgres createuser ekdos --pwprompt
sudo -u postgres createdb ekdos --owner=ekdos
```

Redis braucht nichts weiter -- EK-DOS legt seine Schlüssel unter dem Präfix
`ekdos:` ab und nutzt eine eigene Datenbanknummer (`REDIS_DB`).

> Redis hält Sitzungen **und** den n8n-Cache. Ist Redis weg, ist niemand mehr
> angemeldet und jede Ansicht fragt wieder direkt bei n8n an. Die Anwendung
> läuft weiter, aber langsamer und mit erneuter Anmeldung.

## 3. Verzeichnisse

```bash
sudo mkdir -p /var/www/ekdos/{releases,backend}
sudo useradd --system --home /var/www/ekdos --shell /usr/sbin/nologin ekdos
sudo chown -R ekdos:ekdos /var/www/ekdos
sudo mkdir -p /var/log/php && sudo chown ekdos:ekdos /var/log/php
```

## 4. Backend einrichten

```bash
cd /var/www/ekdos/backend
sudo -u ekdos cp .env.example .env
sudo -u ekdos editor .env
sudo -u ekdos composer install --no-dev --optimize-autoloader
sudo -u ekdos php bin/ekdos migrate
sudo -u ekdos php bin/ekdos user:create     # erster Administrator
sudo -u ekdos php bin/ekdos check
```

`.env` gehört dem Benutzer `ekdos` und sollte `chmod 600` sein. Sie wird beim
Ausrollen ausdrücklich nicht überschrieben.

### n8n-Adressen

| Einstellung         | Wert                              | warum                                                       |
| ------------------- | --------------------------------- | ----------------------------------------------------------- |
| `N8N_PUBLIC_BASE`   | `https://n8n.elektro-krueger.eu`  | Der Dienst auf Port 5678 ist nur über den CNAME erreichbar   |
| `N8N_INTERNAL_HOST` | `10.0.11.131`                     | Jeder weitere n8n-Dienst auf einem anderen Port              |

Alle heutigen `ek-dos-web`-Webhooks laufen über den 5678-Dienst und damit über
`N8N_PUBLIC_BASE`. Kommt später ein zweiter n8n-Dienst auf eigenem Port dazu,
wird er mit `Endpoints::internal(<port>, '<pfad>')` angesprochen und geht über
die RFC1918-Adresse -- er ist nach aussen nicht veröffentlicht.

## 5. php-fpm

```bash
sudo cp deploy/php-fpm/ekdos.pool.conf /etc/php/8.5/fpm/pool.d/ekdos.conf
sudo php-fpm8.5 -t
sudo systemctl restart php8.5-fpm
ls -l /run/php/ekdos.sock      # muss www-data:www-data 0660 gehören
```

Der Pool setzt `opcache.validate_timestamps = 0`. Neuer Quelltext wird deshalb
**erst nach einem `systemctl reload php8.5-fpm`** wirksam -- die Ausrollstrecke
macht das selbst.

## 6. nginx

```bash
sudo cp deploy/nginx/ekdos.conf /etc/nginx/sites-available/ekdos.conf
sudo ln -sf /etc/nginx/sites-available/ekdos.conf /etc/nginx/sites-enabled/
sudo nginx -t && sudo systemctl reload nginx
```

Kurzfassung: `fastcgi_pass unix:/run/php/ekdos.sock` für `/api/`, alles andere
`try_files $uri $uri/ /index.html`. Kein Anwendungsserver, kein Reverse Proxy
auf einen Node-Prozess.

Läuft der Zugriff nur intern über HTTP, kann `SESSION_COOKIE_SECURE=false`
gesetzt und der 443-Block entfernt werden. Sobald TLS anliegt: wieder auf `true`.

## 7. Ausrollen

Die Gitea-Strecke (`.gitea/workflows/build.yml`) macht das bei jedem Push auf
`main`. Nötig sind:

- ein SSH-Schlüssel als Gitea-Secret `DEPLOY_SSH_KEY`
- ein Konto `deploy` auf dem Server, das nach `/var/www/ekdos` schreiben darf
- `sudo systemctl reload php8.5-fpm` ohne Passwort für dieses Konto

```
deploy ALL=(root) NOPASSWD: /bin/systemctl reload php8.5-fpm
```

Jede Veröffentlichung landet unter `releases/<sha>`; sichtbar wird sie erst
durch den Symlink-Tausch von `current`. Die letzten fünf bleiben liegen, ein
Rückschritt ist damit ein `ln -sfn`.

### Von Hand

```bash
cd frontend && pnpm install --frozen-lockfile && pnpm build
rsync -az --delete frontend/dist/ server:/var/www/ekdos/releases/manuell/
ssh server 'cd /var/www/ekdos && ln -sfn releases/manuell current && sudo systemctl reload php8.5-fpm'
```

## Prüfen, wenn etwas klemmt

```bash
php backend/bin/ekdos check            # Postgres, Redis, n8n
curl -sS https://<host>/api/health     # ohne Anmeldung erreichbar
tail -f /var/log/php/ekdos-error.log   # Ausnahmen aus dem Backend
tail -f /var/log/nginx/ekdos.error.log
```

| Symptom                                     | meistens                                                              |
| ------------------------------------------- | --------------------------------------------------------------------- |
| 502 auf `/api/`                             | Socket fehlt oder falsche Rechte; `systemctl status php8.5-fpm`        |
| Anmeldung wirkt, danach sofort abgemeldet   | Redis nicht erreichbar, oder `SESSION_COOKIE_SECURE=true` ohne TLS     |
| Listen bleiben leer, Meldung „nicht erreichbar" | `N8N_PUBLIC_BASE` falsch, oder der Webhook ist in n8n nicht aktiv  |
| Angezeigte Daten sind veraltet              | Rückfall-Cache greift, weil n8n gerade nicht antwortet                 |
| 503 „noch nicht eingerichtet"               | `N8N_INVOICE_SYNC_SECRET` bzw. `N8N_CUSTOMER_KEY` fehlt in `.env`      |
| Quelltextänderung wirkt nicht               | Opcache; `systemctl reload php8.5-fpm`                                 |

## Alle Benutzer aussperren

```bash
redis-cli --scan --pattern 'ekdos:sess:*' | xargs -r redis-cli del
```

Danach muss sich jeder neu anmelden. Einzelne Konten trifft es gezielt über die
Benutzerverwaltung (Deaktivieren beendet die offenen Sitzungen sofort).