Update Documentation

2023-01-06 08:53:54 +01:00 · 2023-01-06 08:53:54 +01:00 · f0cbc32c36
parent 606f582dc0
commit f0cbc32c36
1 changed files with 76 additions and 54 deletions
--- a/README.md
+++ b/README.md
@ -1,27 +1,55 @@
-# Starten des Reverse-Proxies
+# First Steps
+## Initiales Setup
+Öffne ein Terminal und führe die `setup.sh` Datei aus.
+Das Script:
+1. Behebt Berechtigungsprobleme und legt alle nötigen Ordner/Dateien an, die zum starten des Proxies benötigt werden.
+2. Installiert den `myssh` befehl nach `$HOME/bin` und fügt diesen ggf zur PATH variable hinzu
+3. Erstellt SSH Keys für den SSH Docker Container (wenn diese nicht bereits existieren)
+4. Erstellt und Konfiguriert einen Client SSH Key, dessen public Key wird dem SSH Docker Container hinzugefügt
+
+## Starten des Reverse-Proxies
 Der Proxy kann über docker compose gestartet werden
 ```bash
 docker compose up -d
 ```

-# Hinzufügen von Docker Containern
+# Proxy Konfiguration
+## HTTP-Proxy
+### Hinzufügen von Docker Containern (Hosts)
 Container werden automatisch vom reverse proxy/host manager aufgegriffen wenn sie:
 1. Das Label `local.web.host` gesetzt haben.
 2. Im gleichen Docker-Netzwek (Default: `proxy`) sind.

 Optional kann über das Label `local.web.port` der gebundene Port gesetzt werden (Default: 80)

