Zum Inhalt

SNLO – Spittank.net Ladeorganisation 0.5.12 – Schnellstart

1. Voraussetzungen

  • Docker Engine und Docker Compose v2
  • mindestens eine funktionierende EVCC-Instanz
  • Netzwerkzugriff der Container auf alle konfigurierten EVCC-Instanzen
  • optional bidirektionaler Netzwerkzugriff zur KEBA P30; Docker muss auf Linux laufen und der Host muss UDP 7090 exklusiv senden/empfangen können
  • optional ein OIDC-Provider mit zwei Gruppen für Nutzer und Administratoren

Die Anzahl der EVCC-Instanzen ist nicht begrenzt. Jede EVCC-Instanz bleibt für ihre eigene Site, PV, Batterie und Wallbox zuständig.

2. Konfiguration erzeugen

cd snlo-0.5.12
python3 scripts/init-env.py

Das Skript erzeugt .env mit Dateimodus 0600, Datenbankpasswort, Verschlüsselungsschlüssel und einmaligem Bootstrap-Passwort.

Für HTTPS hinter einem Reverse Proxy:

APP_ORIGIN=https://snlo.de
COOKIE_SECURE=true

3. Optional: OIDC aktivieren

Im Identity Provider einen vertraulichen OIDC-Webclient mit folgender Redirect-URI anlegen:

https://snlo.de/api/auth/oidc/callback

Mindestens folgende Werte in .env setzen:

OIDC_ENABLED=true
OIDC_ISSUER_URL=https://sso.example.org/realms/home
OIDC_CLIENT_ID=snlo
OIDC_CLIENT_SECRET=...
OIDC_GROUPS_CLAIM=groups
OIDC_USER_GROUPS=snlo-users
OIDC_ADMIN_GROUPS=snlo-admins
OIDC_AUTO_REDIRECT=true
OIDC_LOCAL_LOGIN_ENABLED=true

Mitgliedschaft in der Administratorgruppe hat Vorrang. Konten ohne eine erlaubte Gruppe werden abgewiesen. Bei Direktweiterleitung bleibt der lokale Login unter /?local=1 erreichbar, solange OIDC_LOCAL_LOGIN_ENABLED=true gesetzt ist.

Details und alternative Claim-Pfade: OIDC.md

4. Start beziehungsweise Update

Bei einem Update einer bereits laufenden Installation zuerst den vorhandenen Datenvolume-Namen ermitteln und in der bestehenden .env festhalten:

docker volume ls --format '{{.Name}}' | grep 'postgres-data'

POSTGRES_VOLUME_NAME=<bestehender-volume-name>

Bei einer Neuinstallation ist bereits POSTGRES_VOLUME_NAME=snlo-postgres-data gesetzt. Für einen lokalen Build gelten standardmäßig:

SNLO_IMAGE=snlo:local
SNLO_PULL_POLICY=build

Danach starten:

docker compose up -d

Alternativ kann ein Forgejo-Registry-Release verwendet werden:

SNLO_IMAGE=dev.spittank.org/daniel/snlo:0.5.12
SNLO_PULL_POLICY=always

docker compose pull migrate api worker
docker compose up -d

Status:

docker compose ps
docker compose logs -f migrate api worker

Standardadresse: http://<docker-host>:8080. Auf TrueNAS den Reverse Proxy immer auf die feste TrueNAS-Host-IP und Port 8080 richten, nicht auf die interne API-Container-IP.

Beim Update führt migrate zuerst alle Alembic-Migrationen aus. Vor jedem Update wird ein Datenbankdump empfohlen.

5. Erste Anmeldung

Ohne OIDC:

  • E-Mail: Wert aus BOOTSTRAP_ADMIN_EMAIL, standardmäßig admin@example.com
  • Passwort: Ausgabe von scripts/init-env.py

Mit OIDC über die konfigurierte Administratorgruppe anmelden. Der Bootstrap-Administrator bleibt als lokaler Notzugang verfügbar, solange der lokale Login aktiviert ist. Sein Passwort nach der ersten Anmeldung ändern.

6. EVCC-Instanzen

Unter Administration -> EVCC-Instanzen:

  1. Namen vergeben.
  2. Basis-URL ohne /api eintragen.
  3. EVCC-API-Key optional hinterlegen.
  4. Verbindung testen.
  5. Vollständig synchronisieren.

Instanzen können später bearbeitet oder gelöscht werden. Existieren Sitzungen, verlangt die Löschung eine zweite, ausdrückliche Bestätigung zur Entfernung der Historie.

