Neukunde / neues Projekt

Diese Seite beschreibt den vollständigen Ablauf zur Einrichtung eines neuen MegBes-Kunden beziehungsweise eines neuen Projekts. Projektspezifische Werte werden zunächst gesammelt und anschließend in den jeweils maßgeblichen Systemen eingetragen.

Wichtig: Passwörter, Tokens, private Schlüssel und geheime Update-URLs dürfen nicht auf dieser Seite oder einer Projektseite gespeichert werden. Dafür ist ausschließlich der vorgesehene Passwortmanager zu verwenden.

1. Projekt festlegen

Vor Beginn sind mindestens zu bestimmen:

vollständiger Projekt- und Kundenname
eindeutiges technisches Projektkürzel
zuständige Personen bei tinetronics
gewünschte Bedienoberfläche
Art der Anmeldung:
- Anmeldung über Ticket-Monitor
- direkter Zugriff ohne Ticket-Monitor, wie beim Subprojekt MiQua Guide
- gegebenenfalls weitere projektspezifische Variante
Anzahl und Art der Medienstationen
Stationsnummern und benötigte UDP-Befehle
lokales Subnetz und gewünschter UDP-Port
projektspezifischer Stations-Timer

Anschließend eine neue Seite in der Projektübersicht anlegen.

2. Domains und Erreichbarkeit

Im Regelfall werden zwei Adressen benötigt:

Externe Adresse: Subdomain für `megbes-external`, beispielsweise `<projekt>.megbes.de`.

Interne Erreichbarkeit: DynDNS-Adresse oder eine andere dauerhaft erreichbare Adresse für `megbes-internal`, beispielsweise `<projekt>-dyndns.megbes.de`.

Für die externe Subdomain ist der DNS-Eintrag auf den zentralen Plesk-Server zu richten. Die konkrete Zieladresse muss vor der Einrichtung anhand der aktuellen IONOS-/Plesk-Konfiguration geprüft werden und wird nicht als allgemeiner Festwert im Wiki hinterlegt.

Für die interne Seite wird bevorzugt IONOS DynDNS eingesetzt. Alternative Anbieter sind nur zu verwenden, wenn dies technisch erforderlich ist.

3. Projektkonfiguration in GitHub

Im privaten Repository `tinetronics/megbes-config` sind die produktiven Konfigurationen anzupassen.

megbes-external-config.json

Für das Projekt werden mindestens gepflegt:

technischer Projektschlüssel
Kommunikationsprotokoll zum internen Server
Adresse von `megbes-internal`
Port von `megbes-internal`
bei Projekten mit zentraler Anmeldung: initialer Administratorname und verschlüsseltes Administratorpasswort

Das Administratorpasswort darf niemals im Klartext eingetragen werden. Die Verschlüsselung erfolgt mit dem vorgesehenen Werkzeug des Status-Monitors.

megbes-status-config.json

Das Projekt wird zusätzlich mit seiner internen und externen Adresse in die Status-Konfiguration aufgenommen.

Prüfung

JSON-Syntax prüfen.
Änderungen nachvollziehbar committen.
Änderungen über den vereinbarten Git-Prozess bereitstellen.
Nach der Übernahme die betroffenen Dienste kontrolliert neu laden.

Siehe auch Konfiguration.

4. megbes-external unter Plesk

Für jedes Projekt wird auf dem zentralen IONOS-Server ein eigener Docker-Container betrieben.

Neue externe Subdomain in Plesk anlegen.
TLS-Zertifikat für die Subdomain einrichten.
Docker-Container aus dem freigegebenen `megbes-external`-Image erstellen.
Container eindeutig nach dem Projekt benennen.
automatischen Start nach einem Serverneustart aktivieren.
erforderliche Umgebungsvariablen anhand der aktuellen freigegebenen Vorlage setzen.
Zertifikatsdateien beziehungsweise Volumes korrekt einbinden.
automatische Portzuordnung nach der initialen Einrichtung deaktivieren.
Docker-Proxy-Regel von der Subdomain auf den Container einrichten.
Container starten und Protokoll auf Fehler prüfen.

