ioBroker Simple-API Adapter

In diesem Artikel zeige ich Dir die Möglichkeiten der Nutzung des Simple-API Adapters. Mit dem Simple-API Adapter kann einfach und schnell ein lesender oder schreibender Zugriff auf die Datenpunkte von ioBroker geschaffen werden. Gerade in Verbindung mit anderen Diensten oder smarten IOT Geräten sind hier viele verschiedene Szenarien der Nutzung denkbar. In dem Beispiel zeige ich, wie externe Sensoren über diese API an ioBroker angebunden werden können. Der Adapter stellt für den Zuriff einen extra HTTP-Zugriff via GET und POST zur Verfügung.

Im ersten Schritt installieren wir zunächst den Adapter über die Administrationsoberfläche.

Nach dem der Adapter installiert wurde können wir den Adapter konfigurieren. In der Konfiguration können wir den verwendeten Web-Adapter, die IP, sowie den Port anpassen. Zudem stehen Optionen zur Verschlüsselung und Authentifizierung zur Auswahl. In meinem Beispiel habe ich alle Einstellungen des Adapters so belassen, der Webservice sollte uns jetzt somit auf dem HTTP-Port 8087 zur Verfügung stehen.

Um im ersten Schritt jetzt die Erreichbarkeit und somit Funktionalität des Adapters testen zu können, rufen wir die integrierte Hilfe-Funktion des Adapters auf. Diese gibt uns ein JSON-String im Webbrowser mit den verschiedenen Möglichkeiten des Adapters zurück:

Mit folgendem Aufruf erhalten wir die Ausgabe:

http://10.50.1.11:8087/help
Als IP-Adresse wird die ioBroker IP-Adresse sowie der eingestellte Port im Simple-API Adapter verwendet.

{
  "getPlainValue": "http://192.168.2.90:8087/getPlainValue/stateID",
  "get": "http://192.168.2.90:8087/get/stateID/?prettyPrint",
  "getBulk": "http://192.168.2.90:8087/getBulk/stateID1,stateID2/?prettyPrint",
  "set": "http://192.168.2.90:8087/set/stateID?value=1&prettyPrint",
  "toggle": "http://192.168.2.90:8087/toggle/stateID&prettyPrint",
  "setBulk": "http://192.168.2.90:8087/setBulk?stateID1=0.7&stateID2=0&prettyPrint",
  "setValueFromBody": "http://192.168.2.90:8087/setValueFromBody?stateID1",
  "objects": "http://192.168.2.90:8087/objects?pattern=system.adapter.admin.0*&prettyPrint",
  "states": "http://192.168.2.90:8087/states?pattern=system.adapter.admin.0*&prettyPrint"
}

Für unser Beispiel habe ich zusätzliche Datenpunkte in meinen eigenen Datenpunkten definiert. Der folgende Screenshot veranschaulicht die Datenpunkte:

Datenpunkte verändern
Mit dem folgenden Aufruf können wir über einen HTTP-Aufruf einen Datenpunkt verändern.

http://10.50.1.11:8087/set/Datenpunkte.0.Sensordata.Outdoor2.Temperatur?value=20

Datenpunkte auslesen (kompletter Datenpunkt)
Mit dem folgenden Aufruf können wir einen kompletten Datenpunkt im JSON-Format über einen HTTP-Aufruf auslesen.

http://10.50.1.11:8087/get/Datenpunkte.0.Sensordata.Outdoor2.Temperatur

Datenpunkte auslesen (kompletter Datenpunkt)
Mit dem folgenden Aufruf können wir einen einzelnen Wert (PlainValue) des Datenpunktes auslesen und zurückgeben.

http://10.50.1.11:8087/getPlainValue/Datenpunkte.0.Sensordata.Outdoor2.Temperatur
Weitere Aufruf-Möglichkeiten der HTTP-API

Toggle
Umschalten eines Wert (Logischer Wert true -> false, false -> true)
setBulk
Setzen mehrer Datenpunkte mit einem HTTP-Aufruf
objects
Gibt alle Objekte mit dem übergebenen Namen zurück

Content retrieved from: https://www.smarthome-tricks.de/software-iobroker/iobroker-simple-api-adapter/.

10. Mai 2024

iobroker Linux-Update

Wird gemacht im Terminal vom Container

pkill -u iobroker
iobroker update
iobroker upgrade self

Nach dem Update dann ein „Neustart“ des Containers.

node.js kann man durch Update des Linux aktualisieren:

apt update
apt upgrade

18. September 2023

MACVLAN über Portainer einrichten

In diesem Tutorial werden wir mittels der Portainer Weboberfläche manuell ein MACVLAN erstellen dass wir dann später beim Starten eines Containers verwenden können. Wie ihr Portainer für euren Docker Host einrichtet habe ich bereits in diesem Tutorial beschrieben:

Ich empfehle die Verwendung von MACVLAN grundsätzlich nur fortgeschrittenen Benutzern, denn für die Umsetzung solltet Ihr in jedem Fall mit den Basics zum Thema „IP-Netzwerke“ vertaut sein und euer eigenes Heimnetzwerk im Griff haben. Wenn euch Begriffe wie „DHCP“, „Gateway“ oder „Subnet“ nichts sagen, holt euch bitte entsprechende Unterstützung. Außerdem ist es hilfreich sich vorab einmal mit dem Networking unter Docker auseinander zu setzen. Infos dazu findet ihr z.B. hier:

docs.docker.com/network

Vorbereitungen für MACVLAN

Und schon geht es los. Für die Umsetzung des Tutorials benötigt ihr also Kenntnisse über euer eigenes Netzwerk, den Zugriff auf die Portainer Oberfläche und einen Konsolenzugriff (z.B. über SSH) auf euren Docker Host.
In meinem Beispiel arbeite ich auf einer Synology Disk Station und verwende als Testnetz ein 192.168.0.0/24-Netz. Das Gateway liegt klassich auf der .1 und es gibt keinen DHCP-Bereich. Mein Container soll später die IP-Adresse 192.168.0.100 bekommen.

Und schon geht es los. Das Erstellen des MACVLAN-Netzwerkes umfasst insgesamt zwei Schritte. Im ersten Schritt erstelle wir eine „Configuration“ mit den gewünschten Netzwerkinformationen. Im zweiten Schritt erstellen wir dann mit Hilfe der „Configuration“ die sogenannte „Creation“ die wir dann später auch mit dem ioBroker-Container verbinden.

Hinweis

Bis einschließlich der Docker-Paketversion 17 war es durch einen Bug auf der DS nicht möglich nach der Erstellung der „Configuration“ eine „Creation“ zu erstellen. Dafür konnte man aber die „Configuration“ direkt mit dem ioBroker-Container verbinden und hatte ein funktionierendes MACVLAN. Eine Erklärung dafür habe ich nicht gefunden, es lief so aber bei mir monatelang problemlos. Trotzdem würde ich empfehlen bei Installationen auf einer DS das Docker-Paket vorher auf die aktuellste Version zu bringen.

Öffnen wir also erst einmal die Portainer-Weboberfläche, melden uns an und wählen unseren Endpoint (Host). Anschließend starten wir die Erstellung der „Configuration“ mit einem Klick auf den Button „Add network“ unter „Networks“.

Im folgenden Dialog sind einige Felder zu füllen. Beginnen wir mit dem Namen. Ich werde dem MACVLAN nur eine einzelne IP-Adresse zuweisen. Daher bekommt mein MACVLAN auch einen eindeutigen Namen. Weil es sich um die „Configuration“ handelt, hänge ich noch ein „conf“ dran: „iob_public_conf“. Als Driver wählen wir natürlich „MACVLAN“.

Weiter geht es zum nächsten Feld: Parent network card. Hier müssen wir angeben auf welche physikalische Netzwerkkarte wir unser MACVLAN binden wollen. An dieser Stelle liegt dann auch die Beurteilung „für fortgeschrittenen Benutzer“ begründet. Denn mir ist bisher kein Weg bekannt diese Information der Weboberfläche der DS zu entlocken. Da hilft nur Kommandozeile raus und „ifconfig“ rein.

Auf meiner virtuellen Test-DS liegt die lokale IP-Adresse (192.168.0.32) auf dem Interface eth0. Ich verwende also dieses.

Weiter geht es mit dem Abschnitt „Network configuration“ Hier fülle ich die Informationen meinem Netzwerk entsprechend aus. Für „IP range“ verwende ich die gewünschte IP-Adresse mit einer Präfixlänge von „/32“. Dieses Netz enthält dann schließlich genau eine IP-Adresse.

Hinweis

Es ist natürlich auch möglich dem MACVLAN über die Präfixlänge einen ganzen Adressbereich zur Verfügung zu stellen, sodass man mehrere Container im MACVLAN mit Adressen versorgen kann.

So hat man z.B. bei 192.168.0.80/29 die Adressen .81 bis .86 für Container zur Verfügung.

Allerdings sollte man bei jedem Container genau überlegen ob dieser wirklich eine eigene IP-Adresse benötigt. In den meisten Fällen (Webster, Datenbanken usw.) ergibt das nämlich keinen Sinn.

Bei der Wahl des Netzes unterstützen kann euch dabei der z.B. Netzwerkrechner von Heise.

Achtung: Um IP-Konflikte in eurem Netzwerk zu vermeiden, stellt bitte sicher dass der gewählte Bereich NICHT von einem DHCP Server verwaltet wird/ vergeben werden kann!

Über den Button „Create the network“ schließe ich die Erstellung der „Configuration“ ab.

Die Erstellte „Configuration“ sollte nun in der Liste der Netzwerke auftauchen.

Fehlt noch die „Creation“. Um diese zu erstellen klicken wir erneut auf den Button „Add network“ und geben einen Netzwerknamen an. Dieses Mal verwenden wir nur „iob_public“ und wählen als „Driver“ erneut „MACVLAN“ aus. Anschließend klicken wir auf den Button „Creation“ und wählen im Dropdownmenü „Configuration“ unsere vorab bereits erstellte „Configuration“ aus.

Über den Button „Create the network“ schließen wir nun die Erstellung der „Creation“ ab. Das neue Netzwerk erscheint in der Liste und ist bereit zur Verwendung.

Umsetzung mit docker-compose aka „Portainer Stacks“…

Natürlich lässt sich die Erstellung des MACVLAN auch in docker-compose abbilden. In Portainer nennt sich das ganze „Stacks“. Wer noch nichts davon gehört hat kann erst einmal hier weiter lesen. Für alle Anderen habe ich hier das oben erläuterte Beispiel einmal als Definition für das Stack File. Der Name des Netzwerks lautet im Beispiel dabei „public“.

