GSD NETframe für zuhause und unterwegs

Das Produkt NETframe® kennen vermutlich nicht viele. Es enthält eine Rest API für die Produkte der GSD Software mbH.

Mit NETframe können Daten aus DOCUframe® abgrefragt und hochgeladen werden. Damit die Einrichtung möglichst einfach geht habe ich mir dafür ein docker-compose file erstellt. Das git repo kann ich interessierten GSD Partnern gerne zur Verfügung stellen.

Mit einem git clone ssh://dont-tell-you/netframe.git  lädt man alle erforderlichen Dateien herunter.

Hinweis: Auch der ma-web-service ist jetzt integriert.

Der Container „restapi“

In diesem Container läuft die eigentlich REST Schnittstelle. Er verbindet sich zum GSD Fernzugriffsserver (der unter Windows läuft). Es gibt drei Konfigurationsdateien die für die korrekte Funktion angepasst werden müssen.

  • docker-compose.yml
  • api-config.json
  • cifs

docker-compose.yml

  1. Hier muss die environment Variable NETFRAME_TMPSHARE auf die tmp Freigabe der GSD-RestApi zeigen.
  2. VIRTUAL_HOST enthält den Namen unter dem der Rest-Service später angesprochen wird. Details dazu findet ihr weiter unten im Text. Auch wie man LETSENCRYPT_HOST nutzt.

cifs.sample

Die cifs.sample dient als Vorlagendatei. Sie muss in eine Datei cifs (ohne Endung) umkopiert werden. Hier werden die Windows-Anmeldedaten für die NETFRAME_TMPSHARE hinterlegt. Benutzername, Kennwort und Domäne:

api-config.json.sample

Auch die api-config.json.sample dient als Vorlagendatei. Sie muss in eine Datei api-config.json umkopiert werden. Hier wird der REST Dienst konfiguriert. Die aus meiner Sicht immer zu ändernden Werte habe ich in der Konfigdatei noch oben sortiert.

Sind die Anpassungen erfolgt kann die Erstellung und der erste Start der eigentlich Container mit docker-compose up  eingleitet werden.  Wichtig: Man muss im Ordner (oder einem Unterordner) der Datei docker-compose.yml stehen, wenn man docker-compose Kommandos absetzt. Ein um ein -d ergänztes docker-compose up -d gibt nach den Start auch die Eingabekonsole frei. Die Container laufen nun auch weiter wenn man das Terminal beendet.

Die REST Schnittstelle ist jetzt unter netframe.lan (oder dem unter VIRTUAL_HOST gewählten Hostname) funktionstüchtig.

Portainer Übersicht „netframe stack“

VIRTUAL_HOST und Let’s encrypt?

Zwei Container aus dem Setup sind noch nicht besprochen: nginx-proxy und letsencrypt

Den Container nginx-proxy gibt es aus zwei Gründen

  • Der Container mit der restapi ist nicht direkt aus dem LAN und WAN erreichbar. Erster Ansprechpunkt ist der nginx-proxy.
  • Für den Fall, dass man den restapi Container skalieren muss wird nginx automatisch die Last auf alle laufenden restapi Container verteilen
  • Der Container nginx-proxy kann zusammen mit dem container lets-encrypt-companion automatisch SSL Zertifikate für den VIRTUAL_HOST erstellen und erneuern.

Für den Betrieb ohne SSL reichen die gemachten Einstellungen.  Wichtig ist nur, dass man die REST Schnittstelle über den Namen anspricht der in VIRTUAL_HOST eingetragen ist (z.B. http://netframe.lan/v1/login) . Die IP des Server ist NICHT möglich. Der nginx prüft den Namen in der URL!

Die Rest API für die Nutzung aus dem Internet freigeben und mit Let’s Encrypt SSL/TLS verschlüsseln

Wenn man ein Let’s Encrypt Zertifikat nutzen möchte sind einige Voraussetzungen zu erfüllen:

  • Man hat einen öffentlich DNS Namen als VIRTUAL_HOST erstellt
  • Unter den Ports 80 und 443 ist der nginx-proxy erreichbar. Das heisst schlicht, das die beiden Ports auf die interne IP des docker hosts (linux server) weitergeleitet werden müssen.
  • LETSENCRYPT_HOST enthält den gleichen Wert wie VIRTUAL_HOST
  • In LETSENCRYPRT_EMAIL ist die E-Mailadresse des technischen Ansprechpartners für das Zertifikat. Sollte es Probleme mit der Verlängerung geben sendet Let’s Encrypt an diese E-Mail alle Hinweise.

Wenn man das sichergestellt hat, sehen die Einträge im docker-compose.yml ungefähr so aus:

Die Umgebungsvariable LETSENCRYPT_Host ist jetzt nicht auskommentiert (# entfernt). Dadurch weiss nun der let’sencrypt companion, dass er ein SSL Zertifikat für dies Hostname beschaffen soll und der nginx-proxy wird entsprechend umkonfiguriert sobald das erfolgt ist.

Ein grosser Vorteil ist, dass man nun den restapi Container updaten kann ohne sich über die SSL Verschlüsselung Gedanken machen zu müssen. Die wird durch den nginx-proxy durchgeführt. Von proxy aus erfolgt die Anfrage dann auch nicht mehr per SSL an den restapi, da hier das interne LAN des docker hosts genutzt wird.

Ein Update der netapi ?

die restapi muss natürlich auch mal aktualisiert werden. Dazu die net-api mit allen zugehörigen Dateien auf dem linux docker host in den ordner netframe/netapi entpacken (da liegt bereits von mir eine net-api – alles überschreiben) und prüfen, dass das Execute-Flag für die net-api gesetzt ( chmod +x net-api).

Dann den Container neu erstellen und starten:  docker-compose up -d --force-recreate --no-deps --build restapi

Vorausgesetzt es gibt keine weiteren Änderungen die erforderlich sind (z.B. api-conf.json ergänzen / anpassen) war es das schon.

Ist das Bereit für den Produktivbetrieb?

Die kurze Antwort: Nein.

Die lange Version:
Zum einen sind noch Veränderungen an der REST Api des NETframe möglich. Zum anderen fehlt den Containern noch eine Funktionsüberwachung, Fehlerbehandlung und auch so einfache Dinge wie die Vorgabe, dass die Container nach einem Reboot des Hosts auch neugestartet werden (restart policy) .

Ohne Störeinflüsse von außen (z.B. Netzwerkstörungen) läuft das System sehr stabil.

Links

Kommentar verfassen

Deine E-Mail-Adresse wird nicht veröffentlicht. Erforderliche Felder sind mit * markiert.