7. Nutzer und Fahrzeuge

  1. Nutzer lokal anlegen oder durch OIDC automatisch anlegen lassen.
  2. Internes Fahrzeug anlegen.
  3. Unter EVCC verknüpfen alle passenden EVCC-Fahrzeuge verbinden.
  4. Nutzer zuweisen öffnen.
  5. alle berechtigten Familienmitglieder mit Zeitraum hinzufügen.
  6. genau eine Zuweisung je Zeitraum als Zahlender Nutzer markieren.

Für vorhandene historische Sitzungen empfiehlt sich beim ersten Zuordnen:

Gültig ab: 01.01.1970
Historische Sitzungen neu zuordnen: aktiviert

SNLO gleicht EVCC-Sitzungen sowohl über den internen Fahrzeugnamen als auch über den sichtbaren EVCC-Titel ab.

8. Tarife

Unter Administration -> Tarife benannte Tarife anlegen, zum Beispiel Privat und Privat Plus.

Jeder Tarif enthält:

  • allgemeinen Aufschlag,
  • Solaraufschlag,
  • Netzbezugsaufschlag,
  • Batterieaufschlag,
  • je Komponente die Darstellung Aufschlag oder in Stromkosten eingerechnet.

Danach:

  • globale Standardzeiträume im unteren Bereich der Tarifverwaltung zuordnen,
  • nutzerbezogene Zeiträume unter Administration -> Nutzer -> Einstellungen zuordnen.

Beispiel:

Alfred | 01.01.1970 bis einschließlich 31.03.2026 | Privat
Alfred | ab 01.04.2026                            | Privat Plus

Wird ein bereits verwendeter Tarif bearbeitet, zeigt die UI eine Warnung. Nach Bestätigung werden alle mit diesem Tarif verknüpften Sitzungen neu berechnet.

9. Optionale KEBA-Freigabe

Unter Administration -> KEBA / RFID:

  1. EVCC-Ladepunkt auswählen.
  2. KEBA-IP und UDP-Port eintragen.
  3. Verbindung mit Testen prüfen.
  4. Beim Nutzer unter Einstellungen -> RFID-Keys die 8-stellige RFID-UID aus der KEBA-Kartenliste hinterlegen. Sie wird unverändert wie in der Home-Assistant-Integration gesendet; der benötigte RFID-Class-Wert wird intern ergänzt. 16-stellige UDP-Tags aus historischen Reports werden weiterhin akzeptiert.

compose.yaml startet dafür keba-gateway im Linux-Hostnetz und hält dort dauerhaft UDP 7090 offen. Bei rootful Docker Engine unter Linux entfällt damit die Docker-Bridge-NAT-Stufe. Ein parallel auf demselben Host laufender KEBA-UDP-Listener auf Port 7090 verursacht einen Portkonflikt. Bei einem Upgrade von 0.5.5 oder älter zusätzlich KEBA_GATEWAY_TOKEN=$(openssl rand -hex 32) in .env eintragen.

Bei Problemen zuerst docker compose logs -f keba-gateway beobachten. Eine erfolgreiche Antwort erzeugt eine Zeile KEBA UDP RX. Fehlt diese trotz sichtbarer Wallbox-Antwort im Netz, siehe die Netzwerkdiagnose unter Konfiguration.

Der Nutzer erhält unter Ladevorgang die Schaltfläche Mit RFID freigeben. Der Key wird serverseitig entschlüsselt und nicht an den Browser zurückgegeben.

10. Nutzer- und Adminansichten

Nutzer können im Dashboard und in der Sitzungsliste Nur selbst bezahlte Fahrzeuge aktivieren. Ohne Filter sehen sie zusätzlich Sitzungen aller Fahrzeuge, denen sie zum Sitzungszeitpunkt zugeordnet waren.

Administratoren können im Dashboard einen zahlenden Nutzer auswählen. In Administration -> Nutzer öffnet Druckansicht dieselbe zahlungsbezogene Kostenübersicht für den gewählten Nutzer.

CSV ist ausschließlich Administratoren verfügbar.

11. Backup und Diagnose

docker compose exec -T db sh -c 'pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB"' > snlo-$(date +%F).sql
docker compose logs --tail=300 api
docker compose logs --tail=300 worker
docker compose logs --tail=300 migrate
curl http://localhost:8080/healthz

.env gemeinsam mit der Datenbank sichern. Ohne CREDENTIAL_ENCRYPTION_KEY sind EVCC-/KEBA-Geheimnisse und RFID-Keys nach einem Restore nicht entschlüsselbar. Das OIDC-Client-Secret befindet sich ausschließlich in .env beziehungsweise der Containerumgebung.

Weiterführende Dokumentation