networks: public: driver: macvlan driver_opts: parent: eth0 ipam: config: – subnet: 192.168.0.0/24 gateway: 192.168.0.1 ip_range: 192.168.0.100/32 aux_addresses: net-address: 192.168.0.100

In dem entsprechenden Container wird das Ganze dann wie folgt, inklusive der IP-Adresse für den Container, referenziert.

networks: public: ipv4_address: 192.168.0.100

Das solle es zu diesem Thema erst einmal gewesen sein. Bei Fragen und Anregungen nutzt gerne die Kommentare oder kontaktiert mich über einen der öffentlichen Kanäle wie z.B. über das ioBroker Forum oder den ioBroker Discord Channel.

Grundsätzlich biete ich keinen persönlichen Support per Messenger bzw. E-Mail an. Fragen sollten meiner Meinung nach immer öffentlich gestellt und beantwortet werden, damit auch andere User mit der selben Frage Zugriff auf die Antworten bekommen. 🙂 Falls ihr mal irgendwo keine Antwort bekommt, nutzt gerne das Kontaktformular und macht mich auf euren Kommentar, Post, Beitrag oder Thread aufmerksam! Danke.

Content retrieved from: https://smarthome.buanet.de/2020/09/macvlan-ueber-portainer-einrichten/.

3. März 2021

ioBroker Docker Container – Steuerung per Kommandozeile

Grundsätzlich kann die ioBroker-Installation innerhalb meines Docker Containers wie in der ioBroker-Dokumentation beschrieben über die Kommandozeile bedient werden. Allerdings gilt dies nicht uneingeschränkt. Denn aufgrund von Problemen beim Autostart des ioB-Dienstes innerhalb des Containers bin ich gezwungen gewesen den ioBroker im Container per Befehl zu starten und nicht wie üblich als Dienst laufen zu lassen. Demnach funktioniert auch die Steuerung des Dienstes über iobroker start und iobroker stop im Container nicht. Als Alternative verwende ich im Start-Script daher folgenden Befehl:

gosu iobroker node node_modules/iobroker.js-controller/controller.js

Allerdings empfehle ich dringend statt des manuellen Starts über die Kommandozeile immer den gesamten Container einmal neu zu starten. Nur dann ist gewährleistet dass alles so läuft wie es soll. 🙂

Natürlich unterscheidet sich aufgrund der oben genannten Unterschiede auch das Beenden des ioBrokers:

pkill -u iobroker

Dieser Befehl beendet dabei schlicht alle im Container laufenden Prozesse des Users „iobroker“.

Ein js-controller Update würde also analog zur ioBroker-Dokumentation über die Kommandozeile im Container wie folgt aussehen:

pkill -u iobroker
iobroker update
iobroker upgrade self
>>> neustart des containers <<<

alternativ:

pkill -u iobroker
npm install iobroker.js-controller –-production
>>> neustart des containers <<<

Content retrieved from: https://smarthome.buanet.de/2019/05/iobroker-docker-container-steuerung-per-kommandozeile/.

26. Februar 2021

ioBroker Docker Container – Backup & Restore

Das Thema Backup & Restore des ioBroker im Docker Container ist eigentlich gar nichts Besonderes. Denn grundsätzlich gilt nämlich, dass die ioBroker-Daten im Container genauso gesichert werden können wie in jeder anderen ioBroker-Installation auch.

Im Folgenden ein paar Informationen und Links zu den beiden wichtigsten Varianten des ioBroker-Backups und was ich euch diesbezüglich empfehle.

Variante 1: Backup auf Dateiebene

Beim Backup auf Dateiebene wird schlichtweg der gesamte Ordner in dem sich die ioBroker Installation befindet in einem Backup gesichert. Wie euch bekannt sein sollte, ist dies der Ordner /opt/iobroker oder unter Docker eben jener Ordner bzw. jenes Volume auf dem Host, der/ das bei der Erstellung in den Container eingebunden wurde.

In der Regel erfolgt das Backup auf Dateieben über ein Script auf dem Docker Host. Hier sollte aber unbedingt berücksichtigt werden, dass der ioBroker Container vor dem Kopieren/ Sichern des ioBroker-Ordners beendet sein sollte.

Diese Methode eignet sich in Bezug auf das ioBroker Docker Image vor allem für Updates des ioBroker Containers innerhalb der Major-Versionen (z.B. innerhalb der Version 5.x.x). Durch simples Anlegen einer Kopie des Ordners oder Volumes auf dem Docker Host kann man so schnell und unkompliziert eine neue Version des Docker Images testen und im Zweifel auch schnell auf die alte Version zurück schwenken.

Achtung

Beim Wechsel der Major-Version, also z.B. von einem ioBroker Docker Image v4.x.x auf v5.x.x ändert sich innerhalb des ioBroker Images zumeist auch die Node-Version. In diesem Fall wären weitere Schritte über die Kommandozeile erforderlich. Details zum Wechsel der Node Version gibt es auch hier in der offiziellen ioBroker-Doku.

Da diese Methode eher etwas für fortgeschrittenen User ist, habe ich mich dazu entschlossen diesen Weg hier nicht weiter zu erörtern. Wer doch einen Blick wagen möchte, dem empfehle ich einen kurzen Blick in die Rubrik „Sichern & Wiederherstellen“ des folgenden, eigentlich bereits eingemotteten Tutorials:

Variante 2: Backup der Konfiguration (Best Practice)

