Erstinstallation - Windows

Das folgende Video zeigt Ihnen alle notwendigen Schritte, die nötig sind, um die smartWARE Evaluation auf einem Windows-Betriebssystem installieren zu können.

Sollten Sie einen Windows-Server nutzen, müssen Sie diesen auf WSL2 (Windows Subsystem for Linux) Unterstützung prüfen. WSL2 ist die Voraussetzung zur Lauffähigkeit der smartWARE Evaluation auf einem Windows-Betriebssystem.

https://youtu.be/eX9vEU6djZ8

Sie schauen lieber Videos anstatt zu lesen, dann ist das obige genau richtig für Sie.

Erstinstallation

Die Software wird mit Hilfe der Windows Installation direkt in das Linux Dateien System von Windows installiert (WSL2)!
Kopieren Sie das Installationsfile in ein beliebiges Verzeichnis auf Ihrem Windows OS
(z.B. c:\Temp\smartWARE_452.5.0.0.14.exe).
Nach dem Starten der ausführbaren Datei per Doppelklick oder in der Windows Konsole (smartWARE_452.5.0.0.14.exe) öffnet sich eine Windows Command Shell:

Mit dem Betätigen einer beliebigen Taste wird der Installationsvorgang gestartet.
Jetzt startet das Installationsskript und Sie werden folgende Ausgaben im Terminal sehen.

Da für die Installation root (sudo) Rechte notwendig sind, werden Sie nach dem Passwort gefragt. Geben Sie das Passwort ein, welches Sie während der WSL Ubuntu Installation vergeben haben, damit die Installation gestartet werden kann. Die erforderlichen Dateien werden in das Verzeichnis /tmp entpackt und anschließend in das Zielverzeichnis ~/smartWARE_452.5.0.0.14 kopiert. (Hinweis: "~/" ist die Kurzform des home Verzeichnis des Benutzers "user", also "/home/user")

Um mit dem Internet-Browser per HTTPS auf die Anwendung zugreifen zu können, erzeugt das Installationsskript ein selbst signiertes Zertifikat. Dieses Zertifikat kann später durch ein offizielles Zertifikat (falls vorhanden) ersetzt werden (siehe Basiskonfiguration).

Die Windows Installation ist mit dem Betätigen einer beliebigen Taste am Ende des Installationsvorgangs abgeschlossen.
Alle weiteren Schritte werden nun in der Command Shell vom Ubuntu (bash) durchgeführt.
Starten Sie nun das Windows Terminal.

Sollte das Terminal noch nicht installiert sein, wird die Installation des Terminals mittels dem Microsoft Store
vorgenommen.

Im Suchfeld "Terminal" eingeben und "Windows Terminal" auswählen und installieren.

Bitte beachten Sie, dass automatisch nach dem Starten des Terminal-Programms eine "Windows PowerShell"
geöffnet wird. Zur Installation benötigen wir jedoch einen Linux Terminal. Aus diesem Grund öffnen Sie jetzt
zusätzlich ein Linux Terminal (Ubuntu-20.04):

Folgende Verzeichnisse wurden durch das Skript auf dem Ubuntu (WSL2) jetzt neu erstellt:

Das Verzeichnis ~/smartWAREData/ enthält alle persistenten Daten der Anwendung. Hier werden also alle Daten gespeichert, die auch nach einem Software-Update weiter erhalten bleiben müssen, wie zum Beispiel die von den Jupiter Geräten übertragenen Messwerte, Benutzereinstellungen, wie Dashboards oder Geräteplatzinformationen. Für den Zugriff benötigt man als Benutzer "root" Rechte .

Das Verzeichnis ~/smartWARE_452.5.0.0.14/ enthält alle Skripte, die zum Betrieb der Anwendung nötig sind. Z.B.: Start- und Stop-Skript zum Starten bzw. Stoppen der Docker Services. In diesem Verzeichnis können auch individuelle Einstellungen in einer .env Datei konfiguriert und gespeichert werden. Mehr dazu unter dem Kapitele Basiskonfiguration.

Basiskonfiguration

Nach dem Ausführen des Installationsskripts können die Services gestartet werden. Die Services werden dann mit folgenden Standardeinstellungen gestartet.

