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:

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: /pfad/zu/docker ist ein Platzhalter für den Container-Ordner auf dem Server. Die Skripte in deploy/ finden ihren Ordner selbst – bei einem Umzug muss nur der Pfad in den Befehlen hier angepasst werden.

mkdir -p /pfad/zu/docker
GIT_SSH_COMMAND="ssh -i ~/.ssh/hcrb_deploy" git clone git@github.com:guyg1474/hcrb.git /pfad/zu/docker/hcrb
cd /pfad/zu/docker/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):

sudo ss -ltnp | grep ':3000 '

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

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:

hostname -I

5. Daten übernehmen (optional)

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

# 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 /pfad/zu/docker/hcrb/data/
sudo chown 1000:1000 /pfad/zu/docker/hcrb/data/*.json && sudo chmod 600 /pfad/zu/docker/hcrb/data/*.json

6. Container starten

cd /pfad/zu/docker/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):

docker compose exec hcrb npm run user -- add admin admin    # Admin-Zugang
docker compose exec hcrb npm run user -- add hcrb           # gemeinsamer Zugang für alle Mitglieder

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

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

sudo crontab -e
# Zeile hinzufügen:
30 3 * * * /pfad/zu/docker/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)

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

# auf dem Server
ssh DEIN-USER@SERVER /pfad/zu/docker/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 /pfad/zu/docker/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> [admin|mitglied]
Rolle ändern	docker compose exec hcrb npm run user -- role <name> <admin|mitglied>
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 /pfad/zu/docker/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 /pfad/zu/docker/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.