Server installieren

Zum Ausprobieren

Die Entwicklungsumgebung bringt den Simulator und einen Mail-Fänger mit. Nichts verlässt den Rechner.

Auch in der Entwicklung geht nichts im Klartext über ein Netz. Ohne TLS gibt es nur Ports auf 127.0.0.1. Was vom Handy oder einem zweiten Rechner aus erreichbar ist, spricht HTTPS mit dem Zertifikat der eigenen CA. Damit der Browser nicht warnt, das CA-Zertifikat einmal importieren (System → Status → „CA-Zertifikat herunterladen“).

dev.bat hat ein Menü: starten, stoppen, neu starten, aktualisieren, Status, Protokoll, Sicherung anlegen und zurückspielen, alles zurücksetzen, Prüfungen. Jeder Punkt geht auch direkt, zum Beispiel dev.bat logs.

Im Homelab

Zwei Wege führen zum laufenden Server. Option A ist die einfache Installation auf einem Rechner, auf dem Docker schon läuft. Option B ist die vollständige Anleitung für einen eigenen Server, etwa einen LXC-Container unter Debian 13: SmartBeet läuft unter einem eigenen Benutzer deploy ohne root-Rechte, und auf Wunsch spielt ein GitHub-Runner jeden Push auf main von selbst ein.

Option A: einfache Installation

Fehlt Docker, steht die Installation unter Option B im ersten Schritt.

Option B: Debian 13 mit Benutzer deploy

Das System richtest du als root ein (Pakete, Docker). Alles, was SmartBeet selbst betrifft (klonen, einstellen, bauen, starten), läuft unter dem Benutzer deploy, der später auch das automatische Aktualisieren ausführt. Die Schritte sind mit [root] und [deploy] markiert. Wechsel mit su - deploy, zurück mit exit. deploy hat kein Passwort, keinen SSH-Zugang und ruft nie sudo auf.

In einem LXC-Container (etwa unter Proxmox) braucht Docker die Optionen nesting=1 und keyctl=1. Richtwert für die Größe: 2 Kerne, 4 GB RAM (oder 2 GB mit Swap), 40 GB Platte. Das erste Bauen ist der anspruchsvollste Teil.

HTTPS und Reverse-Proxy

SmartBeet ist immer verschlüsselt erreichbar, auch ohne eigenen Proxy. Der Container frontend ist zugleich der TLS-Endpunkt.

Das Zertifikat stammt von der eigenen CA der Installation. Der Dienst certs legt sie beim ersten Start an und erneuert das Serverzertifikat 30 Tage vor dem Ablauf selbst. Browser warnen, bis das CA-Zertifikat importiert ist (System → Status → „CA-Zertifikat herunterladen“). Hubs brauchen das nicht: Sie erkennen die CA am Server-Schlüssel im Einrichtungscode.

Die Hubs gehen nie über einen eigenen Proxy, sondern immer direkt an Port 8443 und 8883 des Stacks. Der Proxy ist nur dafür da, dass Menschen die Oberfläche von außen erreichen.

Mit eigenem Proxy. Er nimmt HTTPS entgegen und leitet an SmartBeet weiter.

Dabei beachten:

• Auch zwischen Proxy und Stack liegt ein Netz. Steht der Proxy auf einem anderen Rechner, leitet er an die HTTPS-Ports weiter und prüft das Zertifikat mit dem CA-Zertifikat des Stacks. Bei nginx:

  proxy_pass https://192.168.1.10:8443;
  proxy_ssl_trusted_certificate /etc/nginx/smartbeet-ca.crt;
  proxy_ssl_verify on;
  proxy_ssl_name smartbeet-server;
  

  http:// zum Stack nur, wenn Proxy und SmartBeet auf demselben Rechner laufen.

• WebSocket durchreichen (Upgrade, Connection) und lange Verbindungen erlauben, sonst aktualisiert sich die Übersicht nicht live. Für Push ebenso.

• Uploads bis 32 MB erlauben (Firmware), bei nginx client_max_body_size 32m.

• Die Kopfzeilen Host, X-Forwarded-For und X-Forwarded-Proto setzen.

• In der .env die Adressen so eintragen, wie man sie von außen sieht, und SmartBeet neu starten (./deploy.sh → „Neu starten“):

  APP_URL=https://beet.example.org
  NTFY_PUBLIC_URL=https://push.beet.example.org
  

  Mit https:// in APP_URL markiert SmartBeet seine Cookies als „secure“.

Ohne eigenen Proxy, mit eigener Domain. Der mitgelieferte HTTPS-Vorbau, Caddy mit Let’s Encrypt. In der .env:

COMPOSE_PROFILES=caddy
PUBLIC_DOMAIN=beet.example.org
PUSH_DOMAIN=push.beet.example.org
APP_URL=https://beet.example.org
NTFY_PUBLIC_URL=https://push.beet.example.org

