refactoring

We again decided to restrure the whole guide...

Author: Luis Herr

README.md

@@ -1,39 +1,2 @@
 # Admin Guide
-You can find this repository here: [https://adminguide.pages.dev](https://adminguide.pages.dev).
-
-## Contribute
-Feel free to open issues / pull requests. Please validate that your changes work as intented!
-You can start the mkdocs development server by running `mkdocs serve`.
-
-Contribution Guidelines:
-* Web Services are exposed to `[::1]:8000`
-* Secret Environment Variables are in an env_file (and not in the `docker-compose.yml` itself, to prevent leaks) with the following format:
-  ```shell
-  # .servicename.env
-  KEY=value
-  ```
-* environment variables should be in form of a YAML array, not an object:
-  ```yaml
-  environment:
-    - "KEY=value"
-  ```
-  instead of
-  ```yaml
-  # WRONG - please don't do this
-  environemnt:
-    KEY: value
-  # WRONG
-  ```
-* If possible the service should use either mariadb or postgresql.
-  If it makes sense, other databases (e.g. sqlite) are also quiet fine.
-* YAML arrays should be quoted, regardless which data is stored:
-  ```yaml
-  volumes:
-    - "/srv/service_name/data:/data"
-  ports:
-    - "[::1]:8000:1234"
-  networks:
-    - "default"
-    - "database"
-  ```
-* All domain examples should end in `domain.de`
+You can find the rendered guide on [adminguide.pages.dev](https://adminguide.pages.dev).

ToDo_reforming.md

@@ -0,0 +1,11 @@
+# 1. Wahl des Reverse Proxies
+Im Rahmen dieses Guides werden [nginx](https://www.nginx.com/) auf dem Host sowie
+[Traefik](https://traefik.io/) als Container vorgestellt.
+
+Nginx ist ein leistungsstarker und weit verbreiteter Webserver und Reverse Proxy, welcher sich
+durch hohe Stabilität, Effizienz und Flexibilität in klassischen Serverumgebungen auszeichnet.
+
+Traefik hingegen ist speziell auf containerisierte Umgebungen ausgelegt und integriert sich
+nahtlos mit Plattformen wie Docker oder Kubernetes. Es erkennt neue Services automatisch und
+konfiguriert Routing-Regeln dynamisch, was es besonders für moderne, dynamische Deployments
+attraktiv macht.

docs/10_overview.md

@@ -0,0 +1,71 @@
+# 2. TLS
+Für die verschlüsselte Kommunikation zwischen Nutzer und Webserver sind TLS-Zertifikate
+erforderlich.
+
+In den Standard-Einstellungen von Betriebssystemen und Browsern ist bereits eine Auswahl
+vertrauenswürdiger Zertifizierungsstellen (CAs) hinterlegt. Nur Zertifikate, die von einer
+dieser anerkannten Stellen ausgestellt oder signiert wurden, werden vom Browser automatisch
+als sicher bzw. vertrauenswürdig eingestuft. Diese sogenannte "Trusted Root Certificate Authority
+List" wird von den jeweiligen Herstellern (z. B. Microsoft, Apple, Mozilla, Google) gepflegt und
+regelmäßig aktualisiert.
+
+Es gibt grundsätzlich drei Möglichkeiten, TLS-Zertifikate zu beziehen bzw. auszustellen:
+
+1. **Kommerzielle Anbieter**
+
+    Zertifikate können kostenpflichtig von anerkannten Zertifizierungsstellen wie DigiCert,
+    GlobalSign oder GoDaddy erworben werden. Sie werden häufig von Unternehmen genutzt, um
+    zusätzliche Garantieleistungen, erweiterte Validierungen (OV/EV) oder Supportleistungen
+    zu erhalten.
+
+2. **Kostenlose Zertifikate**
+
+    Let’s Encrypt wurde 2015 von der gemeinnützigen Organisation Internet Security Research Group (ISRG)
+    gegründet. Ziel war es, das Web durch die Bereitstellung kostenloser, automatisierter und offener
+    Zertifikate sicherer zu machen und so verschlüsselte Verbindungen (HTTPS) zum Standard im Internet
+    zu etablieren.
+
+    Neben Let’s Encrypt existieren weitere Anbieter, die ähnliche kostenlose Zertifizierungsdienste anbieten,
+    wie beispielsweise ZeroSSL und [Actalis](https://www.actalis.com/). Alle Anbieter unterstützen das
+    ACME-Protokoll (Automatic Certificate Management Environment), über das die Ausstellung und Verlängerung
+    von Zertifikaten automatisiert erfolgen kann.
+
+    Diese kostenlosen Zertifikate sind von den gängigen Browsern als vertrauenswürdig anerkannt und eignen sich
+    hervorragend für öffentliche Websites, Webanwendungen und APIs. Im Vergleich zu kommerziellen Angeboten bieten
+    sie zwar keine zusätzlichen Garantieleistungen oder erweiterte Validierung (z. B. EV-Zertifikate), erfüllen
+    aber in technischer Hinsicht die gleichen Sicherheitsstandards.
+
+3. **Eigene Zertifizierungsstelle (CA)**
+
+    Neben öffentlichen und kommerziellen Anbietern besteht auch die Möglichkeit, eine eigene Zertifizierungsstelle
+    (Certificate Authority, CA) zu betreiben. Damit können eigene Zertifikate ausgestellt werden – beispielsweise
+    für interne Server, Entwicklungsumgebungen oder Testsysteme.
+
+    Diese Variante ist kostenlos, erfordert jedoch mehr administrativen Aufwand. Damit Browser und Betriebssysteme
+    den ausgestellten Zertifikaten vertrauen, muss das Root-Zertifikat der eigenen CA manuell auf allen beteiligten
+    Geräten installiert werden. In kontrollierten Umgebungen (z. B. Firmennetzwerke oder geschlossene Systeme) kann
+    dies automatisiert über zentrale Verwaltungswerkzeuge erfolgen.
+
+    Für den produktiven Einsatz im öffentlichen Internet ist diese Lösung jedoch nicht geeignet, da externe Nutzer
+    das Root-Zertifikat nicht installiert haben und der Browser die Verbindung daher als nicht vertrauenswürdig
+    einstufen würde.
+
+!!! warning
+    Von der Verwendung selbstsignierter Zertifikate und dem Ignorieren von Browserwarnungen ist dringend abzuraten.
+
+    Wer sich daran gewöhnt, Sicherheitsmeldungen einfach „wegzuklicken“, entwickelt schnell ein riskantes Verhalten.
+
+Im Rahmen dieses Guides wird auf kostenlose TLS-Zertifikate des Anbieters Let’s Encrypt gesetzt.
+
+Für die Verwaltung dieser stehen verschiedene Tools und Clients zur Verfügung. Wird nginx als Reverse Proxy
+eingesetzt, bietet sich die Verwendung von [acme.sh](https://github.com/acmesh-official/acme.sh), ein schlanker,
+in Shell geschriebener ACME-Client, der sich einfach in bestehende Umgebungen integrieren lässt, an.
+Traefik hingegen verwendet für diesen Zweck standardmäßig den in Go entwickelten ACME-Client [Lego](https://go-acme.github.io/lego/).
+
+Unabhängig von der gewählten Implementierung stehen bei Let’s Encrypt verschiedene [ACME-Challenge-Typen](https://letsencrypt.org/docs/challenge-types/)
+zur Verfügung, über die die Domainvalidierung erfolgt.
+
+Während die Challenge-Typen HTTP-01 und TLS-ALPN-01 voraussetzen, dass der Reverse Proxy aus dem Internet
+erreichbar ist, bietet die DNS-01-Challenge die Möglichkeit, die Domainvalidierung über einen TXT-Eintrag
+im DNS durchzuführen. Dadurch muss der Webserver nicht öffentlich zugänglich sein, und die ausgestellten
+Zertifikate können somit auch in internen Umgebungen verwendet werden.

docs/30_Theorie.md

@@ -0,0 +1,24 @@
+# 3. Eine IPv6 Adresse pro Service
+
+!!! note
+    Die meisten Hosting-Provider weisen jedem Server ein /64-IPv6-Präfix zu,
+    was einem Adressraum von $2^{64}$ Adressen entspricht – eine Zahl, die in
+    der Praxis quasi unerschöpflich ist.
+
+    Ausnahmen gibt es beispielsweise bei Strato: Dort wird nicht ein ganzes /64-IPv6-Präfix,
+    sondern lediglich eine einzelne IPv6-Adresse pro Server zugewiesen. Dadurch ist es nicht
+    möglich, jedem Dienst eine eigene IPv6-Adresse zu geben
+    ([siehe YouTube Short](https://www.youtube.com/shorts/oSvU4HXZ_Wc)).
+
+Wird jedem nginx Reverse Proxy eine eigene IPv6-Adresse zugewiesen, kann bereits auf OSI-Layer 3
+nachvollzogen werden, an welchen Webservice eine Anfrage gerichtet war. Würde hingegen für alle
+Dienste nur eine gemeinsame Adresse verwendet, wäre eine eindeutige Zuordnung frühestens auf
+Layer 5 (durch Auswertung des TLS SNI Headers) möglich; ohne ein spezielles Analysewerkzeug sogar
+erst auf Layer 7, etwa über die Logdaten des Webservers.
+
+Der Webserver nginx bietet mit der Direktive `listen` die Möglichkeit, virtuelle Hosts an spezifische
+IPv4- oder IPv6-Adressen zu binden. Diese Technik erlaubt eine frühzeitige Trennung und Zuordnung des
+eingehenden Traffics zu den einzelnen Anwendungen. Soll ein Dienst abgeschaltet oder vorübergehend
+blockiert werden, kann dessen zugewiesene Adresse zudem sehr einfach über die Firewall – oder sogar
+direkt beim Provider – gesperrt werden, ohne dass Änderungen an der Servicekonfiguration selbst
+erforderlich sind.