homelab-infra/apps/dawarich/README.md

Dawarich Stack

Produktionsvorlage fuer Dawarich im KalliLab-Homelab mit GitOps ueber Gitea und Komodo.

Gepruefter Stand

• Dawarich Release: 1.8.1 (GitHub latest am 2026-06-11)
• Docker Image: freikin/dawarich:1.8.1
• Hinweis: freika/dawarich existiert auf Docker Hub nicht; das offizielle Image aus dem Upstream-Compose ist freikin/dawarich.
• Dawarich Tracking-Endpoint fuer OwnTracks: /api/v1/owntracks/points?api_key=<api-key>
• Dawarich Prometheus ab 1.7.7: Web-Service /metrics; Port 9394 ist intern fuer Sidekiq-Metriken.

Quellen:

• https://github.com/Freika/dawarich/releases/tag/1.8.1
• https://dawarich.app/docs/getting-started/track-your-location/
• https://dawarich.app/docs/self-hosting/monitoring/prometheus/

Dateien

apps/dawarich/
|-- docker-compose.yml
|-- .env.example
|-- prometheus-scrape.snippet.yml
|-- homeassistant-dawarich.example.yaml
|-- grafana/
|   |-- datasource-dawarich.yml
|   `-- dashboard-dawarich.json
|-- postgres/initdb/20-grafana-readonly.sh
`-- secrets/*.txt.example

Setup-Reihenfolge

1. Stack-Verzeichnis nach Komodo/Gitea uebernehmen: apps/dawarich.
2. .env.example als nicht versionierte Stack-.env oder Komodo Stack Environment anlegen.
3. Secret-Dateien auf dem Unraid-Host erstellen:

install -d -m 700 /mnt/user/appdata/secrets
openssl rand -base64 48 > /mnt/user/appdata/secrets/dawarich_postgres_password.txt
openssl rand -base64 48 | tr -dc 'A-Za-z0-9._~-' | head -c 48 > /mnt/user/appdata/secrets/dawarich_redis_password.txt
openssl rand -hex 64 > /mnt/user/appdata/secrets/dawarich_secret_key_base.txt
openssl rand -base64 48 > /mnt/user/appdata/secrets/dawarich_metrics_password.txt
openssl rand -base64 48 > /mnt/user/appdata/secrets/dawarich_grafana_ro_password.txt
chmod 600 /mnt/user/appdata/secrets/dawarich_*.txt

4. Bind-Volume-Zielpfade vor dem ersten Deploy anlegen:

install -d -m 750 \
  /mnt/user/appdata/dawarich/postgres17 \
  /mnt/user/appdata/dawarich/redis \
  /mnt/user/appdata/dawarich/shared \
  /mnt/user/appdata/dawarich/public \
  /mnt/user/appdata/dawarich/watched \
  /mnt/user/appdata/dawarich/storage

5. In Komodo als Compose-Stack deployen. frontend_net und backend_net muessen bereits existieren.
6. Ersten Login in Dawarich durchfuehren und den API-Key im Account-Bereich erzeugen.
7. Home Assistant homeassistant-dawarich.example.yaml in das Smart-Home-Fachrepo uebernehmen und device_tracker.your_phone ersetzen.

Traefik und Authelia

Die UI liegt auf https://dawarich.kaleschke.info und nutzt authelia@file,secure-headers@file.

Der Healthcheck und die Tracking-API-Routen fuer OwnTracks, Overland und Traccar sind separat und priorisiert ohne Authelia geroutet, weil Mobile Clients per Dawarich-API-Key authentifizieren und keine Browser-ForwardAuth-Challenge verarbeiten koennen. /metrics ist ebenfalls separat ohne Authelia geroutet; der Endpoint bleibt durch Dawarich HTTP Basic Auth geschuetzt.

Prometheus

prometheus-scrape.snippet.yml ist die dienstnahe Referenz. Produktiv ist der Job bereits in monitoring/prometheus/prometheus.yml eingetragen.

Der Monitoring-Stack ist dafuer bereits vorbereitet:

• /mnt/user/appdata/secrets/dawarich_metrics_password.txt ist in Dawarich und Prometheus eingebunden.

Nicht dawarich_app:9394 scrapen: das ist nach aktueller Dawarich-Doku veraltet. Der Web-Service aggregiert App- und Sidekiq-Metriken unter /metrics. Im KalliLab wird dieser Endpoint ueber https://dawarich.kaleschke.info/metrics gescraped, damit Traefik den HTTPS-Kontext setzt und Dawarich nicht auf HTTPS umleitet.

Grafana

Der Read-only-User dawarich_grafana_ro wird beim ersten DB-Init durch postgres/initdb/20-grafana-readonly.sh angelegt.

Bei einer bereits initialisierten DB das Script einmal manuell im DB-Container ausfuehren:

docker exec dawarich_db /docker-entrypoint-initdb.d/20-grafana-readonly.sh

Die produktive Provisionierung ist bereits in den vorhandenen Monitoring-Stack integriert:

• Datasource: monitoring/grafana/provisioning/datasources/dawarich.yml
• Dashboard: monitoring/grafana/dashboards/dawarich.json
• Grafana haengt an backend_net, damit dawarich_db:5432 erreichbar ist.
• DAWARICH_GRAFANA_RO_PASSWORD wird beim Grafana-Start aus /mnt/user/appdata/secrets/dawarich_grafana_ro_password.txt exportiert.

Home Assistant

Dawarich akzeptiert OwnTracks-kompatible Location-Punkte per:

https://dawarich.kaleschke.info/api/v1/owntracks/points?api_key=<dawarich-api-key>

homeassistant-dawarich.example.yaml enthaelt:

• rest_command.dawarich_push_owntracks
• Automation fuer device_tracker-State-Changes
• API-Key aus HA secrets.yaml als dawarich_api_key

Alternativ existiert eine HACS-Integration dawarich-home-assistant; die YAML-Variante hier bleibt absichtlich transparent und GitOps-lesbar.

Backup mit Borg

Borg-relevante Daten liegen unter:

/mnt/user/appdata/dawarich/postgres17
/mnt/user/appdata/dawarich/redis
/mnt/user/appdata/dawarich/shared
/mnt/user/appdata/dawarich/public
/mnt/user/appdata/dawarich/watched
/mnt/user/appdata/dawarich/storage
/mnt/user/appdata/secrets/dawarich_*.txt

Primaerer Restore-Weg fuer die DB sollte ein logischer Dump plus Appdaten sein. Raw-Postgres-Verzeichnisse sind nur fuer gleiches Major/PostGIS-Image und sauberen Shutdown geeignet.

Empfohlener Dump vor Borg:

docker exec dawarich_db pg_dump -U dawarich -d dawarich_production -Fc > /mnt/user/backups/borg/dumps/latest/dawarich.dump

Updates

• Kein latest verwenden.
• Vor jedem Update Release Notes lesen, besonders bei Dawarich und PostGIS.
• Dawarich App und Sidekiq muessen immer dasselbe Image-Tag nutzen.
• PostGIS-Major-/Minor-Wechsel getrennt planen und vorher Dump plus Restore-Probe erstellen.
• Image-Digests nach Review bewusst aktualisieren.

Rollback

1. Komodo Stack stoppen.
2. Vorherigen Git-Commit mit altem Image-Tag/Digest deployen.
3. Falls nur App-Code gewechselt wurde: Stack starten und Healthchecks pruefen.
4. Falls DB-Migrationen gelaufen sind: DB aus dawarich.dump in einen frischen PostGIS-17-Container restoren; kein blindes Zurueckkopieren eines Live-Postgres-Verzeichnisses.
5. Dawarich UI, /api/v1/health, Prometheus-Scrape und HA-Push testen.