Platform Deployment

Zweck: Initiale Einrichtung der Ferrosoft Plattform

Zielgruppe: Administrator mit SSH-Zugang auf den Root-Account

Geschätzter Gesamtaufwand: 30 Minuten

Schritte

1. Configs-Repository einrichten

Siehe Einrichtung des Configs-Repositorys.

2. Konfigurationsdateien erzeugen

  1. Ins Configs-Repository wechseln.

  2. Secret-Key für Django erzeugen:

    openssl rand -base64 50 | tr -dc 'a-zA-Z0-9' | head -c 50

  3. Environment-Datei anlegen.

    Die DHALL-Datei (Endung .dhall) kommt in den Unterordner environments — Dateien dort werden transparent verschlüsselt. Vorlage: Environment-Snippet.

  4. Konfigurationsdateien bauen (ENV = Name der Environment-Datei ohne .dhall-Endung):

    make ENV=xxx

    Die fertigen Dateien liegen danach in build/xxx.

3. Compose-Projekt starten

Die Plattform und alle Dienste — Datenbank, Webserver und mehr — werden über Docker Compose verwaltet. Bereitstellung und Compose-Befehle übernimmt das Playbook platform.yml.

  1. Ins Infrastruktur-Repository wechseln.

  2. Docker Container Engine installieren:

    uv run ./ansible-playbook --host "xxx" playbooks/docker-ce.yml

  3. Plattform-Playbook ausführen. <CONFIGS_DIR> durch den Pfad zu den im vorigen Schritt erzeugten Konfigurationsdateien ersetzen:

    uv run ./ansible-playbook --host "xxx" playbooks/platform.yml -e fp2_configs_src=<CONFIGS_DIR>

    Nützliche Ad-Hoc-Variablen für diesen Aufruf sind im Konfigurationsmanagement dokumentiert.

4. Adminzugang einrichten

Überspringen Sie diesen Schritt, wenn Sie die Plattform aus einer Sicherung wiederherstellen.

  1. Initialen Mandanten anlegen. Erstes Argument: Mandant-Name, zweites Argument: Organisations-Name. Ferrosoft ist die eingebaute Organisation:

    ./container-run --host "xxx" -- addtenant Ferrosoft Ferrosoft

  2. Initialen Administrator anlegen. Die Organisations-ID ist die ID der eingebauten Ferrosoft-Organisation:

    ./container-run --host "xxx" -- createsuperuser --organization_id=0198a8b4-9109-7d8a-992f-3a4ed6ad0194

Mission erfüllt. Die Ferrosoft Plattform ist einsatzbereit. Zur Überprüfung die in der Environment-Datei konfigurierte URL aufrufen (platform.service_fqdn_platform).

Plattform aus Sicherung wiederherstellen

Siehe Schritte zur Wiederherstellung. Die dort beschriebenen Schritte werden nach der Einrichtung gemäß diesem Kapitel ausgeführt — Schritt 4 (Adminzugang) ausgenommen.

Troubleshooting

Playbook gescheitert oder Browser zeigt nicht das Erwartete?

  • Playbook hängt bei "Check if restic repo is initialized" — S3-Zugangsdaten prüfen, typischerweise in playbooks/group_vars/ferrosoft/backup.yml.
  • Ansible-Fehler — Ausgabe des ansible-playbook-Aufrufs genau lesen; die genaue Fehlermeldung steckt fast immer darin.
  • Fehler in der Django-App — falls Sentry konfiguriert ist (platform.sentry_dsn in der Environment-Datei), dort den Fehler im Detail untersuchen.
  • Flüchtige Fehler — per SSH auf den Server verbinden, nach /etc/ferrosoft wechseln und mit docker compose-Befehlen den Zustand inspizieren.