hps-thunderbird-templates/web-editor/README.md

# HPS Vorlagen & Signaturen – Web-Editor

Ein kleiner, in Docker laufender Web-Editor zum Pflegen der **E-Mail-Vorlagen** und
**Signaturen** für das Hotel Park Soltau. Er ist das Web-Gegenstück zum Thunderbird-Plugin
**„HPS Vorlagen & Signaturen“** und teilt sich mit ihm dieselbe **Gitea/Forgejo-Repository**
als gemeinsame Quelle der Wahrheit.

---

## Was kann der Editor?

- **Vorlagen für alle Abteilungen** verwalten – gemeinsame Vorlagen (`_gemeinsam/`),
  Abteilungsvorlagen (z. B. `Rezeption/`, `IT/`) und persönliche Vorlagen pro Benutzer
  (`_benutzer/<email>/`).
- **Fußzeilen** pflegen – pro Abteilung (`signatures/footers/<Abteilung>.html`) sowie eine
  gemeinsame Standard-Fußzeile (`signatures/footers/_default.html`).
- **Signatur-Köpfe** bearbeiten (`signatures/headers/<email>.<name-slug>.html`).
- **WYSIWYG-Bearbeitung**, Umschalten auf den **HTML-Quelltext** und eine **Live-Vorschau**.
- Jede Änderung wird **direkt als Commit ins Gitea-Repo** geschrieben.

Der Editor ist eine kleine **Node.js/Express-App** (`server.js`), die ein statisches Frontend
aus `public/` ausliefert und die **Gitea Contents API** weiterreicht. Der **Gitea-Token bleibt
serverseitig** und ist für den Browser nicht sichtbar. Konfiguriert wird ausschließlich über
**Umgebungsvariablen**.

---

## Voraussetzungen

- **Docker** mit **docker compose** – *oder* **Node.js ≥ 18**, falls ohne Docker betrieben.
- Ein **Gitea/Forgejo-API-Token mit Schreibrechten** auf das Vorlagen-Repository
  (siehe [Gitea-API-Token erstellen](#gitea-api-token-erstellen)).

---

## Schnellstart mit docker compose

```bash
# 1. Vorlage kopieren und ausfüllen
cp .env.example .env
nano .env          # GITEA_URL, GITEA_OWNER, GITEA_REPO, GITEA_TOKEN eintragen

# 2. Bauen und starten
docker compose up -d --build
```

Anschließend den Editor im Browser öffnen:

```
http://localhost:8080
```

Den Host-Port kannst du über `HOST_PORT` in der `.env` ändern (Standard `8080`).
docker compose mappt `${HOST_PORT:-8080}:3000`.

Logs ansehen bzw. Editor stoppen:

```bash
docker compose logs -f
docker compose down
```

---

## Alternative: plain `docker build` / `docker run`

```bash
# Image bauen
docker build -t hps-vorlagen-web-editor .

# Container starten (Umgebung aus .env, Port 8080 → 3000)
docker run -d \
  --name hps-web-editor \
  --restart unless-stopped \
  -p 8080:3000 \
  --env-file .env \
  hps-vorlagen-web-editor
```

---

## Alternative: lokal ohne Docker

```bash
# Abhängigkeiten installieren
npm install

# Umgebungsvariablen setzen (Beispiel)
export GITEA_URL="https://git.example.com"
export GITEA_OWNER="organisation"
export GITEA_REPO="email-vorlagen"
export GITEA_BRANCH="main"
export GITEA_TOKEN="dein-api-token"

# Starten
npm start
```

Der Editor läuft dann auf dem in `PORT` eingestellten Port (Standard `3000`),
also unter `http://localhost:3000`.

---

## Umgebungsvariablen

| Name                  | Pflicht | Standard       | Beschreibung                                                                 |
| --------------------- | :-----: | -------------- | --------------------------------------------------------------------------- |
| `GITEA_URL`           | **ja**  | –              | Basis-URL des Gitea/Forgejo-Servers, ohne abschließenden Slash.             |
| `GITEA_OWNER`         | **ja**  | –              | Besitzer des Repos (Organisation oder Benutzer).                            |
| `GITEA_REPO`          | **ja**  | –              | Name des Vorlagen-Repositories.                                             |
| `GITEA_BRANCH`        | nein    | `main`         | Branch, in den committet wird.                                              |
| `GITEA_TOKEN`         | **ja**  | –              | API-Token mit Schreibrechten auf das Repository. Bleibt serverseitig.       |
| `COMMIT_AUTHOR_NAME`  | nein    | `Web-Editor`   | Name, mit dem Änderungen committet werden.                                  |
| `COMMIT_AUTHOR_EMAIL` | nein    | –              | E-Mail-Adresse des Commit-Autors.                                           |
| `BASIC_AUTH_USER`     | nein    | –              | Benutzername für HTTP-Basic-Auth (siehe [Sicherheit](#sicherheit)).         |
| `BASIC_AUTH_PASS`     | nein    | –              | Passwort für HTTP-Basic-Auth. Schutz aktiv, wenn beide Werte gesetzt sind.  |
| `PORT`                | nein    | `3000`         | Port, auf dem die App im Container/Prozess lauscht.                         |
| `HOST_PORT`           | nein    | `8080`         | Nur für docker compose: Port, unter dem der Editor am Host erreichbar ist.  |

Eine fertige Vorlage findest du in [`.env.example`](.env.example) – einfach kopieren
und ausfüllen.

---

## Gitea-API-Token erstellen

1. In Gitea/Forgejo oben rechts auf das Profilbild → **Einstellungen**.
2. Reiter **Anwendungen** öffnen.
3. Unter **Token verwalten** einen neuen Token **generieren**.
4. Als **Scope** mindestens **Schreibrechte auf Repositories** (`repo` bzw. `write:repository`)
   vergeben.
5. Den angezeigten Token **sofort kopieren** (er wird nur einmal angezeigt) und als
   `GITEA_TOKEN` in die `.env` eintragen.

---

## Sicherheit

- **Wenn der Editor öffentlich erreichbar ist, unbedingt `BASIC_AUTH_USER` und
  `BASIC_AUTH_PASS` setzen.** Sind beide gesetzt, ist der gesamte Editor per
  HTTP-Basic-Auth geschützt.
- Die **`.env` niemals committen** – sie enthält den Gitea-Token. Sie steht bereits in der
  `.gitignore` und bleibt damit außerhalb der Versionskontrolle.

---

## Hinweis zum Zusammenspiel mit dem Thunderbird-Plugin

Jede im Editor gespeicherte Änderung landet **sofort als Commit im Gitea-Repo**. Das
Thunderbird-Plugin **„HPS Vorlagen & Signaturen“** nutzt dasselbe Repo als Quelle der Wahrheit
und übernimmt die Änderungen automatisch beim nächsten **Sync** (alle paar Sekunden bis
spätestens alle 15 Minuten). Ein manueller Export ist nicht nötig.