Die Services werden dann mit folgenden Standardeinstellungen gestartet.
Default Einstellungen

Diese Einstellungen werden im Installationsverzeichnis der Software (~/smartWARE_452.5.0.0.14) in einer Datei mit dem Namen .env gespeichert. Um diese Datei zu erzeugen oder zu ändern, kann das Skript ~/smartWARE_452.5.0.0.14/config_smartware.sh verwendet werden. Mittels der textbasierenden Menüführung können die Parameter leicht geändert werden.

Zum Speichern der neuen Einstellungen den Menüpunkt Save/Exit auswählen.

Das erzeugte .env File wird unter ~/smartWARE_452.5.0.0.14/.env gespeichert.

Die Einstellungen werden mit dem nächsten Start in das System übernommen.
~/smartWARE_452.5.0.0.14/stop_smartware.sh
~/smartWARE_452.5.0.0.14/start_smartware.sh

Wurden die Ports geändert, muss dann aber im Browser beim Zugriff auf die GUI der Port mit angegeben werden. Das wäre in diesem Fall:

http://ip:80802
https://ip:84433

Dieser geänderte Port muss dann auch im Datastore Gateway der Jupiter Geräte korrekt eingestellt
werden! In diesem Fall wäre der Port für das HTTP Protocol anzugeben. (Hinweis: Das HTTPS Protokoll
im Jupiter Gerät wird erst mit Firmware Version 8.x unterstützt! Eine Installation der smartWARE
Evaluation Software im Internet auf einem Cloudrechner sollte also erst mit der HTTPS Unterstützung der Firmware 8.x erwogen werden.) ip:8080/store4

Selbstsigniertes Zertifikat ersetzen

Während der Installation wird ein selbst signiertes Zertifikat erzeugt und in das Verzeichnis ~/smartWAREData/reverse_proxy/certs kopiert. Wenn Sie die Software GUI im Browser über das HTTPS Protocol öffnen, werden Sie vom Browser eine Warnung bekommen, da das Zertifikat selbst signiert ist. Hier ein Beispiel des Chrome Browsers:

Diese Warnung können Sie aber ignorieren, da das selbst signierte Zertifikat dem Browser nicht bekannt ist. Klicken Sie dazu auf den Link "weiter zu... (unsicher)". Die Warnung der Browser kann man aber auch dadurch verhindern, indem man ein offiziell signiertes Zertifikat benutzt bzw. diese der Software zur Verfügung stellt. Im Verzeichnis ~/smartWAREData/reverse_proxy/certs liegen 2 Dateien

• smartware.crt

• smartware.key

Der Austausch dieser Dateien kann nur als root User erfolgen (sudo). Diese Zertifikat und Key Dateien können durch firmeneigene offiziell signierte Dateien ersetzt werden. Dazu die smartWARE Services stoppen (siehe 5.2). Die beiden vorhandenen Dateien umbenennen (z.B. in smartware.ctr_original , smartware.key_original). Dann die offiziell signierten Dateien kopieren und gegebenenfalls umbenennen. Wichtig, die Dateien müssen die Namen smartware.crt und smartware.key haben und müssen ein PEM/X509 Format sein.
Bitte nach dem Austausch der Dateien und dem Starten der smartWARE Services (siehe 5.1) die Log Datei kontrollieren, um zu überprüfen, dass die ersetzten Dateien keine Probleme erzeugen:

$ cat ~/smartWAREData/reverse_proxy/error.log | more

Updateinstallation

Die Updateinstallation unterscheidet sich nicht von der Erstinstallation. Somit gelten die Kapitel 3 und 4 auch für ein Update. Bereits vorhandene Konfigurationsdateien (z.B. File .env) werden in die neue Installation übernommen. Das Stoppen der alten Installation und das erneute Starten der neuen Installation werden vom Installationsskript durchgeführt.

Betrieb

Die smartWARE Evaluation Software besteht aus mehreren einzelnen Programmen (auch als Microservices bezeichnet). Diese Programme werden als Docker Container gestartet. Zum einfachen Starten und Stoppen der Services befinden sich im Verzeichnis:
~/smartWARE_452.3.0.0.7
zwei Linux shell Dateien
start_smartware.sh
stop_smartware.sh

