laermsensor-stack/README.md

Projekt Lärm-Sensoren

Installation der Container

Dateien

Directory-Struktur

Die Datei noise.tgz enthält die folgenden Dateien und Verzeichnisse:

<LOCALDIR>
|
+- <d>noisesensors
       |
       +- <f>docker-compose.yml
       +- <f>readarchive-stack.yml
       +- <d>log
       +- <d>data
       |  +- <d>mongo
       |  |  +- <d>data  
       |  |  +- <d>entries
       |  |  |  +- <f>create.js
       |  + <d>influx
       |  |  + <d>data   

<f>: file,  <d>: directory       

• docker-compose.yml
  enthält die Anweisungen für die Docker-Container. Dies kann so an das aktuelle Portainer-Stack angehängt werden.
• readarchive-stack.yml
  eigenes, kleines Stack für den Einmal-Lauf readarchive (siehe unten). Gehört bewusst nicht ins Haupt-Stack, weil es kein Dauerdienst ist.
• log
  Ablage für die Logdateien der einzelnene Container (noise.log, sensorapi.log und readin.log) . Diese werden täglich komprimiert. Es werden Versionen für 7 Tage aufgehoben.
• data
  hier darunter befinden sich alle Daten, sowohl die Datenbanken als auch Konfigurationen. Außerdem werden jeweils die laufend eingelesenen Daten als actdata.json abgelegt. Diese werden bei jedem neuen Einlesen wieder überschrieben.
• data/mongo
  Verzeichnis für die Mongo-Datenbank
• data/mngo/data
  hier befinden sich die eingelesenen Daten
• data/mongo/entries
  hier liegt die Datei create.js, mit deren Hilfe bei ersten Start der Datenbank die Collections und die Indexe erzeugt werden.
• data/influx
  Verzeichnis für die Influx-Datenbank
• data/influx/data
  Hier dann die eingelesenen Daten

Aufrufe

Entpacken des Tar-Files noise.tgz in einem beliebigen Verzeichnis (das Direktoty noisesensors wird angelegt). Der komplette Pfad zu dem Verzeichnis (also ab root) muss in der Environmentvariablen LOCALDIR hinterlegt werden.

Nun das docker-compose.yml in das Portainer-Stack einfügen. Zusätzlich folgende Environment-Variablen festlegen:

DOCKER_INFLUXDB_INIT_USERNAME=<username>
DOCKER_INFLUXDB_INIT_PASSWORD=<passwort>
DOCKER_INFLUXTOKEN=<token>
MONGO_ROOT_USERNAME=<username1>
MONGO_ROOT_PASSWORD=<passwort1>
LOCALDIR=<directory, in die das .tgz entpackt wurde>
STORE=influx

<username>, <passwort>, <username1>, <passwort1> und <token> sind anzupassen.

Danach einloggen in das Docker-Registry auf citysensor.de:

docker login docker.citysensor.de

Einloggen mit Username und Passwort (siehe mail), anschließend kann das Portainer-Stack gestartet werden (die Container werden beim ersten mal automatisch von docker.citysensor.de herunter geholt).

Damit sollte dann Alles laufen. Das Programm holt alle 5min die neuesten Daten von sensor.community ab und speichert die Messwerte in der InfluxDB und die Metadaten des Sensors in der Mongo-Datenbank.
Das Logfile kann via tail -f log/noise.log im Verzeichnise noisesensors mitgeschrieben werden.

Container

• readin
  Über diesen Container werden alle 5 min. die aktuellen Daten von sensor.community abgeholt und in den beiden Datenbanken gespeichert

• readarchive
  Gegenstück zu readin: liest rückwirkend die Tagesdateien von archive.sensor.community ein, um Lücken zu füllen. Kein Dauerdienst, sondern ein Lauf mit Parametern — deshalb steht er nicht im Haupt-Stack, sondern in der eigenen Datei readarchive-stack.yml.

Auf der Kommandozeile mit Argumenten:

docker compose -f readarchive-stack.yml run --rm readarchive \
       -t noise -s 2026-07-22 -e 2026-07-23 -d influx

Im Portainer als eigenes Stack anlegen (Inhalt von readarchive-stack.yml) und die Parameter unten als Environment variables eintragen — docker compose run hat dort kein Gegenstück, aber readFromcsv.js liest jeden Parameter auch aus einer Env-Variablen:

CLI	Env	Default
-s	START	gestern
-e	END	Startdatum + 1 Tag (exklusiv)
-t	TYP	noise
-d	DBASE	both, in der Stack-Datei auf influx vorbelegt

