hcrb/DEPLOY.md

# HCRB auf dem eigenen Server betreiben (Docker + Nginx Proxy Manager)

Annahme: ein Linux-Server mit SSH-Zugang und Docker, auf dem der **Nginx Proxy Manager** (NPM) als Container läuft
und die Domains verwaltet. Dazu eine (Sub-)Domain, z. B. `hcrb.dbks.eu`.

Der Ablauf: Code liegt in einem Git-Repository → Server holt ihn per `git pull` → `docker compose` baut und startet
den Container auf Port 3000 → NPM leitet die Domain per HTTPS an `Server-IP:3000`.
Die Daten (`data/`) liegen außerhalb des Containers auf dem Server und bleiben bei Updates erhalten.

## 1. Git-Repository ✓

Erledigt – der Code liegt in https://github.com/guyg1474/hcrb (privat).
`data/`, `.env` und `node_modules/` stehen in `.gitignore` – Passwörter und Mitgliederdaten landen nicht im Repository.

## 2. Domain ✓

`hcrb.dbks.eu` zeigt bereits auf den Server (79.193.32.236) – kein neuer DNS-Eintrag nötig.
Die Hauptdomain `dbks.eu` bleibt für die bestehende Seite.

## 3. Code auf den Server holen (einmalig)

Per SSH auf dem Server. Zugriff auf das private Repository – einen SSH-Schlüssel erzeugen:

```bash
ssh-keygen -t ed25519 -N "" -f ~/.ssh/hcrb_deploy
cat ~/.ssh/hcrb_deploy.pub
```

Den ausgegebenen Schlüssel im Repository unter *Settings → Deploy keys* eintragen (nur Lesezugriff). Dann:

> **Ordner:** Das Projekt liegt in `~/festplatte/dockercontainer/hcrb`. Die Skripte in `deploy/` finden ihren
> Ordner selbst – bei einem Umzug muss nur der Pfad in den Befehlen hier angepasst werden.

```bash
mkdir -p ~/festplatte/dockercontainer
GIT_SSH_COMMAND="ssh -i ~/.ssh/hcrb_deploy" git clone git@github.com:guyg1474/hcrb.git ~/festplatte/dockercontainer/hcrb
cd ~/festplatte/dockercontainer/hcrb
git config core.sshCommand "ssh -i ~/.ssh/hcrb_deploy"
chmod +x deploy/*.sh

# Datenordner – der Container läuft als Benutzer "node" (UID 1000) und muss hier schreiben dürfen
mkdir -p data && sudo chown 1000:1000 data
```

## 4. Port und Server-IP

Der Container ist auf dem Server über **Port 3000** erreichbar. Prüfen, ob der Port noch frei ist
(keine Ausgabe = frei):

```bash
sudo ss -ltnp | grep ':3000 '
```

Ist er belegt, einen anderen freien Port wählen (z. B. 3010) und in die Datei `.env` schreiben:

```bash
cp .env.example .env
nano .env          # HCRB_PORT=3010
```

Lokale IP des Servers herausfinden (die erste Adresse, meist `192.168.…`) – die kommt später in den Proxy Manager:

```bash
hostname -I
```

## 5. Daten übernehmen (optional)

Wer die bisherigen Mitglieder, Termine und Logins mitnehmen will, kopiert sie vom eigenen Rechner:

```bash
# lokal ausführen
scp data/db.json data/users.json DEIN-USER@SERVER:/tmp/
# auf dem Server
sudo mv /tmp/db.json /tmp/users.json ~/festplatte/dockercontainer/hcrb/data/
sudo chown 1000:1000 ~/festplatte/dockercontainer/hcrb/data/*.json && sudo chmod 600 ~/festplatte/dockercontainer/hcrb/data/*.json
```

## 6. Container starten

```bash
cd ~/festplatte/dockercontainer/hcrb
docker compose up -d --build
docker compose ps            # Status sollte nach ca. 30 Sekunden "Up … (healthy)" zeigen
```

Ohne übernommene Daten jetzt den ersten Login anlegen (Passwort wird verdeckt abgefragt):

```bash
docker compose exec hcrb npm run user -- add elias
```

Prüfen, ob die Seite läuft (sollte `{"user":null}` ausgeben – Server-IP und ggf. Port anpassen):

```bash
curl -s http://192.168.178.20:3000/api/me
```

Der Container startet automatisch neu – nach Abstürzen und nach einem Server-Neustart (`restart: unless-stopped`).

## 7. Domain im Nginx Proxy Manager anlegen

