From f0cbc32c365ea11ba7bf3997a455baea416e9932 Mon Sep 17 00:00:00 2001 From: Kevin Baensch Date: Fri, 6 Jan 2023 08:53:54 +0100 Subject: [PATCH] Update Documentation --- README.md | 130 +++++++++++++++++++++++++++++++----------------------- 1 file changed, 76 insertions(+), 54 deletions(-) diff --git a/README.md b/README.md index 6439ffe..f5786b2 100644 --- 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