Der einzusetzende Release wird bewusst festgelegt. Ein neuer Kunde erhält grundsätzlich den aktuell freigegebenen Release, sofern kein bekannter projektspezifischer Grund dagegenspricht.

5. Zertifikate

Projektbezogene Zertifikate werden über den Status-Monitor erstellt und entsprechend der dortigen Anleitung installiert.

Zu prüfen sind:

Zertifikat gehört zum richtigen Projekt und zur richtigen Adresse.
Zertifikatsdateien liegen am vorgesehenen Ablageort.
Container-Volume zeigt auf den korrekten Ordner.
Kennwörter sind ausschließlich im Passwortmanager und in der geschützten Laufzeitkonfiguration hinterlegt.
Verbindung wird nach dem Neustart erfolgreich getestet.

6. Interner Server beim Kunden

Für jedes Projekt wird beim Kunden ein eigener Server für `megbes-internal` eingerichtet. Die folgenden Schritte sind in dieser Reihenfolge abzuarbeiten.

6.1 Ubuntu installieren und anmelden

Die jeweils aktuelle Ubuntu-LTS-Version installieren. Während der Installation:

eindeutigen Servernamen nach dem Projektschema vergeben
Administrationsbenutzer anlegen
OpenSSH-Server installieren
keine unnötigen Zusatzpakete auswählen
Installationsmedium nach Aufforderung entfernen

Nach dem Neustart lokal oder per SSH anmelden.

6.2 Aktuelle Ubuntu-Version prüfen

lsb_release -a

Falls der Befehl fehlt:

cat /etc/os-release

Prüfen, ob tatsächlich die vorgesehene LTS-Version installiert ist.

6.3 System vollständig aktualisieren

Zuerst aktuelle Paketlisten abrufen:

sudo apt update

Der Befehl muss ohne Zeilen mit `E:` oder `Error` enden. Danach verfügbare Aktualisierungen installieren:

sudo apt upgrade

Die Paketliste prüfen und die Rückfrage mit `Y` beziehungsweise `J` bestätigen. Nach Abschluss den Neustartbedarf prüfen:

if [ -f /run/reboot-required ]; then cat /run/reboot-required; else echo "Kein Neustart erforderlich"; fi

Falls ein Neustart erforderlich ist:

sudo reboot

Danach neu anmelden und prüfen:

systemctl --failed

Die vollständige Anleitung einschließlich Fehlerbehandlung und Funktionstest steht unter Ubuntu aktualisieren.

6.4 Feste lokale IP-Adresse einrichten

Die Netzwerkschnittstelle, IP-Adresse, Netzmaske, Gateway und DNS-Server anhand der Kundennetz-Dokumentation bestimmen. Keine Beispieladresse ungeprüft übernehmen. Die konkrete Anleitung folgt unter Feste IP-Adresse unter Ubuntu.

Nach der Änderung Verbindung, Gateway und DNS testen:

ip address
ip route
ping -c 4 <Gateway-Adresse>
getent hosts download.docker.com

6.5 Docker installieren

Docker aus der offiziellen Docker-Paketquelle installieren. Nicht mehr die veraltete GPG-/Repository-Anleitung aus dem Word-Dokument verwenden.

Die vollständige Schrittfolge steht unter Docker installieren. Abschließend müssen diese Prüfungen erfolgreich sein:

docker --version
sudo systemctl status docker --no-pager
sudo docker run --rm hello-world

6.6 Projektordner vorbereiten

Einen eindeutig benannten Ordner für die geschützten Zertifikatsdateien anlegen. Beispiel – Benutzer und Projektkürzel anpassen:

mkdir -p /home/<Benutzername>/certs/<Projektkürzel>
chmod 700 /home/<Benutzername>/certs/<Projektkürzel>