Mittlerweile bringt der ioBroker aber eine wirklich gute eingebaute Möglichkeit mit ein Backup der Konfiguration direkt aus ioBroker heraus zu erstellen. Dies geschieht entweder über den Befehl iobroker backup in der Kommandozeile oder mittels des Adapters „ioBroker.backitup“.

ioBroker.backitup

https://github.com/simatec/ioBroker.backitup

In beiden Fällen steht am Ende ein Archiv, dass die komplette Konfiguration des ioBroker enthält und sich ebenfalls per Kommandozeile oder Adapter einfach wiederherstellen lässt. Über den Adapter lassen sich außerdem zeitgesteuert Backups erstellen. Mit einem kleinen Copy Script auf dem Docker Host lässt sich das Backup dann problemlos regelmäßig auch an einen „sicheren“ Ort kopieren.

Der Große Vorteil dieser Variante besteht aber darin, dass das Backup in der Regel relativ klein ist und sich problemlos auf einem neuen oder beliebig anderem System mit ioBroker wiederherstellen lässt.

Für den Fall des ioBroker Docker Containers bedeutet dies, dass ihr getrost den alten Container und das zugehörige Image löschen könnt und nur allein aus dem Backupfile eure Installation wiederherstellen könnt.

Allerdings gibt es auch einen Nachteil. Währen ihr bei Variante 1 im besten Fall den Container einfach startet und alles wieder läuft, muss bei Variante 2 der ioBroker nach dem Restore erst die verwendeten Adapter (neu) installieren. Dies kann bei einer größeren Anzahl Adapter mitunter recht lange dauern…

Beispiel: Wiederherstellung eines ioBroker-Containers aus dem Backupfile

Wie immer gibt es also Vor- und Nachteile. Trotzdem ist Variante 2 aus meiner Sicht grundsätzlich die sauberere und zuverlässige Methode. Grund genug sie einmal in einem Beispiel durchzuspielen.

Wir stellen uns also vor, wir hatten einen Systemcrash. Das Backupfile vom gestiegen Backup ist vorhanden. Unser Docker Host (welcher Art auch immer) ist wiederhergestellt und unser Portainer läuft auch wieder.

Portainer auf der Synology DiskStation

Alles was wir nun zur Wiederherstellung tun müssen ist einen neuen ioBroker Container anlegen. Wie das geht haben wir ja bereits in diesem Tutorial besprochen:

ioBroker unter Docker auf der Synology DiskStation (ab v3)

Der Clou an der Sache: Seit Version 4.1.0 des ioBroker Container Images ist es möglich vor dem ersten Start ein Backupfile in das noch leere Verzeichnis, welches in den Container als /opt/iobroker eingebunden wird, zu kopieren. Das Backup wird dann vom Startup-Script des Container erkannt und für die Wiederherstellung verwendet. Vollautomatisch.

Weiteren Informationen dazu findet ihr auch in der Readme auf Github. Bitte behaltet bei der Prozedur nach dem Start des Containers die Logausgabe im Auge. Hier könnt ihr sehen ob der Restore erfolgreich durchgeführt werden konnte oder es ggf. Probleme gab.

Nachdem der ioBroker Container dann gestartet ist und ihr Zugriff auf den ioBroker Admin bekommen habt, könnt ihr im dortigen Log beobachten wie der ioBroker nun die Adapter nach und nach neu installiert. Jetzt braucht ihr eigentlich nur noch etwas Geduld, und der Restore ist abgeschlossen.

Hinweis

Sollte es mal nicht mit der automatischen Wiederherstellung klappen, könnt ihr natürlich auch einfach einen neuen, leeren ioBroker Container starten, das Backupfile in das ioBroker-Verzeichis kopieren und den Restore über die Kommandozeile (mehr Infos) oder den Backitup-Adapter (mehr Infos) durchführen.

Content retrieved from: https://smarthome.buanet.de/2020/10/iobroker-docker-container-backup-restore/.

26. Februar 2021

ioBroker Docker Container – Updates & Upgrades

Wie halte ich meine ioBroker-Installation aktuell? Eine kurze Frage die aber durchaus etwas komplexer zu beantworten ist. Daher im folgenden erst einmal ein paar ausführliche Informationen sowie einfache Kurzanleitungen zu den verschiedenen Updates.

Updates der ioBroker Adapter

Die Aktualisierung der ioBroker Adapter erfolgt in der Regel über die Weboberfläche des ioBroker Admins. Unter Anderem über eine Zahl neben dem Menüpunkt „Adapter“ werden verfügbare Updates signalisiert. Über die Adapter-Übersicht lassen sich die Updates dann installieren. Soweit, so einfach.

Hinweis

Die Adapter sind im Ordner /opt/iobroker installiert, den wir ja (hoffentlich) auf den Docker-Host ausgelagert haben. Diese Tatsache erklärt auch, warum Adapter nicht aktualisiert werden wenn man den Container selbst aktualisiert!

Alternativ lassen sich die Adapter natürlich auch über die Kommandozeile aktualisierten. Weitere Infos zur Bedienung des ioBrokers über die Kommandozeile findet ihr in der offiziellen Dokumentation der Konsolenkommandos.

Update des js-controllers

Mit dem js-controller verhält es sich zuerst einmal wie mit den ioBroker-Adaptern. Er ist ebenfalls in Ordner /opt/iobroker installiert und wird nicht aktualisiert wenn man den Container über sein Image aktualisiert. Allerdings ist es aktuell nicht möglich den js-controller über die Weboberfläche des ioBroker Admins zu aktualisieren. Um den js-controller zu aktualisieren ist also zwingend die Kommandozeile zu bemühen.

