Installation auf dem Timberwolf mittels Portainer

Um die CometVisu auf dem Timberwolf-Server zu installieren wird die dort verwendete Administrationsoberfläche Portainer verwendet.

Installation

Mit dieser Anleitung wird die CometVisu auf dem Timberwolf Server über HTTPS unter der Adresse https://<mein timberwolf>/proxy/visu/ aufrufbar sein.

Grundsätzlich eignen sich diese Schritte auch als Referenz für die Installation über Portainer auf anderen Systemen, jedoch müssen die Schritte im Detail angepasst werden, da dort üblicherweise keine Proxy zur Verfügung steht, der die CometVisu über HTTPS zugreifbar macht.

Volumes anlegen

Volume für Konfigurationsdateien

Zuerst ist ein Volume anzulegen um dort die Konfigurationsdateien abzulegen und diese über Neustarts und Aktualisierungen des Containers hinweg beizubehalten.

Die notwendigen Schritte sind: Volumes → Add Volume → Name: CometVisuConfig → Create the Volume

../_images/portainer_volume_add.png

Volume im Portainer anlegen

Dieses Volume kann von außen mit den Config-Dateien befüllt werden - oder am besten über den Manager.

Volume für RRD

Dieser Schritt ist optional und nur notwendig, wenn das Diagram Plugin mit RRD Dateien genutzt werden sollen. Bei der reinen Verwendung der InfluxDB kann dieser Schritt übersprungen werden.

Die Schritte für das Anlegen des Volume für Konfigurationsdateien ist zu wiederholen, jedoch wird hier sinnvoller Weise der Name CometVisuRRD gewählt.

Das Befüllen dieses Containers muss extern erfolgen, z.B. durch einen anderen Container, der diesen RRD-Container gleichzeitig mit einbindet.

Wichtig: Das interne Format der RRD Dateien ist Architektur spezifisch. So können die RRD-Dateien vom WireGate (32 Bit Architektur) nicht direkt auf dem Timberwolf (64 Bit Architektur) verwendet werden [1].

Anlegen des Containers

Unter Containers → Add Container

  • Name: CometVisu

  • Image configuration: Name: cometvisu/cometvisu:latest für die “großen” Server (TSW2xxx) oder cometvisu/cometvisu:latest-arm für die Hutschienen-Server.

  • Port mapping: host 18080, container 80

  • Advanced container settings:

    • Volumes: Volume mapping

      • container: /var/www/html/config ⭢ volume: CometVisuConfig (bis einschließlich Version 0.10.2)
      • container: /var/www/html/resource/config ⭢ volume: CometVisuConfig (ab Version 0.11)
      • container: /var/www/rrd ⭢ volume: RRD (Optional, wenn RRD genutzt werden soll)

    • Env: Environment variables

      • name: CGI_URL_PATH mit value: /proxy/visu/cgi-bin/

      • Je nach lokaler Umgebung sind gegebenenfalls weitere Anpassungen notwendig, die im Abschnitt des Docker Containers angegeben wurden.

        So kann es notwendig sein für KNX_PA einen anderen Wert als das Default 1.1.238 zu setzen, wenn diese physikalische Addresse bereits belegt ist oder eine andere Linie als 1.1 verwendet werden soll.

        Es ist auch wichtig, dass der Port der KNX Schnittstelle korrekt ist. Im Timberwolf ist unter Einstellungen → KNX → Schnittstellen der verwendete Port ersichtlich:

        ../_images/timberwolf_knx_port.png

        Sollte der Port von 3700 abweichen, so ist die Umgebungsvariable KNX_INTERFACE entsprechend anzupassen, in diesem Beispiel auf den Wert iptn:172.17.0.1:3674.

    • Restart policy: Unless stopped

../_images/portainer_container_add.png

Container im Portainer anlegen

../_images/portainer_container_volumes_add.png

Container Volumes im Portainer konfigurieren

../_images/portainer_container_env_add.png

Container Env im Portainer konfigurieren

../_images/portainer_container_restart_add.png

Container Restart policy im Portainer konfigurieren

Dann über Deploy the container diesen erzeugen.

Proxy einrichten

In der Timberwolf Oberfläche: Einstellungen → Remotezugriff → Reverse Proxy

  • URL: visu/, Target http://127.0.0.1:18080/

Über Add bestätigen.

../_images/timberwolf_proxy_add.png

Timberwolf Proxy-Eintrag hinzufügen

Die CometVisu ist nun über https://<mein timberwolf>/proxy/visu/ aufrufbar.

InfluxDB Zugriff

Hinweis

The InfluxDB access as well as the hidden config was introduced with version 0.11.0 and isn’t available in earlier versions.

Für den Zugriff auf die Zeitreihen der InfluxDB müssen die Credentials in der Versteckten Konfiguration über den Manager eingetragen werden. Hierzu muss auf dem Timberwolf Server unter Portainer bei “Wie Sie aus dem Docker Container auf die Zeitreihen-Datenbank zugreifen können” auf das i geklickt werden um den Benutzernamen und das Passwort für die lokale Installation in Erfahrung zu bringen.