Deploy the stack startet den Lauf, der Container endet danach und bleibt als „Exited" stehen. Für den nächsten Zeitraum nur die Variablen ändern und Update the stack. Der Haupt-Stack wird dabei nicht angefasst.

Beide Wege brauchen dieselben Zugangsdaten und LOCALDIR — auf der Kommandozeile aus einer .env neben der Datei, im Portainer aus den Stack-Variablen. Auch mit -d influx wird Mongo gebraucht, dort liegen die Metadaten der Sensoren.

Der Netz-Name ist die Stolperstelle. Das docker-compose.yml des Haupt-Stacks deklariert kein Netz — Compose legt für jedes Projekt automatisch <projektname>_default an und hängt alle Services hinein; daher funktioniert MONGOHOST: mongodb. Bei Portainer ist der Projektname der Stack-Name. Heißt das Stack dort noisesensors, passt der in readarchive-stack.yml eingetragene Wert noisesensors_default; heißt es laerm, muss dort laerm_default stehen, sonst bricht der Lauf ab:

network noisesensors_default declared as external, but could not be found

Vor dem ersten Lauf also im Portainer unter Networks nachsehen (oder docker network ls) und den Namen in readarchive-stack.yml angleichen. Das Netz wird nur an einer Stelle erzeugt — im Haupt-Stack implizit. Es auch dort als external zu deklarieren, führt dazu, dass es niemand mehr anlegt.

Option: fester Netz-Name. Wer die Abhängigkeit vom Stack-Namen loswerden will, benennt im Haupt-Stack das Default-Netz um:

networks:
  default:
    name: noisesensors_net

Kein Service braucht dafür einen eigenen networks:-Eintrag — die automatische Zuordnung bleibt, das Netz heißt nur fest noisesensors_net, und in readarchive-stack.yml steht dieser Name statt <stack-name>_default. Der Preis: Beim Umstellen wechseln alle Container das Netz und werden neu erzeugt, Mongo und Influx sind also kurz weg. Die Daten liegen auf Bind-Mounts und bleiben unangetastet — trotzdem gehört das in ein Wartungsfenster und nicht nebenbei erledigt.

Umgekehrt gilt: Ein networks: an einem Service hebt dessen automatische Zuordnung auf. Wer dort etwas einträgt — etwa um noise zusätzlich ins Traefik-Netz zu hängen —, muss default mit aufführen, sonst erreicht der Service die übrigen Container des Stacks nicht mehr.