Damit das Update funktioniert muss der js-controller innerhalb des laufenden Containers beendet werden. Ohne js-controller kein ioBroker, daher wird damit natürlich der gesamte ioBroker inkl. aller Adapter gestoppt.

Und hier kommen wir zu einer Besonderheit des ioBroker Containers. Während der js-controller auf anderen Systemen über den ioBroker Dienst gesteuert wird, startet er im Container „nur“ als normaler Prozess. Aus diesem Grund sind die Kommandos iobroker stop und iobroker start im Container auch teilweise ohne Funktion und sollten nicht verwendet werden!

Um den ioBroker und den js-controller innerhalb des Containers zu beenden werden über den Konsolenbefehl pkill -u iobroker kurzerhand alle Prozesse des Benutzer „iobroker“ beendet. Anschließend kann der js-controller wie auf jedem anderen Linux System aktualisiert werden.

Nach der Aktualisierung muss der ioBroker neu gestartet werden. Das geht theoretisch auch über einen Befehl, allerdings empfehle ich dringend dies einfach über den Neustart des Containers zu erledigen.

Im Detail würde sich also die komplette Prozedur des Updates über die folgenden beiden Befehle erledigten lassen:

pkill -u iobroker
iobroker update
iobroker upgrade self

Anschließend ist dann, wie bereits angesprochen, der Container zu beenden und neu zu starten.

Update des Containers

Nachdem wir jetzt alles über die Updates innerhalb des ioBrokers wissen, bleibt noch der Container selbst. Im Container, bzw. dem Image aus dem der Container gestartet worden ist, sind alle Softwarepakete enthalten die der ioBroker zum Laufen benötigt. Wenn man es nicht so ganz genau nimmt dann könnte man sagen, es ist praktisch das Betriebssystem in dem der ioBroker ausgeführt wird.

Natürlich gibt zu den einzelnen Paketen die im Container enthalten sind auch immer wieder Updates. Prominente Pakete sind zum Beispiel „node“ und „npm“, die ihr vermutlich schon aus Weboberfläche des ioBroker Admin kennt.

Wer weiß wie man in einer Linux Umgebung über die Kommandozeile Updates abruft und installiert, der kann dies im Grunde genauso auch über die Kommandozeile innerhalb des Containers tun. Zum Beispiel in etwas so:

apt-get update && apt-get upgrade -y

Ich persönlich bevorzuge allerdings einen anderen Weg, denn über Portainer ist es möglich ein Update des Containers mit wenigen Klicks einfach über die Weboberfläche zu erledigen. Dabei wird praktisch der alte Container gelöscht, die aktuelle Version des Images herunter geladen und der Container wieder neu gestartet.

Achtung

Das Update über einen neuere Version des ioBroker Docker Images funktioniert innerhalb einer Major Version (z. B. v5.x.x) problemlos.

Beim Upgrade, also dem Wechsel der Major Versions (z.B. von v4.x.x auf v5.x.x) gibt es in der Regel auch immer eine neue Major Version der node-Pakets im Image. Hier wären unter Umständen nach dem Update des Containers noch weitere Schritte innerhalb des ioBrokers notwendig damit der ioBroker wieder ordnungsgemäß funktioniert (Mehr Infos dazu in der ioBroker Doku zum Thema Node Update).

Aus diesem Grund empfehle ich ein Upgrade des Containers immer über die Funktion Backup und Restore durch zu führen. Mehr Infos zu Backup und Restore hier: ioBroker Docker Image – Backup & Restore.

Kurzanleitung: Update des Containers über Portainer

Wir öffnen also unsere Portainer Weboberfläche und öffnen mit einem Klick auf unseren ioBroker Container unter dem Menüpunkt „Containers“ die „Container details“.

Anschließend suchen wir den Button „Recreate“. Durch einen weiteren Klick öffnet sich ein Fenster in dem wir die Checkbox für „Pull latest image“ aktivieren. Mit einem Klick auf den Button „Recreate“ starten wir den Prozess.

Hinweis

Wenn ihr beim Neuerstellen des Containers Parameter ändern oder auf eine andere Version des Docker Images wechseln wollt, dann schaut euch doch mal die Funktion hinter dem Button „Duplicate/ Edit“ an.

Kleiner Tip dazu: „Duplicate/ Edit“ funktioniert am Besten wenn ihr vorher den Container beendet.

Im Grunde sollte es das gewesen sein. Ich hoffe ich habe alles berücksichtigt und nichts vergessen. Falls euch auffallen sollte, dass etwas fehlt oder mißverständlich erklärt ist, lasse es mich bitte wissen. Am Besten und schnellsten geht das über die Kommentarfnktion. Danke!

Content retrieved from: https://smarthome.buanet.de/2020/10/iobroker-docker-container-updates-upgrades/.

26. Februar 2021

ioBroker unter Docker auf der Synology DiskStation

ioBroker unter Docker auf der Synology DiskStation (ab v3)

Nachdem sich in letzter Zeit einiges zum Thema ioBroker und Docker getan hat und das alte Tutorial mittlerweile nicht mehr vollständig auf die aktuelle Docker Version gepasst hat, habe ich mich entschieden eine komplette Neuauflage zu machen. Damit wird praktisch die alte Version, welche ihr im Archiv weiterhin einsehen könnt, eins zu eins abgelöst.

