Betrieb

Cloud-Backend deployen

Das Backend läuft als Docker-Compose-Stack auf einem zentralen Server (VPS oder Cloud-Instanz). Ein eigenständiges Deployment ergänzt den gepflegten Traefik-Edge:

cd locker-backend
docker compose \
  -f docker-compose.prod.yml \
  -f docker-compose.prod.traefik.yml \
  up -d

Zuvor APP_DOMAIN, REVERB_DOMAIN, MQTT_DOMAIN und ACME_EMAIL setzen. Öffentlich erreichbar sind HTTPS auf Port 443 und MQTTS auf Port 8883. Mosquitto-Port 1883 bleibt unverschlüsselt im Docker-Netz und wird in Produktion nicht veröffentlicht.

Für Coolify v4 das Git-basierte Docker Compose Build Pack verwenden und Docker Compose Location auf /locker-backend/docker-compose.prod.coolify.yml setzen. Die Datei enthält den Produktions-Stack inline, weil Coolify Compose extends und include nicht auflöst. Coolifys ähnlich benanntes Custom Compose Override konfiguriert die Coolify-Infrastruktur und ist kein Anwendungs-Overlay. Der verwaltete Traefik-Proxy muss einen TCP-Entrypoint mqtts auf Port 8883 veröffentlichen. Coolify legt den Entrypoint nicht aus dem App-Compose an. Unter Servers → dein Server → Proxy → Configuration die bestehenden HTTP/HTTPS-Einträge behalten und Folgendes dazumergen, danach den Proxy neu starten:

ports:
  - "8883:8883"

command:
  - "--entrypoints.mqtts.address=:8883"

Kein 1883:1883 in der Coolify-Port-UI. Setzt Coolify die Proxy-Config zurück, den Schritt wiederholen. Der Adapter routet HostSNI(*) über diesen Entrypoint zu Mosquitto-Port 1883. Coolify interpoliert ${VAR} in Compose-Labels nicht.

Die vollständigen Anleitungen für Standalone und Coolify einschließlich Firewall, DNS, Zertifikaten und Smoke Tests stehen im Installationsleitfaden.

Image-Version pinnen

Für Beta- und Produktions-Deployments das Image in locker-backend/.env auf einen unveränderlichen Release-Tag pinnen; latest nicht deployen:

BACKEND_IMAGE_TAG=backend-v1.0.0-beta.1

docker compose \
  -f docker-compose.prod.yml \
  -f docker-compose.prod.traefik.yml \
  pull
docker compose \
  -f docker-compose.prod.yml \
  -f docker-compose.prod.traefik.yml \
  up -d --force-recreate

Die laufende Version ist über GET /api/identify als version abfragbar.

MQTT-Authentifizierung

Der Mosquitto-Broker authentifiziert Clients gegen die Laravel-API (mosquitto-go-auth). Die Konfiguration wird aus dem Template erzeugt:

just setup-mqtt

Ohne just: mosquitto.conf aus dem Beispiel kopieren und in den Webhook-URIs mosq_secret=<MOSQ_HTTP_PASS> eintragen, dann den Mosquitto-Container neu starten.

Locker Clients verwenden mqtts://<mqtt-domain>:8883 und prüfen öffentliches Zertifikat und Hostnamen. Vor der Abnahme einen authentifizierten MQTT-Roundtrip über Port 8883 testen und bestätigen, dass Port 1883 von außerhalb des Docker-Hosts nicht erreichbar ist.

Auf allen Backend-Instanzen muss derselbe gültige Laravel-APP_KEY gesetzt sein. Das Backend leitet daraus einen domain-separierten HMAC-Subkey für Provisionierungs-Tokens ab; ein zusätzliches Provisionierungsgeheimnis ist nicht erforderlich. Eine APP_KEY-Rotation invalidiert offene, noch nicht verbrauchte Provisionierungs-Tokens, für die anschließend neue Tokens ausgestellt werden müssen. Bereits provisionierte Geräte verwenden ihre MQTT-Zugangsdaten weiter.

Admin-Benutzer anlegen

Vor dem ersten Deployment ADMIN_EMAIL setzen oder ausführen:

docker compose exec app php artisan first-admin:create admin@example.com

Der Mailversand muss funktionieren, damit der Admin ein Passwort setzen kann. Das Admin-Panel ist unter https://<deine-domain>/admin erreichbar.

Monitoring

• Health-Endpoint: GET /up (Laravel)
• MQTT-Listener: meldet Liveness per Heartbeat im Cache; php artisan mqtt:health ist der Docker-Healthcheck des mqtt-listener-Containers. Ein autoheal-Sidecar startet unhealthy Container automatisch neu. Hinweis: autoheal nutzt die Docker-Restart-API — Restarts erscheinen in den autoheal-Logs, nicht im RestartCount.
• Offline-Erkennung: Der Scheduler führt php artisan locker:detect-offline jede Minute aus

Locker Client am Standort

Der Locker Client läuft als Docker-Container auf einem Raspberry Pi (3/4/5 oder Zero 2 W, Raspberry Pi OS Lite 64-bit):

• Image: einen unveränderlichen Release pinnen, zum Beispiel ghcr.io/open-locker/locker-client:client-v1.0.0-beta.1
• Benötigt config/locker-config.yml und eine .env mit PROVISIONING_TOKEN
• Verbindet sich per MQTT mit dem Backend und steuert Waveshare-Relais-Boards über serialisiertes Modbus RTU

Die Provisionierung im Admin-Panel ausstellen oder neu starten, das Token aus dem einmaligen Dialog direkt in die .env des Clients kopieren und den Client neu starten. Das Token kann nicht erneut angezeigt werden; bei Verlust muss ein neues ausgestellt werden. Persistierte Identität, Zugangsdaten, Runtime-Konfiguration oder Deduplizierungszustand nicht als routinemäßige Wiederherstellungsmaßnahme löschen.

Empfohlene Hardware: siehe Stückliste.

Hosting-Optionen

• Self-Hosting: alles selbst betreiben — volle Kontrolle, keine Softwarekosten
• Gehostetes Backend: wer nicht selbst hosten möchte, kann das zentrale Backend hosten lassen — siehe Angebot auf der Website