In der NPM-Weboberfläche: **Hosts → Proxy Hosts → Add Proxy Host**

Reiter **Details**

| Feld | Wert |
| --- | --- |
| Domain Names | `hcrb.dbks.eu` |
| Scheme | `http` |
| Forward Hostname / IP | lokale IP des Servers aus Schritt 4, z. B. `192.168.178.20` (**nicht** `127.0.0.1`/`localhost` – das wäre der Proxy-Manager-Container selbst) |
| Forward Port | `3000` (bzw. der Port aus `.env`) |
| Cache Assets | aus |
| Block Common Exploits | an |
| Websockets Support | aus (wird nicht gebraucht) |

Reiter **SSL**

| Feld | Wert |
| --- | --- |
| SSL Certificate | Request a new SSL Certificate |
| Force SSL | an |
| HTTP/2 Support | an |
| HSTS Enabled | an |
| E-Mail / Agree to Terms | ausfüllen bzw. anhaken |

Speichern – NPM holt das Zertifikat und verlängert es automatisch. Danach ist die Seite unter
`https://hcrb.dbks.eu` erreichbar.

NPM gibt die echte Besucher-IP und das Protokoll (`X-Forwarded-For`, `X-Forwarded-Proto`) von sich aus weiter –
das braucht die Seite für die Sperre nach 10 falschen Passwörtern und für das sichere Login-Cookie.
Unter *Advanced* muss dafür nichts eingetragen werden.

**Hinweis:** Port 3000 im Router **nicht** freigeben – von außen soll die Seite nur über NPM (Port 443) erreichbar sein.
Im Heimnetz ist sie unter `http://Server-IP:3000` direkt erreichbar, das ist unkritisch.
Die NPM-Oberfläche (Port 81) sollte ebenfalls nicht offen im Internet stehen.

## 8. Backups

```bash
sudo crontab -e
# Zeile hinzufügen:
30 3 * * * /home/DEIN-USER/festplatte/dockercontainer/hcrb/deploy/backup.sh
```

Sichert täglich um 3:30 Uhr `data/` nach `/var/backups/hcrb/` und behält 30 Tage.
Am besten zusätzlich ab und zu eine Sicherung vom Server herunterladen.

---

## Änderungen aufspielen (jedes Mal)

```bash
# lokal
git add .
git commit -m "Was geändert wurde"
git push

# auf dem Server
ssh DEIN-USER@SERVER festplatte/dockercontainer/hcrb/deploy/update-docker.sh
```

`update-docker.sh` holt den neuen Stand, baut den Container neu und startet ihn. Die Daten bleiben unverändert,
an NPM muss nichts geändert werden.

## Nützliche Befehle auf dem Server

Alle im Ordner `~/festplatte/dockercontainer/hcrb` ausführen:

| Zweck | Befehl |
| --- | --- |
| Status | `docker compose ps` |
| Log ansehen | `docker compose logs -f` |
| Neu starten | `docker compose restart` |
| Stoppen / Starten | `docker compose down` / `docker compose up -d` |
| Benutzer anlegen | `docker compose exec hcrb npm run user -- add <name>` |
| Passwort ändern | `docker compose exec hcrb npm run user -- passwd <name>` |
| Benutzer auflisten | `docker compose exec hcrb npm run user -- list` |
| Backup zurückspielen | `docker compose down && sudo tar -xzf /var/backups/hcrb/hcrb-DATUM.tar.gz -C ~/festplatte/dockercontainer/hcrb && sudo chown -R 1000:1000 data && docker compose up -d` |

## Fehlersuche

| Problem | Ursache / Lösung |
| --- | --- |
| `port is already allocated` beim Start | Port belegt – in `.env` einen anderen `HCRB_PORT` setzen (Schritt 4) und in NPM nachziehen. |
| NPM zeigt „502 Bad Gateway“ | Container läuft nicht (`docker compose ps`, `docker compose logs`), oder in NPM steht `127.0.0.1` bzw. ein falscher Port – dort die lokale Server-IP eintragen. |
| Container startet neu mit `EACCES … data` | Rechte am Datenordner: `sudo chown -R 1000:1000 ~/festplatte/dockercontainer/hcrb/data` |
| Nach 10 falschen Passwörtern ist der Login für **alle** gesperrt | Die Seite erkennt die echte Besucher-IP nicht – prüfen, ob `TRUST_PROXY` in `docker-compose.yml` gesetzt ist und der Zugriff über NPM erfolgt. |