Apps anlegen, verwalten und warten

Unter https://codeberg.org/softwerke-magdeburg/infrastructure/src/branch/main/apps sind alle von uns zur Verfügung gestellten Apps/Dienste zu finden. Jeder Ordner ist dabei ein eigenes Docker-Compose-Projekt, welches auf bestimmte global verfügbare Variablen und andere Dienste (z. B. Traefik, MySQL, PostgreSQL, Mail & LDAP) zurückgreifen kann.

Ein Projekt sieht also beispielsweise wiefolgt aus:

  • <APPNAME>/
    • README.md - Informationen zu eigenen Umgebungsvariable und Secrets
    • docker-compose.yml - Compose File (Version 3.8) für den Dienst
    • Konfigurationsdateien, die dann als Volume eingebunden werden

Für die Compose-Datei ist folgendes zu beachten:

  • Es sollten lediglich offizielle (von Docker oder dem Entwicklungsteam des Dienstes) Images genutzt werden. Andernfalls ist es unbedingt notwendig, dass der Build automatisiert ist (also im Docker-Hub direkt die Dockerfile verlinkt ist, oder eine andere vertrauenswürdige CI wie GitHub Actions oder eine gehostete Woodpecker-Instanz genutzt wird). Das Projekt sollte zudem voraussichtlich auch in absehbarer Zukunft aktiv maintained und aktualisiert werden.
  • Images sollten eine Minor-Versionsnummer nutzen, also z. B. 2.1 - gibt es beim eingesetzten Image keine solchen Tags, sollte der nächst-spezifischere Tag genutzt werden. Nur wenn auch dies nicht möglich ist können allgemeinere Tags wie 2 oder gar latest genutzt werden.
  • Das Zielsystem nutzt SELinux, alle Volumes müssen darum entweder mit :z oder :ro,z gekennzeichnet werden, je nachdem ob sie schreibbar sind.
  • Für Volumes, in denen langfristige lokale Daten gespeichert werden sollen, ist der Pfad-Präfix ${data_volume:-./data} auf dem Hostsystem zu verwenden. Für kurzfristiges Caching kann ${cache_volume:-./cache} genutzt werden.
  • Der YAML-Code sollte entsprechend der .editorconfig mit zwei Leerzeichen als Einzug formatiert werden; die meisten Texteditoren und IDEs erledigen dies automatisch.

Global verfügbare Variablen

Global verfügbare Dienste

TODO: Aktuell fehlt ein allgemeiner Ansatz für den lokalen Test von LDAP, E-Mail, Datenbanken etc. mit TLS-Verschlüsselung. Dies muss noch fertiggestellt und dokumentiert werden.

Traefik

Durch Traefik 2 als Reverse Proxy können HTTP-Endpunkte der App unter einer bestimmten Internetadresse verfügbar gemacht werden. Dies wird über Docker-Label eingestellt, beispielsweise folgendermaßen:

labels:
  traefik.enable: "true"
  traefik.http.services.<APPNAME>.loadbalancer.server.port: "80" # Container-internal port
  traefik.http.routers.<APPNAME>.rule: "Host(`example.${main_domain:-localhost.mock.directory}`)" # Rules for exposed URL
  traefik.http.routers.<APPNAME>.entrypoints: "web"
  traefik.http.routers.<APPNAME>.tls: "true"
  traefik.http.routers.<APPNAME>.middlewares: "hsts"

E-Mail

Für den Versand von E-Mail kann SMTP genutzt werden, wofür folgende Umgebungsvariablen genutzt werden können:

  • ${mail_from:-noreply@example.email} - Absenderadresse des Servers
  • ${mail_server:-mailhog} - Hostname oder IP-Adresse des Mail-Servers.
  • ${mail_port:-1025} - Port des Mail-Servers.
  • ${mail_username:-mailhog} - Benutzername für den Mail-Versand per SMTP.
  • ${mail_password:-mailhog} - Passwort für den Mail-Versand per SMTP.

Authentifizierung

OpenID Connect

Dies ist bisher noch nicht implementiert, wird später aber die bevorzugte Methode sein.

SAML

Dies ist bisher noch nicht implementiert.

LDAP

LDAP sollte nur genutzt werden wenn weder OpenID Connect noch SAML genutzt werden können.

Dabei können folgende Umgebungsvariablen genutzt werden:

  • ${ldap_server:-openldap} - Hostname oder IP-Adresse des LDAP-Servers.
  • ${ldap_bind_dn:-cn=admin,dc=example} - DN für die Authentifizierung am LDAP-Server.
  • ${ldap_bind_pw:-secret} - Passwort für die Authentifizierung des LDAP-Servers.
  • ${ldap_dn:-dc=example} - DN unter dem alle Nutzer etc. gefunden werden können; als Such-DN für Nutzer kann also beispielsweise ou=users,${ldap_dn:-dc=example} genutzt werden.

Das LDAP-Schema hat dabei folgende Eigenschaften:

  • TODO

Datenbanken

PostgreSQL

Das bevorzugte Datenbanksystem ist PostgreSQL - dieses kann mit folgenden Umgebungsvariablen genutzt werden:

  • ${postgres_host:-my-database} - Hostname oder IP-Adresse des PostgreSQL-Servers.
  • ${postgres_database:-example} - Datenbankname für den entsprechenden Dienst.
  • ${postgres_username:-example} - Für die Authentifizierung zu nutzender Benutzername.
  • ${postgres_password:-secret} - Für die Authentifizierung zu nutzendes Passwort.
MariaDB

Wenn PostgreSQL nicht unterstützt wird, kann eine MariaDB-Datenbank folgendermaßen eingesetzt werden:

  • ${mariadb_host:-my-database} - Hostname oder IP-Adresse des MariaDB-Servers.
  • ${mariadb_database:-example} - Datenbankname für den entsprechenden Dienst.
  • ${mariadb_username:-example} - Für die Authentifizierung zu nutzender Benutzername.
  • ${mariadb_password:-secret} - Für die Authentifizierung zu nutzendes Passwort.

Lokale Testmöglichkeit

Mit ./debug.sh <APPNAME> up kann ein Projekt gestartet werden - alles was dafür benötigt wird ist eine POSIX-Shell (wie sie auf jeder handelsüblichen Linux-Distribution vorhanden sein sollte) und Docker + Docker Compose.