+### SSL Zertifikat Konfiguration
+Nach starten des docker containers ist das von caddy erstellte SSL Zertifikat in './caddy_data/pki/authorities/local/root.crt' gefunden werden.
+Relevante Dokumentation:
+- [MacOS](https://support.apple.com/guide/keychain-access/add-certificates-to-a-keychain-kyca2431/mac)
+- [Linux](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/security_guide/sec-shared-system-certificates)
+
+## SQL Proxy
+### Hinzufügen von DB Docker Containern
+Container werden automatisch vom reverse proxy/host manager aufgegriffen wenn sie:
+1. Die Umgebungsvariable `local.db.type` (`mysql` oder `postgres`) und `local.db.host` gesetzt haben.
+2. Im gleichen Docker-Netzwek (Default: `proxy`) sind.
+
+Optional kann über das Label `local.web.port` der gebundene Port gesetzt werden (Default mysql: 3306, Default postgres: 5432)
+
 ## Minimale Beispiel-Konfiguration
-In diesem Beispiel sind zwei Container, nur der `app` Kontainer ist teil des proxy Netzwerks, der `db` Container ist nicht im proxy Netzwerk.
+In diesem Beispiel sind zwei Container, beide sind Teil des `proxy` Netzwerks.
+Der `app` Container hat das Label `local.web.host` und wird deshalb als HTTP Proxy Target registriert.
+Der `db` Container hat die Label `local.db.type` und `local.db.host` und wird deshalt als SQL Proxy Target registriert.
 ```yaml
 version: "3.4"
 services:
  db:
    image: mariadb:10.4
    labels:
+      # SQL-Proxy Configuration
      # Required labels
      local.db.type: "mysql"
-      local.db.host: "db_host"
+      local.db.host: "db.myapp.localhost"
      # Optional labels
      local.db.port: "3306"
      local.db.user: "db_user"
@ -34,16 +62,23 @@ services:
    restart: unless-stopped
    volumes:
      - db-data:/var/lib/mysql
+    networks:
+      - default
+      - proxy

  app:
    image: some_base/image
    depends_on:
      - db
    labels:
-      local.web.host: "app_host"
+      # HTTP-Proxy Configuration
+      # Required Label
+      local.web.host: "myapp.localhost"
+      # "Optional" Label to set the correct port
      local.web.port: "3000"
    restart: unless-stopped
    networks:
+      - default
      - proxy

 networks:
@ -60,35 +95,42 @@ networks:
    external: true
 ```

-## SSL Zertifikat Konfiguration
-Nach starten des docker containers ist das von caddy erstellte SSL Zertifikat in './caddy_data/pki/authorities/local/root.crt' gefunden werden.
-Relevante Dokumentation:
- [MacOS](https://support.apple.com/guide/keychain-access/add-certificates-to-a-keychain-kyca2431/mac)
- [Linux](https://access.redhat.com/documentation/en-us/red_hat_enterprise_linux/7/html/security_guide/sec-shared-system-certificates)
+## Fortgeschrittene Optionen (für docker compose)
+### Hostman Script Umgebugsvariablen
+- `DOCKER_SOCK_PATH`
+  - DEFAULT: `"/tmp/docker.sock"`
+  - DESCRIPTION: Docker Socket Pfad
+- `NETWORK_NAME`
+  - DEFAULT: `"proxy"`
+  - DESCRIPTION: Docker netzwerk in dem nach Containern gesucht wird
+
+### Template Spezifische Umgebungsvariablen
+#### Caddy
+- `DOCKER_CADDY_NAME`
+  - DEFAULT: `proxy`
+  - DESCRIPTION: Der Caddy Container-/Host-Name unter dem das Caddy Admin Interface erreichbar ist.
+- `DOCKER_CADDY_PORT`
+  - DEFAULT: `2020`
+  - DESCRIPTION: Der Port des Caddy Admin Interfaces.
+
+#### Hosts
+- `HOST_CONF_PATH`
+  - DEFAULT: `"/config/hosts"`
+  - DESCRIPTION: hosts Datei-Pfad
+- `RESOLVE_DOCKERHOST`
+  - DEFAULT: `false`
+  - DESCRIPTION: Setzt ob IP Addressen in der hosts Datei auf die der Docker Container (true) oder 127.0.0.1 (false) aufgelöst werden.
+- `DOCKER_HOSTNAME_VAR`
+  - DEFAULT: `"LOCAL_WEB_HOST"` (entspricht: `local.web.host`)
+  - DESCRIPTION: Docker Container Umgebungsvariable die den Hostnamen bestimmt (das auto generierte Öabel ist lower case und verwendet Punkte statt Unterstriche)
+
+#### SQLProxy
+- `EXCLUDE_USERPASS`
+  - DEFAULT: `false`
+  - DESCRIPTION: Ob Nutzername und Passwort für die Authentifizierung ausgelassen werden soll.


-## SQL Proxy
-### Initiales Setup
-Öffne ein Terminal und führe die `sqlproxy_setup.sh` Datei aus.
-Das Script:
-1. Installiert den `myssh` befehl nach `$HOME/bin` und fügt diesen ggf zur PATH variable hinzu
-2. Erstellt SSH Keys für den SSH Docker Container (wenn diese nicht bereits existieren)
-3. Erstellt und Konfiguriert einen Client SSH Key, dessen public Key wird dem SSH Docker Container hinzugefügt
-
-### Starten des Reverse-Proxies
-Der SQL Proxy kann über docker compose gestartet werden
-```bash
-docker compose -f docker-compose.yml -f docker-compose-sqlproxy.yml up -d
-```
-
-### Hinzufügen von DB Docker Containern
-Container werden automatisch vom reverse proxy/host manager aufgegriffen wenn sie:
-1. Die Umgebungsvariable `local.db.type` und `local.db.host` gesetzt haben.
-2. Im gleichen Docker-Netzwek (Default: `proxy`) sind.
-
-Optional kann über das Label `local.web.port` der gebundene Port gesetzt werden (Default mysql: 3306, Default psql: 5432)
-
-### myssh cli
+# myssh cli
 Der SQL Proxy Client hat folgende Optionen:
 ```bash
 ls: Gibt eine Liste an verfügbaren DB Hosts zurück
@ -96,31 +138,11 @@ connect $DB_HOST [-u $USERNAME ] [-p $PASSWORD]: Erstellt einen Tunnel zum DB Ho
 disconnect: schließt die SSH Multiplex Session und damit auch alle aktuellen Verbindungen
 ```

-#### myssh Umgebungsvariablen
+## myssh Umgebungsvariablen
 - `SQL_PROXY_HOST`
  - DEFAULT: `"localhost"`
  - DESCRIPTION: Setzt den Target Proxy Host
- `SQL_PROXY_DB_PORT`
-  - DEFAULT: sql: `"3306"`, psql: `"5432"`
-  - DESCRIPTION: Setzt den DB Host Target Port
- `SQL_CLI_TEMPLATE`
+- (DEPRECATED) `SQL_CLI_TEMPLATE`
  - DEFAULT LINUX: `'mysql --protocol=TCP -u $MYSQL_USERNAME -p$MYSQL_PASSWORD -h localhost -P 3306'`
  - DEFAULT MACOS: `'open \"mysql://$MYSQL_USERNAME:$MYSQL_PASSWORD@localhost:3306\" -a \"Sequel Ace\"'`
  - DESCRIPTION: Setzt den auszuführenden Datenbank-Client Befehl
-
-## Hostman Umgebugsvariablen (für docker compose)
- `DOCKER_SOCK_PATH`
-  - DEFAULT: `"/tmp/docker.sock"`
-  - DESCRIPTION: Docker Socket Pfad
- `NETWORK_NAME`
-  - DEFAULT: `"proxy"`
-  - DESCRIPTION: Docker netzwerk in dem nach Containern gesucht wird
- `RESOLVE_DOCKERHOST`
-  - DEFAULT: `false`
-  - DESCRIPTION: Setzt ob IP Addressen in der hosts Datei auf die der Docker Container (true) oder 127.0.0.1 (false) aufgelöst werden.
- `HOST_CONF_PATH`
-  - DEFAULT: `"/tmp/hosts"`
-  - DESCRIPTION: hosts Datei-Pfad
- `DOCKER_HOSTNAME_VAR`
-  - DEFAULT: `"VIRTUAL_HOST"`
-  - DESCRIPTION: Docker Container Umgebungsvariable die den Hostnamen bestimmt