Starten der Services

Wechseln Sie in der Linux Konsole in das Verzeichnis ~/smartWARE_452.3.0.0.7 und starten Sie das Skript ./start_smartware.sh:

$ ./start_smartware.sh

Die Eingabe der Zeichenkombination ./ (also ein Punkt gefolgt von einem Schrägstrich) ist notwendig, da Linux die Datei sonst nicht findet. Es zeigt Linux, dass sich die Datei im aktuellen Verzeichnis befindet.

Wenn Sie dieses Skript nach der Installation das erste Mal aufrufen, werden zuerst die Softwarepakete (Images) vom JUMO Server geladen. Danach werden die einzelnen Services als Docker Container gestartet. Sie können den aktuellen Status der Services sehen durch das Starten eines weiteren Shell Scripts.

$ ./status_smartware.sh

Jetzt sollten Sie eine Liste angezeigt bekommen, die Ihnen den Status der einzelnen Services anzeigt:

Wenn alle Services den State Up zeigen, laufen die Services. Nun kann man im Browser die Startseite öffnen mit http://IP oder https://IP.

Wobei IP für die IPv4 Adresse des W10 PC steht, auf dem die Services gestartet wurden. Sie können aber auch statt der IP Adresse den Hostnamen des Rechners benutzen oder http://localhost, wenn der Browser auf dem selben Rechner gestartet wurde. Falls die Ports 80/433 schon durch ein anderes Programm benutzt werden und Sie Ausweich-Ports durch Einträge in der .env Datei konfiguriert haben, so hängen Sie bitte diesen Port an die URL an, z.B. http://localhost:8080 oder https://localhost:8433.

Stoppen der Services

Um Änderungen der .env Dateien zu übernehmen, ist es notwendig, die einzelnen Services geordnet zu beenden, bevor man sie erneut starten kann. Dazu rufen Sie auf der Linux Console das Skript ./stop_smartware.sh Shell auf.

$ ./stop_smartware.sh

Es dauert einige Sekunden, bis alle Services beendet sind. Sie sehen folgende Ausgabe am Bildschirm:

VHDx Datei

Bitte vor folgenden Änderungen immer die smartWARE Services wie beschrieben beenden.

Verschieben

Windows Docker Desktop installiert per Default alles auf Platte C:.
Beispiel: Verschieben der Ubuntu-20.04 VHDx auf Laufwerk E:.
Zum Verschieben der Ubuntu VHDx Datei auf eine zweite interne größere SSD sind folgende Schritte notwendig:
Öffnen Sie als Administrator eine Windows Powershell und zeigen Sie alle Distributionen an:

❯ wsl --list

Windows-Subsystem für Linux-Distributionen:
Ubuntu-20.04 (Standard)
docker-desktop
docker-desktop-data

Das Verschieben der Distribution geschieht in folgenden Schritten.

• Die Distribution wird in eine .tar Datei exportiert auf der SSD E:.

• Die Distribution wird abgemeldet.

• Die exportierte Distribution wird importiert aus der .tar Datei auf der neuen SSD E:.

• Nach erfolgreichem Import kann die .tar Datei gelöscht werden.

wsl --export Ubuntu-20.04 E:\ubuntu.tar
wsl --unregister Ubuntu-20.04
Registrierung wird aufgehoben…
wsl --import Ubuntu-20.04 E:\Docker\wsl\Ubuntu-20.04\ E:\ubuntu.tar --version 2

Damit ist die Ubuntu Distribution auf Laufwerk E:\Docker\wsl\Ubuntu-20.04\ verschoben. Zum Testen eine Ubuntu Shell öffnen und überprüfen. Wenn alles ok ist, kann die Datei E:\ubuntu.tar gelöscht werden.

Falls nach dem Starten der "root" user der default user sein sollte, ist folgendes zu tun:
In der Datei /etc/wsl.conf muss der Default user eingetragen werden:
[user] default=hier_mein_default_username_eintragen
Danach muss man in der Powershell "wsl --shutdown" durchführen, damit die Änderung aktiv wird.

Maximale Größe erhöhen