Weiterhin habe ich versucht das Ganze einigermaßen übersichtlich zu gestalten und einige Teile in kleine „Mini-Tutorials“ ausgelagert. Hinweise findet ihr an den entsprechenden Stellen.

Ansonsten wünsche ich euch viel Erfolg beim Einrichten des ioBroker-Containers unter Docker und freue mich auf eure Kommentare.

Wichtige Neuerungen und Hinweise

Bevor es mit dem neuen Tutorial los geht ein kurzer Überblick über die größten Neuerungen.

Portainer als Ersatz der Docker Weboberfläche im DSM

Während ich im alten Tutorial noch die Weboberfläche innerhalb des Disk Station Managers (DSM) gelobt und verwendet habe, so fehlen mir dort mittlerweile jedoch wichtige Möglichkeiten zur Administration. So ist es mir z.B. bisher nicht gelungen dem ioBroker-Container mit Hilfe von MACVLAN über die DSM-Oberfläche eine eigene IP-Adresse zu verpassen. Mit Portainer hingegen ist das innerhalb von zwei Minuten erledigt. Weiterhin bietet Portainer eine Reihe von komfortablen Features, wie z.B. die Verwendung von Stacks und Templates, die die Erstellung von Containern in Zukunft noch einfacher machen werden. Dazu aber zu gegebener Zeit mehr in einem anderen Tutorial. Wie ihr Portainer einrichtet habe ich in euch beteits in einem separaten Tutorial gezeigt:

Portainer auf der Synology DiskStation

Änderungen im ioBroker Setup

Durch Änderungen im eigentlichen ioBroker-Setup und in der Art und Weise wie ioBroker später läuft, waren auch im Image umfangreiche Anpassungen notwendig. Durch z.B. die Verwendung eines separaten ioBroker Users ergeben sich ganz neue Anforderungen an die Rechteverwaltung innerhalb und auch außerhalb des Containers. Zu diesem Zweck wurde und wird das Startup-Script innerhalb des Containers ständig weiterentwickelt.

Mount des ioBroker-Verzeichnises

Auch hier gibt es Neuerungen. So ist es nun z.B. möglich, nein, wird es nun dringend empfohlen, beim ersten Start des Containers ein leeres oder ein mit einer bestehenden Installation gefülltes Verzeichnis in /opt/iobroker zu mounten. Den Rest erledigt dann das überarbeitete Startup-Script. Die mühsame Prozedur mit dem hin und her kopieren wird dadurch deutlich vereinfacht bzw. entfällt bei einer Neuinstallation komplett!

Neue Umgebungsvariablen zur Konfiguration des Containers

Zu den bekannten Umgebungsvariablen für z.B. die Zeitzone kommen weitere Variablen hinzu die es ermöglichen Features zu aktivieren (z.B. dem AVAHI-Daemon) oder zusätzlich benötigte Linux-Pakete zu installieren. Aktuelle Informationen zu den möglichen Variablen finden sich immer im Readme auf Github.

Voraussetzungen und Vorbereitungen

Im Gegensatz zum alten Tutorial starten wir dieses Mal nicht sofort durch. Bevor wir den eigentlichen ioBroker-Container mit wenigen Klicks erstellen können, sind ein paar Vorbereitungen zu treffen.

Systemvoraussetzungen

Wie der Titel es schon vermuten lässt, habe ich dieses Tutorial ursprünglich für die Installation von ioBroker unter Docker auf einer Synology Disk Station geschrieben. Es wäre also nicht verkehrt wenn ihr eine konfigurierte Disk Station mit installiertem Docker-Paket euer eigen nennen würdet. Allerdings ist das diesmal kein Muss! Ich teste zum Beispiel meine Builds zusätzlich zur DS auch immer auf einem ganz normalen Debian PC mit installiertem Docker CE. Trotzdem beziehe ich mich in diesem Tutorial grundsätzlich in erste Linie auf die Installation auf der DS, werde aber an einigen Stellen entsprechende Anmerkungen machen wenn Schritte auf anderen Systemen deutlich abweichen. 🙂

Eine weitere Voraussetzung für das Gelingen dieses Tutorials ist die Installation von Portainer als alternative Weboberfläche zur Administration von Docker. Dazu habe ich im Vorfeld bereits ein Tutorial veröffentlicht welches beschreibt wie man Portainer auf die DS bringt. Keine Angst, bei Portainer handelt es sich lediglich um einen weiteren Docker-Container. Es ist also kein komplizierter Eingriff auf der DS nötig. Benutzer die keine DS verwenden, müssen an dieser Stelle höchstwahrscheinlich die Kommandozeile bemühen. Anleitungen zum Aufsetzen von Portainer auf einem „normalen“ Docker-PC gibt es zu genüge im Netz.

Verzeichnisstruktur

Docker-Container sind per Definition zu 100% austauschbare Hüllen für die darin laufende Software. Dies bedeutet wir müssen uns Gedanken darüber machen welche (Konfigurations-)Daten wir außerhalb des Containers speichern sollten um nicht bei jedem Update des Containers neu anfangen zu müssen.