Ein Tag dauert etwa zwei Minuten. Schlägt ein Influx-Write fehl, werden die betroffenen Sensoren am Ende aufgelistet und der Exit-Code ist ≠ 0 (im Portainer als „Exited (1)" sichtbar).

• logrotate
  Mit Hilfe dieses Containers werde die Log-Files im Unterverzeichnis log täglich rotiert. Es werden 7 Versionen behalten, ältere gelöscht.

• sensorapi
  Über diesen Container werde die Daten aus der Mongo-Datenbank ausgelesen, aufbereitet und als JSON- oder CSV-Datei ausgegeben.

• noise
  Mit diesem Container wird die Grafik aufbereitet. Auch kann darüber die API (im Container sensorapi) angesprochen und die Daten abgerufen werden. (Für die Parameter der Anfrage siehe die extra Beschreibung Laerm_API). Dieser Container sollte von außen über einen Domainnamen erreichbar sein. Ansonsten hört er auf Port 3003 auf HTTP-Anfragen.

• mongodb
  Die Mongo-Datenbank. Es gibt eine Datenbank namens sensor_data. Diese hat folgende Collections:

  • properties
    Hier liegen für alle Sensoren die Metadaten (wie Ortskoordinaten, Typ, Zeitpunkt der letzten Übertragung etc.)
  • statistics
    Dient nur Kontrolle, schreibt verschiedenen Statistikdaten wie Dauer des Einlesens, Dauer des Speicherns in den DBs etc.
    Zugriff:
    Am Besten über das Programm MongoDB Compass. Zugangsdaten entprechend der im Portainer hinterlegten.

• influxdb
  Die Influx-Datenbank. Hier werden in dem Bucket sensor_data die reinen Messwert der einzelnen Sensoren gespeichert.
  Zugriff:
  http://<server>:8086
  Logindaten: Entsprechen der im Portainer hinterlegten.

Sourcen für die Container

Das gesamte Projekt ist im GitHub unter laermsensor-stack abgelegt. Für jeden der 4 Container existiert darunter ein Verzeichnis: readin, readarchive, sensorapi und noise. In diesen Verzeichnissen sind alle benötigten Sourcen enthalten.

Daneben gibt es common mit den Modulen, die sich readin und readarchive teilen: mongo.js, influx_post.js, logit.js und statistics.js. Sie lagen früher in beiden Komponenten doppelt und sind auseinandergelaufen. Wer dort etwas ändert, ändert es für beide — nach einer Änderung also beide Container neu bauen.

Sollte was geändert werden, so muss mit deploy.sh der Container neu erzeugt und auf die Registry (siehe oben) gepushed werden. Der Build-Kontext von readin und readarchive ist wegen common/ das Wurzelverzeichnis des Repositories; deploy.sh wechselt selbst dorthin und kann aus dem Komponentenverzeichnis aufgerufen werden.

deploy.sh nimmt optional ein Tag als Argument:

./deploy.sh              # nur :latest
./deploy.sh 2026-08-01   # :2026-08-01 und zusätzlich :latest

Ein Tag mitgeben. Wird nur latest gepusht, überschreibt jeder Build den vorherigen Stand und es gibt keinen Weg zurück (siehe Update eines laufenden Stacks).

Das Verzeichnis noisesensors ist nur dummy, es spiegelt die Dateistruktur für das aktuelle Stack ab, wie oben beschrieben (wird mit Hilfe von noise.tgz erzeugt).

Update eines laufenden Stacks

Betrifft eine Installation, die bereits läuft und auf einen neueren Stand gebracht werden soll.

1. Rollback-Möglichkeit sicherstellen

Vor allem anderen. Zeigt in der Registry nur latest auf das Image, existiert der laufende Stand nach dem Pull nirgends mehr. Prüfen, welche Tags es gibt:

curl -H "Authorization: Basic <auth aus ~/.docker/config.json>" \
     https://docker.citysensor.de/v2/readin/tags/list

Fehlt ein benanntes Tag für den laufenden Stand, ihn zuerst benennen und pushen. Das alte Image findet sich auf dem Build-Rechner meist noch unbenannt (docker images | grep readin):

docker tag <alte-image-id> docker.citysensor.de/readin:<datum-alt>
docker push docker.citysensor.de/readin:<datum-alt>

2. docker-compose.yml im Portainer angleichen

Den Stand aus noisesensors/docker-compose.yml dieses Repositories übernehmen. Zu beachten:

• Zwingend bei einem Update von einem Stand vor August 2026: das Volume von readin muss auf /opt/app/readin/data zeigen, nicht mehr auf /opt/app/data. Das Layout im Image spiegelt seit der Einführung von common/ das Repository. Bleibt der alte Pfad stehen, schreibt readin aktdata.json in die Container-Schicht statt auf den Host.
• Der Service readarchive gehört nicht mehr ins docker-compose.yml. Steht er dort noch (mit profiles: ["tools"]), kann er beim Update entfallen — er wird durch das eigene Stack readarchive-stack.yml ersetzt.
• Nicht aufnehmen: ein Mount auf /etc/influxdb2. Das Entrypoint von influxdb legt dort beim Setup das CLI-Profil default an. Ist bereits eines vorhanden, scheitert der Setup — und das Entrypoint löscht daraufhin influxd.bolt und engine/ im Datenverzeichnis und startet neu. Weil der Mount das Aufräumen überlebt, wiederholt sich das endlos und der Datenbestand ist bei jeder Runde weg.

3. Nur den geänderten Container ziehen

Nicht den ganzen Stack neu starten — Mongo und Influx bleiben unangetastet:

docker compose pull readin
docker compose up -d readin

Im Portainer entspricht das dem Aktualisieren des Stacks mit Re-pull image and redeploy.

4. Verifizieren

Der nächste Lauf kommt binnen fünf Minuten:

tail -20 <LOCALDIR>/noisesensors/log/readin.log
ls -l  <LOCALDIR>/noisesensors/data/aktdata.json

Erwartet werden Influx-Write-Time und Program end sowie ein frischer Zeitstempel an aktdata.json — letzterer belegt, dass der Volume-Pfad stimmt.

5. Rollback

Image-Tag im Stack auf den in Schritt 1 gesicherten Stand setzen, die Volume-Zeile auf den alten Pfad zurückdrehen, redeploy.

Versionen

Version	Datum	Bemerkung
1.0.0	2023-11-30
2.0.0	2026-07-25	Anpassung an Stack-Änderungen
2.1.0	2026-08-01	readarchive dazu, gemeinsame Module unter common/, Zeitstempel in UTC
2.1.1	2026-08-02	readarchive als eigenes Stack (readarchive-stack.yml)