Die WSL 2-VHDx verwendet das Ext4-Dateisystem. Diese VHDx wird automatisch an ihre Speicheranforderungen angepasst und verfügt über eine anfängliche maximale Größe von 256 GB. Wenn der von den Linux-Dateien benötigte Speicherplatz diese Größe überschreitet, muss man ihn eventuell erweitern. Wenn die Distribution über die Größe von 256 GB anwächst, werden Fehler angezeigt, die besagen, dass kein Speicherplatz mehr zur Verfügung steht. Man kann diesen Fehler beheben, indem Sie die Größe der VHDx heraufsetzen, falls die physikalische Platte auch groß genug ist. Das folgende Beispiel bezieht sich auf eine Ubuntu Distribution vhdx, die schon auf ein anderes Laufwerk (E:) verschoben wurde! Die Größe wird dabei von 256GB auf 356GB erhöht.
maximum=356000
Eine Powershell öffnen:

PS C:\WINDOWS\system32> wsl --shutdown
PS C:\WINDOWS\system32> diskpart
Microsoft DiskPart-Version 10.0.19041.610
Copyright (C) Microsoft Corporation.
Auf Computer: EW-TEST
DISKPART> Select vdisk file="E:\Docker\wsl\Ubuntu-20.04\ext4.vhdx"
Die Datei für virtuelle Datenträger wurde von DiskPart erfolgreich ausgewählt.

DISKPART> detail vdisk
Geträtetyp-ID: 0 (Unbekannt)
Hersteller-ID: {00000000-0000-0000-0000-000000000000} (Unbekannt)
Status: Hinzugefügt
Virtuelle Größe: 256 GB
Physische Größe: 27 GB
Dateiname: E:\Docker\wsl\Ubuntu-20.04\ext4.vhdx
Ist untergeordnet: Nein
Übergeordneter Dateiname:
Zugeordnete Datenträgernummer: Nicht gefunden.

DISKPART> expand vdisk maximum=356000
100 Prozent bearbeitet
Die Datei für virtuelle Datenträger wurde von DiskPart erfolgreich expandiert.
DISKPART> exit

Jetzt die Ubuntu Distribution starten und in die Linux Shell wechseln:

df -h
Filesystem  Size  Used  Avail   Use%  Mounted on
/dev/sdb    251G  28G   211G    12%   /
tmpfs       3.1G  0     3.1G    0%    /mnt/wsl
tools       454G  273G  182G    61%   /init
none        3.1G  0     3.1G    0%    /dev
none        3.1G  4.0K  3.1G    1%    /run
none        3.1G  0     3.1G    0%    /run/lock
none        3.1G  0     3.1G    0%    /run/shm
none        3.1G  0     3.1G    0%    /run/user
tmpfs       3.1G  0     3.1G    0%    /sys/fs/cgroup
C:\         454G  273G  182G    61%   /mnt/c
E:\         466G  109G  358G    24%   /mnt/e

sudo resize2fs /dev/sdb 356000M

[sudo] password for user:
resize2fs 1.45.5 (07-Jan-2020)
Filesystem at /dev/sdb is mounted on /; on-line resizing required
old_desc_blocks = 32, new_desc_blocks = 44
The filesystem on /dev/sdb is now 91136000 (4k) blocks long.

df -h
Filesystem  Size  Used  Avail   Use%  Mounted on
/dev/sdb    342G  28G   298G    9%    /
tmpfs       3.1G  0     3.1G    0%    /mnt/wsl
tools       454G  273G  182G    61%   /init
none        3.1G  0     3.1G    0%    /dev
none        3.1G  8.0K  3.1G    1%    /run
none        3.1G  0     3.1G    0%    /run/lock
none        3.1G  0     3.1G    0%    /run/shm
none        3.1G  0     3.1G    0%    /run/user
tmpfs       3.1G  0     3.1G    0%    /sys/fs/cgroup
C:\         454G  273G  182G    61%   /mnt/c
E:\         466G  109G  358G    24%   /mnt/e

Hintergrundinformation

Begriffserklärung

• Docker: Legt Programme samt ihrer Abhängigkeiten in Images ab. Diese bilden die Basis für virtualisierte Container, die auf nahezu jedem Betriebssystem lauffähig sind. So werden Anwendungen portabel und unkompliziert.