Im Fall von ioBroker ist das relativ einfach. Das Verzeichnis /opt/iobroker beinhaltet sämtliche Konfigurationsdateien von ioBroker und seinen Adaptern. Dieses Verzeichnis sollten wir also auf jeden Fall außerhalb des Docker-Containers lagern. Wie euch aus meinem Portainer Tutorial bereits bekannt sein sollte, habe ich für die Container-Daten auf der DS eine einfache Ordnerstruktur angelegt. Diese befindet sich bei mir auf „volume1“ im Ordner „docker“. Hier lege ich über die FileStation für jeden Container einen Order nach folgendem Schema an /volume1/docker/[containername]_[bezeichnung]. Bei Portainer war es …/portainer_data. Auch für ioBroker ist das nicht anders. Mein Verzeichnis heißt hier …/iobroker_data (Im alten Tutorial hieß das Verzeichnis übrigens noch „iobroker_mount“).

Netzwerk

Immer wieder ein spannendes Thema unter Docker weil leider nicht ganz trivial. Prinzipiell sind zu diesem Thema drei Varianten relevant: Bridge, Host oder MACVLAN.

Welche Variante ihr verwendet bleibt euch überlassen. Die einfachste ist sicher der Host-Modus. Ich persönlich bevorzuge die MACVLAN-Variante, wenngleich ich diese nur den fortgeschrittenen Benutzern empfehlen würde. Hierbei sind nämlich gute Kenntnisse des eigenen Heimnetzwerks sowie der Netzwerkkonfiguration der DiskStation (Stichwort: Network-Device-Name) unerlässlich. Schaut euch am Besten mal mein Tutorial dazu an und entscheidet ob ihr das ggf. auch so hin bekommt:

MACVLAN über Portainer einrichten

Mit dem Bridged Mode kann man als Einsteiger nicht viel falsch (kaputt) machen. Als Nachteil ist hier aber zu sehen, dass jeder benötigte Port separat als Weiterleitung im Container eingetragen werden muss. Außerdem gilt für den Bridged Mode der Hinweis, dass Adapter die per Multicast arbeiten hier nicht funktionieren werden.

Außerdem gibt es die Möglichkeit den ioBroker im selben Netz wie den Host zu betreiben. Das ist auf aktuellen Linux-Hosts auch kein Problem. Die Synology Disk Stations arbeiten im DSM allerdings mit einem veralteten Linux Kernel in dem es einen bekannten Bug gibt. Der Bug verhindert die Ausführung von sudo im Container. Für den Normalbetrieb geht das ist Ordnung (Habe ich im Image gefixt) sobald es aber z.B. um das Update des js-controllers geht gibt es Probleme. Aus diesem Grund empfehle ich auf den Host Modus beim Einsatz einer Synology DiskStation zu verzichten.

Übernahme von ioBroker Daten aus anderem System

Natürlich ist die Datenübernahme aus einem bereits laufenden ioBroker ein wichtiges Thema. Meine Empfehlung: Backup und Restore.

Der ioBroker bringt von Haus aus eine Backup-Funktion mit die auch über einen Adapter getriggert werden kann. Ich habe zu diesem Thema ebenfall ein kleines Tutorial verfasst. Die Datenübernahme ist also praktisch ein simpler Restore. Mehr Infos dazu hier:

ioBroker Docker Container – Backup & Restore

Damit sollten dann alle Voraussetzungen erfüllt sein und wir können den ioBroker Container erstellen.

Neuen Docker Container erstellen

OK, nachdem wir alle Voraussetzungen geklärt haben, sollte das Erstellen des Containers keine große Hürde mehr darstellen. Los geht es natürlich in der Portainer-Weboberfläche unter dem Punkt: „Containers“.

Über den Button „Add container“ gelangen wir in ein Formular. Auch hier sind wieder einige Felder zu füllen.

Als Namen vergeben wir zunächst einen aussagekräftigen Namen. Ich schlage „iobroker“ vor (bei mir im Testumfeld „iobrokertest“).

Das Image beziehen wir aus der Registry „DockerHub“ und es heißt „buanet/iobroker:latest“. Auch wenn wir es bisher nicht geladen haben, können wir es hier hinterlegen. Beim Erstellen des Containers wird das Image automatisch heruntergeladen. Achtung: Das könnte etwas Zeit in Anspruch nehmen! Unter „Images“ könnte man das Image vorab herunterladen (Stichwort: pull).

Für den Fall dass ihr den ioBroker im Bridged Modus laufen lassen wollt, müssen im Bereich „Ports configuration“ die Port-Weiterleitungen für die von eurem ioBroker und seinen Adaptern verwendeten Ports eingerichtet werden. Für den Admin-Adapter ist das z.B. der Port 8081.

In meinem Fall werde ich die MACVLAN-Konfiguration verwenden, welche ich bereits etwas weiter oben angesprochen habe. Daher brauche ich an dieser Stelle keine Ports mappen (weiterleiten).

Den Bereich „Access control“ können wir einfach ignorieren oder falls gewünscht natürlich auch entsprechend konfigurieren.

Scrollen wir nun nach unten finden wir einen Button „Deploy the container“. Diesen drücken wir aber noch nicht! Zuvor konfigurieren wir noch ein paar „Advanced container settings“.

Erster wichtiger Punkt hier: Volumes. Hier mounten wir unser lokales Verzeichnis in den ioBroker, damit unsere Daten lokal auf der DS bleiben und nicht aus Versehen mit dem Container gelöscht werden können. Dazu hatten wir ja bereits eine Ordnerstruktur angelegt, welche wir jetzt wie folgt einbinden.

