Configs-Repository

Das Configs-Repository enthält die Konfigurationsdateien für die Ferrosoft Plattform und verwandte Dienste. Die Konfiguration ist in der DHALL-Sprache verfasst. Das Dhall-Projekt stellt Konversionsprogramme bereit, um DHALL-Dateien in JSON, TOML und YAML zu überführen.

Environment-Dateien

Das Herzstück des Configs-Repositorys sind die Environment-Dateien. Sie bündeln alle Informationen, die zur Erzeugung der konkreten Konfigurationsdateien benötigt werden.

Die Dateien liegen im Unterordner environments. Git-Crypt verschlüsselt diesen Ordner automatisch. Bevor Sie auf die Dateien zugreifen können, muss Ihr Schlüssel autorisiert werden.

Environment-Snippet

Fertiges Snippet zum Kopieren und Anpassen — ersetzen Sie alle xxx-Platzhalter:

let Platform = ../platform/package.dhall

in  Platform.Environment::{
    , name = "sandbox"
    , caddy = Platform.Caddy::{=}
    , platform = Platform.Config::{
      , version = "v2.45"
      , django_secret_key = "xxx"
      , sentry_dsn =
          "https://xxx@xxx.ingest.de.sentry.io/xxx"
      , service_fqdn_emiflow = "emiflow.sandbox.ferro.software"
      , service_fqdn_platform = "sandbox.ferro.software"
      , geoapify_api_key = "xxx"
      , django = Some
          ( λ(d : Platform.DjangoSettings.Type) →
                d
              ⫽ { EMAIL_HOST_USER = Some "xxx"
                , EMAIL_HOST_PASSWORD = Some "xxx"
                }
          )
      }
    , postgres = Platform.Postgres::{
      , admin_user_name = "postgres"
      , admin_user_password =
          "xxx"
      , host = "postgres"
      , port = 5432
      , platform_database = "platform_master"
      , platform_user_name = "platform"
      , platform_user_password =
          "xxx"
      }
    }

Konfigurationsdateien erzeugen

Makefile ausführen. Mit ENV geben Sie die Environment-Datei an (ohne .dhall-Endung). Die fertigen Dateien landen in build/<ENV> und werden beim Deployment der Ferrosoft Plattform benötigt.

make clean all ENV=sandbox

Mitarbeiter autorisieren

Zweck: Zugriff auf die Plattform-Konfiguration erlangen

Zielgruppe: Administrator mit Gitlab-Zugriff

Zeitaufwand: 10 Minuten

Der environments-Ordner ist mittels Git-Crypt (PGP) transparent verschlüsselt. Für den Zugriff wird ein PGP-Schlüssel benötigt, der von einem bereits autorisierten Mitarbeiter freigeschaltet werden muss.

Schritt 1a: PGP-Schlüssel für neuen Mitarbeiter erstellen

Der neue Mitarbeiter erzeugt den Schlüssel auf seiner eigenen Maschine.

PGP-Schlüssel generieren — mit E-Mail-Adresse, ohne Ablaufdatum, Kommentar "Git-Crypt":
```
gpg --full-generate-key
```
Öffentlichen Schlüssel (Pubkey) exportieren. Ersetzen Sie <KEY-ID> durch den Schlüsselnamen, z.B. die gewählte E-Mail-Adresse:
```
gpg --armor --export <KEY-ID>
```
Pubkey kopieren und an einen bereits autorisierten Mitarbeiter übergeben.

Schritt 1b: Neuen PGP-Schlüssel autorisieren

Der autorisierte Mitarbeiter schaltet den neuen Schlüssel auf seiner Maschine frei.

Pubkey in den eigenen Schlüsselbund importieren:
```
gpg --import keyfile.gpg
```
In das Configs-Repository wechseln.
Neuen Schlüssel autorisieren:
```
git-crypt add-gpg-user <KEY-ID>
```
Änderungen committen und pushen.

Schritt 2: Configs-Repository entsperren

Sobald der neue Mitarbeiter autorisiert ist, kann er das Repository klonen und die verschlüsselten Dateien entschlüsseln.

SSH-Schlüssel zum Agent hinzufügen:
```
ssh-add
```
Repository klonen:
```
git clone git@gitlab.com:ferrosoft/configs.git
cd configs
```
Schlägt der Klon fehl, vergewissern Sie sich, dass Ihr SSH-Schlüssel in Gitlab hinterlegt ist und Sie Zugriff auf die Ferrosoft-Gruppe haben.
Verschlüsselte Dateien entsperren:
```
git-crypt unlock
```

Schritt 3: Konversionsprogramme einrichten

Die Programme dhall-to-json u.ä. sind in den meisten Paketverwaltungen nicht verfügbar und müssen manuell bereitgestellt werden.

Programme vom dhall-haskell-Projekt herunterladen.
Binaries dhall-to-json, dhall-to-toml und dhall-to-yaml in das Unterverzeichnis bin entpacken.
Sicherstellen, dass direnv korrekt eingerichtet ist, damit beim Wechsel in das Configs-Repository PATH automatisch um das Unterverzeichnis bin erweitert wird.

Ferrosoft Betriebshandbuch