Port 80 und 443 müssen aus dem Internet auf den Server zeigen. Caddy holt und erneuert das Zertifikat selbst. Danach docker compose up -d --build.

Ohne Proxy und ohne Domain. https://<server>:8443 öffnen (eigene CA, siehe oben) und APP_URL so eintragen.

Bedienen und aktualisieren

deploy.sh im Verzeichnis von SmartBeet hat ein Menü für alles, was auf dem Server anfällt:

cd /opt/smartbeet
./deploy.sh

Gebaut wird vor dem Neustart: Schlägt das Bauen fehl, läuft die bisherige Anlage weiter.

Automatisch aktualisieren

Push auf main, und der Server aktualisiert sich selbst. Dafür läuft auf dem Server ein selbst gehosteter GitHub-Actions-Runner unter dem Benutzer deploy. Bei jedem Push führt er git reset --hard origin/main und ./deploy.sh rebuild aus. Der Ablauf liegt im Repository als .github/workflows/deploy.yml und startet nur bei einem Push auf main, nie bei Pull Requests: Fremder Code läuft so nie auf deinem Server.

Alle Daten liegen in Docker-Volumes und überstehen jedes Aktualisieren. Die .env steht in .gitignore, git reset --hard lässt sie in Ruhe. Dateien aus dem Repository auf dem Server nicht von Hand ändern, sie werden beim nächsten Lauf überschrieben. Ein Push kann keine Daten löschen; Zurücksetzen geht nur von Hand mit ./deploy.sh reset.

Die drei Adressen

Die Einträge unter „Nur Entwicklung“ braucht der Betrieb nicht. INTERNAL_URL und MQTT_PORT sind entfallen: Hubs laden ihre Firmware über HTTPS, und einen Broker ohne TLS gibt es nach außen nicht mehr. Stehen sie noch in einer älteren .env, nennt das Backend sie beim Start und ignoriert sie.

Geheimnisse

Passwörter für Datenbank und Broker und der Sitzungsschlüssel entstehen beim ersten Start von selbst und liegen in einem eigenen Volume, die eigene CA und das Serverzertifikat in einem zweiten. Es gibt keine Standardpasswörter.

Einrichtungsassistent

Offene Ports

Mit Caddy kommen 80 und 443 dazu. Oberfläche (8080) und ntfy (8090) ohne TLS hören nur auf 127.0.0.1. Datenbank, Broker (1883) und Backend sind nur innerhalb von Docker erreichbar.

Jeder Hub hat eigene Zugangsdaten und darf nur seine eigenen Topics lesen und schreiben. Sonst geht nichts im Klartext über ein Netz, auch nicht im Heimnetz. Die Ausnahmen nennt die README des Projekts: Container untereinander im Docker-Netz, Ports auf 127.0.0.1, der CAN-Bus und die offenen Einrichtungs-WLANs von Hub und Anzeige (WLAN).

Server an einem anderen Ort. Im Router dort Port 8443 und 8883 (TCP) auf den Server weiterleiten, SERVER_HOST auf den öffentlichen Namen oder die IP setzen und beim Hub diese Server-Adresse eintragen.

Damit der Hub den Server findet

Unter Linux kündigt ein kleiner Dienst den Server per mDNS im Heimnetz an, mit dem HTTPS-Port. Dafür braucht er Host-Netzwerk.

Unter Docker Desktop auf Windows und macOS erreicht mDNS das Heimnetz nicht. Der Hub sucht dann selbst das eigene Netz nach einem offenen Port 8443 oder 443 ab. Jeden Kandidaten prüft er über HTTPS: Er nimmt das CA-Zertifikat nur, wenn es zum Server-Schlüssel im Einrichtungscode passt. Das klappt überall, wo der Hub den Server erreicht, dauert aber bis etwa drei Minuten.

Liegt der Server in einem anderen Netz, wird seine Adresse im Einrichtungs-WLAN des Hubs eingetragen. Hat der Server mehrere Netze, legt ANNOUNCE_IP fest, welche Adresse angekündigt wird.

Ohne root

Kein Dienst läuft als root. Jeder Container hat einen festen, unprivilegierten Benutzer.

Wer von einem älteren Stand kommt, setzt einmal die Besitzer der Volumes, bei gestoppter Anlage:

docker compose stop
sh infra/scripts/fix-permissions.sh
docker compose up --build -d

Aktualisieren und sichern

./deploy.sh update           # oder: git pull && docker compose up --build -d
./deploy.sh backup           # legt backups/smartbeet-<Zeit>.tar.gz an

Die Datenbank migriert beim Start von selbst. Sicherung und Wiederherstellung stehen unter Updates und Sicherung.