Neukunde

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

1. JSON-Syntax prüfen.
2. Änderungen nachvollziehbar committen.
3. Änderungen über den vereinbarten Git-Prozess bereitstellen.
4. 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.

1. Neue externe Subdomain in Plesk anlegen.
2. TLS-Zertifikat für die Subdomain einrichten.
3. Docker-Container aus dem freigegebenen `megbes-external`-Image erstellen.
4. Container eindeutig nach dem Projekt benennen.
5. automatischen Start nach einem Serverneustart aktivieren.
6. erforderliche Umgebungsvariablen anhand der aktuellen freigegebenen Vorlage setzen.
7. Zertifikatsdateien beziehungsweise Volumes korrekt einbinden.
8. automatische Portzuordnung nach der initialen Einrichtung deaktivieren.
9. Docker-Proxy-Regel von der Subdomain auf den Container einrichten.
10. 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.

1. aktuelle Ubuntu-LTS-Version installieren.
2. administrativen Benutzer einrichten; nicht dauerhaft als `root` arbeiten.
3. System vollständig aktualisieren.
4. feste lokale IP-Adresse passend zum Kundennetz konfigurieren.
5. Docker installieren und Funktion prüfen.
6. projektbezogene Umgebungsdatei erstellen.
7. Zertifikate in einen eindeutig benannten, geschützten Ordner kopieren.
8. freigegebenes `megbes-internal`-Image laden.
9. Container mit automatischem Neustart, korrekten Ports und Volumes starten.
10. Container-Protokoll prüfen.

Die Umgebungsdatei enthält nur projektspezifische Werte. Eine Konfiguration aus einem anderen Kundenprojekt darf nicht ungeprüft kopiert werden.

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:

1. externe Projektadresse ist per HTTPS erreichbar.
2. vorgesehene Anmeldung beziehungsweise der direkte Zugriff funktioniert.
3. `megbes-external` erreicht `megbes-internal`.
4. Befehle erreichen die richtige Station.
5. Start, Stopp und weitere projektspezifische Befehle funktionieren.
6. Stationszustände und Timer verhalten sich wie vereinbart.
7. Neustart von externem und internem Container wurde getestet.
8. Neustart des internen Servers wurde getestet.
9. Status-Monitor erkennt die Projektinstanzen.
10. Status-/Init-Meldungen erreichen den vorgesehenen Empfänger.
11. 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