../_images/timberwolf_influx.png

Timberwolf InfluxDB Credentials

In der Versteckten Konfiguration des Managers ist nun ein Eintrag mit diesen Eigenschaften anzulegen:

  • Name: influx
  • Schlüssel und Wert:
    • uri: https://172.17.0.1/proxy/ts/query (Sollte entgegen dieser Anleitung das Netzwerk des Containers angepasst worden sein, so muss gegebenenfalls hier die IP-Addresse entsprechend angepasst werden)
    • user: Benutzername aus den Credentials
    • pass: Passwort aus den Credentials
    • selfsigned: true
../_images/timberwolf_influx_manager.png

Timberwolf InfluxDB Credentials im Manager

Aktualisieren

Container ersetzen

Unter Containers → CometVisu wird über den Button Duplicate/Edit das Menü aufgerufen um den Container zu aktualisieren.

Hier ist sicher zu stellen, dass Always pull the image aktiv ist.

Unter Advanced container settings → Labels sollten die Labels gelöscht werden, um später leichter erkennen zu können welche CometVisu Container Version installiert ist.

Wenn von der Version 0.10.2 auf eine Version aus der 0.11er Reihe gewechselt werden soll, so ist noch unter Volumes der Config-Pfad von /var/www/html/config auf /var/www/html/resource/config anzupassen.

Mit Actions → Deploy the Container wird der Container nun durch die neueste Version ersetzt.

../_images/portainer_container_replace.png

Container im Portainer durch eine neue Version ersetzen

Anschließend muss die Sicherheitsabfrage bestätigt werden.

../_images/portainer_container_replace_confirm.png

Bestätigung um den Container im Portainer durch eine neue Version zu ersetzen

Aufräumen

Wenn ein Container durch einen neuen ersetzt wird, so bleibt der alte als Unused im System zurück und belegt weiterhin Platz. Dieser lässt sich unter Images löschen.

Durch markieren des zu löschenden Images (zu erkennen am Label Unused und dem entsprechenden Tag) kann über Remove das Image entfernt werden.

../_images/portainer_image_remove.png

Portainer Dialog um ein Image zu löschen

Entwicklungsversion

Grundsätzlich sind für die jeweils aktuelle Entwicklungsversion die gleichen Schritte wie für das Release durchzuführen. Auch wenn theoretisch das gleiche Konfigutations-Volume wie für die Produktiv-Version verwendet werden kann, so sollte ein getrenntes Volume (z.B. CometVisuTestConfig) angelegt werden, da sich durch zukünftige Updates das Format der Config-Dateien inkompatibel ändern kann.

Wie unter Docker beschrieben hat die neueste Entwicklunglungsversion den Tag testing. Somit ist unter Anlegen des Containers als name cometvisu/cometvisu:testing bzw. cometvisu/cometvisu:testing-arm zu verwenden.

Um für Fehlerberichte u.ä. eine einheitliche Umgebung zu haben, ist die Empfehlung die Testing Version mit diesen Parametern zu installieren:

  • Container:
    • Name: CometVisuTest
    • Image configuration: Name: cometvisu/cometvisu:testing bzw. cometvisu/cometvisu:testing-arm
    • Port mapping: host 28080, container 80
    • Advanced container settings:
      • Volumes: Volume mapping
        • container: /var/www/html/resource/config ⭢ volume: CometVisuTestConfig
        • container: /var/www/rrd ⭢ volume: RRD (Optional)
      • Env: Environment variables name: CGI_URL_PATH mit value: /proxy/visutest/cgi-bin/
  • Proxy:
    • URL: visutest, Target http://127.0.0.1:28080/
[1]

Um den Inhalt einer RRD Datei RRD_Name von einer Architektur auf eine andere zu übertragen muss auf dem Quell-System (also z.B. dem WireGate) der Befehl

rrdtool dump /var/www/rrd/RRD_Name.rrd > RRD_Name.xml

ausgeführt werden. Auf dem Ziel-System (also z.B. einem Container auf dem Timberwolf) wird dann mit dem Befehl

rrdtool restore -f RRD_Name.xml RRD_Name.rrd

die neue RRD-Datei angelegt.

Wenn auf dem Quell-System mit einer Lokalisierung gearbeitet wird, die Zahlen mit einem Komma als Dezimaltrennzeichen verwendet (so wie im Deutschen üblich), so kann es sein, dass der RRD-Export mit Komma statt Punkt erfolgt und somit der Import fehl schlägt. Hier wäre dann der Export mit generischem LANG=C durchzuführen.

Um eine größere Menge an RRD-Dateien zu konvertieren kann dies über eine Schleife vereinfacht werden:

LANG=C; for f in *.rrd; do rrdtool dump ${f} > ${f}.xml; done

bzw.

for f in *.xml; do rrdtool restore ${f} ${f}.rrd; done