Durch Klick auf „map additional volume“ erscheinen zwei neue Felder. Im ersten Feld tragen wir den Pfad innerhalb des Containers /opt/iobroker ein und wählen anschließend den Button „Bind“. Im zweiten Feld tragen wir den lokalen Pfad auf der DS ein. Dieser sollte natürlich „Writeable“ (beschreibbar) sein.

Dann ist das Netzwerk an der Reihe. Hier wählen wir unser Netzwerk aus, in das wir unseren ioBroker einbinden wollen. In meinem Fall ist dies das vorab angelegte MACVLAN Netzwerk „iob_public“. Als Hostname schlage ich wieder „iobroker“ vor (bei mir entsprechend „iobrokertest“). Weitere Einstellungen müssen hier nicht getätigt werden.

Unter „Env“ können wir nun optional Einfluss auf die Umgebungsvariablen zur Containerkonfiguration nehmen. In meinem Fall habe ich zu Demonstrationszwecken mal die beiden variablen „AVAHI=false“ und „PACKAGES=nano“ gesetzt. Weitere Informationen zu verwendbaren Variablen gibt es hier in der Readme auf Github.

Das sollten dann auch die wesentlichen Einstellungen gewesen sein. Natürlich könnt ihr nach Bedarf auch noch weitere Optionen konfigurieren. Für unseren Fall sollte das hier aber reichen und wir können endlich den Button „Deploy the container“ betätigen.

Container prüfen

Je nachdem ob Portainer nun das Image noch laden muss, kann der Prozess eine Weile dauern. Im Anschluss sollte der neu erstellte Container in der Containerliste auftauchen.

Mit einem Klick auf den Containernamen in der Liste könnt ihr euch weitere Informationen zum Container anzeigen lassen. Wenn es unter „Stats“ so

und unter Logs in etwa so

aussieht, dann hat wahrscheinlich alles geklappt und ihr könnt den ioBroker-Admin über den bekannten Weg „http://[name_des_hosts]:8081“ oder „http://[IP-Adresse]:8081“ aufrufen.

Hinweis

Der erste Start des Containers kann unter Umständen auch mal Minuten brauchen. Ursache ist das Startupscript das diverse Aufgaben ausführt. Sollte also euer ioBroker-Container laut Portainer laufen, ihr aber die Weboberfläche nicht erreichen, schaut bitte in die Logs des Containers (siehe etwas weiter oben), hier könnt ihr sehen wie weit das Startupscript ist und ob ioBroker schon gestartet wurde.

Updates und Backup

Jetzt läuft er also, unser neuer ioBroker-Container. Aber was nun? Ganz klar, erst einmal Adapter installieren und einrichten (worauf ich hier nicht weiter eingehen werde). Und dann? Was kommt sonst in Zukunft noch auf uns zu?

Schnell werdet ihr wohl bei den Themen „Updates & Upgrades“ sowie „Backup & Restore“ landen. Für diese Beiden Themenbereiche habe ich bereits separate Tutorials verfasst. Schaut doch als Nächstes einfach mal dort vorbei.

ioBroker Docker Container – Updates & Upgrades

ioBroker Docker Container – Backup & Restore

Zugriff auf die Konsole des Containers

Es soll ja vorkommen, dass man mal über die Konsole Zugriff auf den ioBroker benötigt. Auch dies können wir über Portainer bewerkstelligen. Dazu einfach in den „Container details“ das Konsolenzeichen mit der Beschriftung „Console“ suchen und klicken. Im nächsten Fenster können wir dann mit einem weiteren Klick auf „Connect“ eine Session öffnen. Die Voreinstellungen können wir so übernehmen wie sie sind.

Links und Ressourcen

Im folgenden nun noch ein paar Infos und weiterführende Links zum Thema.

Quellcode und Docker-Image

Wer sich für den Quellcode zum Docker-Image interessiert, der wird in meinem Github-Repo fündig. Das fertige Image wird letztendlich in den Docker Hub gepusht und kann von dort in jegliche Docker-Installation herunter geladen werden.

Allgemeines zu Docker und Synology DiskStation

Allgemeine Infos und Grundlagen zu Docker findet ihr auf docker.com oder auch bei Wikipedia. Wärmstens empfehlen, aber leider nur in Englisch verfügbar, kann ich außerdem die offizielle und sehr umfangreiche Docker-Dokumentation.
Infos zum Docker-Paket für die Synology DiskStation gibt es natürlich auf der Webseite von Synology.

Support

In Sachen Support kann ich nur immer wieder auf den tollen Support im ioBroker-Forum hinweisen. Mittlerweile haben wir auch eine recht starke Docker-Fraktion die sich viel Mühe gibt aufkommende Fragen zuverlässig zu beantworten und bei Bedarf Unterstützung zu geben. Erstes Anlaufziel bei Fragen zum Tutorial sollte für euch mein ioBroker-Forum-Threat sein. Für kurze, einfache Problemchen bietet sich zwar auch die Kommentarfunktion unter diesem Tutorial an. Wenn es dann allerdings um Screenshots und Logfiles geht, sind die Möglichkeiten an dieser Stelle leider sehr begrenzt.

Bleibt mir eigentlich nur noch, euch viel Spaß beim experimentieren mit ioBroker zu wünschen. Für Kritik, Fragen und Anregungen steht euch wie immer die Kommentarfunktion zur Verfügung.

Content retrieved from: https://smarthome.buanet.de/2019/05/iobroker-unter-docker-auf-der-synology-diskstation-v3/.

26. Februar 2021