• Docker Desktop: Docker Desktop ist eine einfach zu installierende Anwendung für eine Windows- Umgebung, mit der containerisierte Anwendungen und Microservices erstellt und verteilt werden können. Docker Desktop umfasst Docker Engine, Docker CLI-Client, Docker Compose, Docker Content Trust, Kubernetes und Credential Helper.

• Docker Compose: Docker Compose ist ein Tool, das zum Definieren und Freigeben von Multicontaineranwendungen entwickelt wurde. Mit Compose können Services definieren werden, die dann mit einem einzigen Befehl gestartet bzw. beenden können.

• Docker Image: Der Begriff „Image“ ist Ihnen im Zusammenhang mit Virtualisierung möglicherweise von virtuellen Maschinen (VMs) bekannt. Für gewöhnlich handelt es sich bei einem VM-Image um eine Kopie eines Betriebssystems. Ggf. enthält ein VM-Image weitere installierten Komponenten wie Datenbank und Webserver. Der Begriff entstammt einer Zeit, in der Software auf optischen Datenträgern wie CD-ROMs und DVDs verteilt wurde. Wollte man eine lokale Kopie des Datenträgers anlegen, erstellte man mit einer speziellen Software ein Abbild, auf Englisch „Image“. Bei der Container-Virtualisierung handelt es sich um die konsequente Weiterentwicklung der VMVirtualisierung. Anstatt einen virtuellen Computer (Maschine) mit eigenem Betriebssystem zu virtualisieren, umfasst ein Docker-Image in der Regel lediglich eine Anwendung. Dabei kann es sich um eine einzelne Binärdatei handeln oder um einen Verbund mehrerer Software-Komponenten.

• Docker Container: Die Virtualisierungs-Lösung Docker hat im Verlauf des letzten Jahrzehnts grundlegend verändert, wie Software gebaut, verteilt und betrieben wird. Anders als bei den zuvor etablierten virtuellen Maschinen (VM) werden mit Docker einzelne Anwendungen virtualisiert. Bei einem Docker-Container handelt es sich also um einen Anwendungs- oder Software-Container. Der Begriff des Software-Containers ist angelehnt an physische Container, wie sie auf Schiffen eingesetzt werden. In der Logistik haben Container als standardisierte Einheit die modernen Handelsketten erst ermöglicht. So lässt sich ein Container auf jedem dafür ausgelegten Schiff, Lkw oder Zug befördern. Dies funktioniert weitgehend unabhängig vom Inhalt des Containers. Nach außen hin ist der Container mit standardisierten Schnittstellen versehen. Ganz ähnlich ist dies auch bei Docker-Containern der Fall.

• VHDx Datei: In einer VHDx-Datei lässt sich der Inhalt einer kompletten Festplatte virtuell in Form einer einzigen Datei speichern. Das Dateiformat ist eine Erweiterung des VHD-Formats und wurde erstmals mit Windows 8 und Windows Server 2012 veröffentlicht. Es bietet gegenüber dem VHD-Format zahlreiche Verbesserungen und Funktionserweiterungen.

Software Struktur

Die smartWARE Evaluation Software besteht im wesentlichen aus 4 funktionalen Einheiten (Services):

• Datastore
  Speichert die Originaldaten (Cold Data), die von den Jupiter Geräten in Intervallen gesendet werden.

• Dataview
  Bereitet Teile der der Daten (Cold Data) auf und speichert diese in der Postgres Datenbank (Warm Data). Nimmt Benutzereingaben der Browser Anwendung entgegen und liefert die Daten zur Darstellung der Dashboard Grafiken/Tabellen.

• Postgres Datenbank
  Hier werden die sogenannten Warm Data gespeichert, also der Anteil der Daten, die zur schnellen Anzeige in den Dashboards dienen.

• Nginx (Reverse Proxy)
  Die http(s) Schnittstelle der Services.

Diese Services sind als Linux Docker Container entwickelt und werden mit Hilfe von Docker-Compose konfiguriert und gestartet/gestoppt. Die Darstellung der Daten für den Benutzer erfolgt dabei über einen Web-Browser auf einem beliebigen Rechner des Netzwerks.