Anschließend kontrollieren:

ls -ld /home/<Benutzername>/certs/<Projektkürzel>

6.7 Projektbezogene Dateien übertragen

Benötigt werden mindestens:

projektspezifische Umgebungsdatei
Key- und Truststore beziehungsweise aktuell verwendete Zertifikatsdateien
dokumentierter Container-Name
festgelegter External-/Internal-Port
UDP-Port und lokales Subnetz
freigegebener Release

Dateien nach dem Übertragen mit `ls -l` kontrollieren. Geheimnisdateien dürfen nicht für alle Benutzer lesbar sein.

6.8 megbes-internal starten

Der projektspezifische Docker-Befehl wird anhand der geprüften Vorlage erstellt. Keine Befehlszeile eines anderen Kunden ungeprüft kopieren. Vor dem Start insbesondere kontrollieren:

Container-Name
External-zu-Container-Port
UDP-Port
Pfad und Name der Umgebungsdatei
Zertifikats-Volume
Docker-Image und Release
Neustartregel `unless-stopped`

Die ausführliche Anleitung folgt unter megbes-internal.

6.9 Start prüfen

sudo docker ps
sudo docker logs --tail 100 <Containername>

Der Container muss `Up` sein. Wiederholte Exceptions, Zertifikats- oder Verbindungsfehler müssen vor dem nächsten Schritt behoben werden.

6.10 Neustarttest

Server kontrolliert neu starten:

sudo reboot

Danach neu anmelden und prüfen:

sudo systemctl status docker --no-pager
sudo docker ps

Der MegBes-Container muss aufgrund der Neustartregel automatisch wieder laufen.

7. Router, DynDNS und Portfreigabe

Am Kundenrouter sind – abhängig vom Projekt – folgende Punkte einzurichten:

feste Zuordnung für den internen Server
DynDNS-Konfiguration
erforderliche TCP-Portfreigabe zu `megbes-internal`
gegebenenfalls kundenspezifische Firewall-Regeln

Der externe Port, der interne Port und die in `megbes-external-config.json` eingetragene Portnummer müssen zueinander passen.

Router-Zugangsdaten und geheime DynDNS-Update-URLs gehören ausschließlich in den Passwortmanager.

8. Medienstationen

Für jede Station sind zu erfassen:

Stationsnummer
Gerätetyp
lokale IP-Adresse
unterstützte UDP-Befehle
verwendeter UDP-Port
Art der Bedienung und Anmeldung
Verhalten bei `IDLE`, `TOUCHSCREEN`, `REMOTE` und gegebenenfalls `OPEN`
erwartete Init-/Statusmeldung

Siehe UDP und Stationszustände.

9. Abnahme und Funktionstest

Vor Übergabe müssen mindestens folgende Prüfungen erfolgreich sein:

externe Projektadresse ist per HTTPS erreichbar.
vorgesehene Anmeldung beziehungsweise der direkte Zugriff funktioniert.
`megbes-external` erreicht `megbes-internal`.
Befehle erreichen die richtige Station.
Start, Stopp und weitere projektspezifische Befehle funktionieren.
Stationszustände und Timer verhalten sich wie vereinbart.
Neustart von externem und internem Container wurde getestet.
Neustart des internen Servers wurde getestet.
Status-Monitor erkennt die Projektinstanzen.
Status-/Init-Meldungen erreichen den vorgesehenen Empfänger.
Fehler und Besonderheiten sind auf der Projektseite dokumentiert.

10. Projektdokumentation abschließen

Auf der Projektseite werden anschließend mindestens eingetragen:

Domains und technische Projektschlüssel
Container-Namen
Ports und Netzwerkbereiche
installierte Releases von External und Internal
Server- und Stationshardware
Stations-Timer
Datum und Ergebnis des letzten Funktionstests
Besonderheiten und offene Aufgaben
Verweis auf die zugehörigen Einträge im Passwortmanager – niemals die Geheimwerte selbst