Persistene Daten

Alle aufgezeichneten Daten werden durch den Datastore Service persistent im Home Verzeichnis des Linux Users gespeichert:

~/smartWAREData/datastore

Die Daten sind in gepackten Dateien gespeichert, und durch zusätzliche signierte Dateien vor Manipulation geschützt. Dieser gesamte Datenbestand wird auch als Cold Data bezeichnet.

Das Löschen dieses Verzeichnisses oder einzelner Dateien aus diesem Verzeichnis führt zum Verlust der aufgezeichneten Daten, falls keine Kopie der Daten erstellt wurde!

Backup

Erst ab Version 3.0.0.7 ist die Backup Funktion unterstützt.

Wenn datastore Backup aktiviert ist, werden die Daten des datastore zusätzlich beim Empfang im Verzeichnis gespeichert.

~/smartWAREBackup/

Um die Wahrscheinlichkeit eines Datenverlust durch einen Festplattencrash zu minimieren, empfiehlt es sich die Daten aus diesem Verzeichnis regelmäßig auf ein NAS im Netzwerk zu verschieben. Die Windows 10 Aufgabenplanung (Task Scheduler) in Verbindung mit dem Programm robocopy ist für diesen Zweck geeignet.

In einer Windows Powershell kann man nun mit folgendem Befehl die Dateien aus dem Verzeichnis \wsl$\Ubuntu-20.04\home<youruser>\smartWAREBackup verschieben, zum Beispiel auf eine schnelle USB Platte (z.Bsp. D:)

robocopy \wsl$\Ubuntu-20.04\home<youruser>\smartWAREBackup D:
\backup_smartware_data /MOV /E

Es werden dabei immer die Dateien verschoben. Das Verzeichnis \wsl$\Ubuntu-20.04\home<youruser>\smartWAREBackup ist also nur ein temporärer Zwischenspeicher der Backup Daten.
Bitte beachten Sie, <youruser> durch den Namen, der auf Ihrem System eingestellt ist zu ersetzen, wie auch der Laufwerksbuchstabe des Ziellaufwerks (im Beispiel D:\ ) auf Ihr reales System zu verändern ist.
Der Aufruf von robocopy folgt nach folgendem Schema.
robocopy Quellverzeichnis Zielverzeichnis /MOV /E
Der Parameter /MOV verschiebt Dateien und löscht sie aus der Quelle, nachdem sie kopiert wurden.
Der Parameter /E kopiert Unterverzeichnisse. Diese Option schließt automatisch leere Verzeichnisse ein.

Mit dem Parameter /L kann man eine Simulation des Befehls durchführen. Die Dateien werden dabei nicht kopiert und auch nicht gelöscht.

Backup automatisieren

Damit das Programm robocopy nicht immer manuell gestartet werden muss, kann man den Vorgang auch durch die Windows Aufgabenplanung täglich automatisieren.
Öffnen Sie dazu das Programm Aufgabenplanung.

Klicken Sie im Bereich Aktionen auf "Einfache Aufgabe erstellen...".

Es öffnet sich ein Assistent in dem Sie Bitte einen Namen und eine Beschreibung eingeben:

Dann klicken Sie auf die Schaltfläche "Weiter >".

Wählen Sie z.Bsp. "Täglich" und klicken Sie auf "Weiter >".

In diesem Dialog wählen Sie das Datum und die Uhrzeit an der das erste mal das Backup gestartet werden soll und klicken dann auf "Weiter >".

Wenn "Programm starten" ausgewählt ist klicken Sie auf "Weiter >".

In das Feld "Programme/Skript" tragen sie Bitte "robocopy" ein und in das Feld "Argumente hinzufügen (optional)" den folgenden langen Parameter Text, den Sie natürlich auf Ihren User Namen und den richtigen Ziellaufwerksbuchstaben anpassen müssen:

\\wsl$\Ubuntu-20.04\home\<youruser>\smartWAREBackup D:\backup_smartware_data /MOV /E

Klicken Sie dann auf "Weiter >".

Klicken Sie auf "Fertig stellen".
Sie können nun auch direkt die Aufgabe starten um zu überprüfen, dass die Daten auch auf das Ziellaufwerk kopiert werden.