Readme.md Dokumentation + Start-Script für Linux/Mac.

Readme.md

@@ -0,0 +1,122 @@
+# HostBBQ Wordpress Development Kit (WDK)
+
+![Docker Desktop mit WDK Stack](./docs/img/docker_stack.png "Docker Desktop mit WDK Stack")
+
+## Inhalt
+
+1. [Project Information](#1-project-Information)
+2. [Systemvoraussetzungen](#2-systemvoraussetzungen) 
+    1. [Administrativer Benutzer](#21-administrativer-benutzer)
+    2. [Docker](#22-docker)
+3. [Quick Start](#3-quick-start)
+    1. [Docker installieren](#31-docker-installieren)
+    2. [Fake Domain Name in Hosts Datei](#32-fake-domain-name-in-hosts-datei)
+    3. [Docker Desktop öffnen / starten](#33-docker-desktop-öffnen--starten)
+    4. [Docker Stack starten](#34-docker-stack-starten)
+    5. [Webseite aufrufen](#35-webseite-aufrufen)
+
+## 1. Project Information
+
+Das **HostBBQ Wordpress Development Kit** (WDK) ist ein vorgefertigter "Docker Stack", der alles beinhaltet, was man zum Betrieb einer Wordpress Instanz benötigt:
+- PHP-fähiger Webserver (apache) mit Wordpress-Installation
+- MySQL-Datenbankserver (MariaDB) mit Datenbank für die Instanz
+- HTTPS-Reverse Proxy (nginx) mit **_self-signed_** SSL-Zertifikat
+
+## 2. Systemvoraussetzungen
+
+### 2.1 Administrativer Benutzer
+
+Zur Installation von Software wie **_Docker_** und auch zur Bearbeitung der **_hosts_**-Datei wird ein Benutzer benötigt, der zumindest auf der lokalen Maschine über Administrative Rechte verfügt.
+
+### 2.2 Docker
+
+Das **WDK** setzt auf die Virtualisierungs-Software **_Docker_** auf. Diese ermöglicht es, einzelne Anwendungen ("Services") in eigenen, gekapselten Umgebungen ("Containern") auszuführen und über virtuelle Netzwerkadapter miteinander zu verknüpfen.
+
+Das hat den Vorteil, dass nicht auf dem Host-System ("Deinem Computer") alle Umgebungssoftware für den Betrieb der Services installiert sein muss, sondern diese Abhängigkeiten werden innerhalb der Container installiert und sind somit immer auf dem Versions-Stand, den der Service benötigt - Es enstehen keine Versionskonflikte mehr, wenn man auf der selben Maschine verschiedene Webservices betreiben möchte, die aber unterschiedliche Umgebungssoftware benötigen. Und alles ist mit einem Klick auch wieder entfernt und hinterlässt keine Datei- oder Konfigurations-Leichen im Host-System.
+
+Das einzige, was auf dem Host-System installiert werden muss, ist die recht schlanke **_Docker Engine_**:
+- [**_Docker Desktop_** for Windows/Mac](https://www.docker.com/products/docker-desktop)
+- [**_Docker_**](https://hub.docker.com/search?offering=community&operating_system=linux&q=&type=edition) for Linux
+
+
+
+## 3. Quick Start
+
+### 3.1 Docker installieren
+
+Folge einem der obigen Links zu richtigen Installationsdatei für dein Betriebssystem und installiere **_Docker_** (Desktop) mit den Standard-Einstellungen. (System-Neustart nach Installation könnte hilfreich sein)
+
+### 3.2 Fake Domain Name in Hosts Datei:
+
+> ℹ️ Wozu ist das gut?
+> 
+> Der Docker Stack, der im nächsten Schritt gestartet wird, startet einen Webserver auf deinem Computer. Dieser wäre ( - der geneigte Computer-Bild-Leser weiß es vielleicht bereits - ) auch ohne diesen Schritt schon erreichbar über die URL https://localhost oder https://127.0.0.1.
+>
+> Eine Wordpress-Instanz ist jedoch sehr empfindlich, was diese URL angeht. Besonders die URL, über die man die Wordpress-Instanz das erste Mal aufruft und einrichtet ist ausschlaggebend: Bei der Einrichtung speichert sich Wordpress in seiner Datenbank die aktive URL als seine "Basis-URL" für alles, das im System geschieht. Also alle verlinkten Systemresourcen, Bild-Inhalte, etc. werden mit dieser Basis-URL verknüpft, Aufrufe über andere URLs als diese werden auf die Original-URL umgeleitet, und so weiter, was es hinterher schwierig macht, ein einmal eingerichtetes System auf einen anderen Server / eine andere Domain umzuziehen.
+>
+> Sinn dieser Aktion ist es also, die URL / Domain, unter der die Wordpress-Instanz später erreichbar sein soll, jetzt schon lokal so hin zu faken, dass die gespeicherten Inhalte und Konfigurationen später nur auf den letztendlichen Zielserver übertragen werden müssen, ohne alles anpassen zu müssen.
+
+1. Öffne einen Text-Editor mit Administrativen Privilegien:
+    1. Unter Windows:
+        * Startmenü öffnen
+        * "notepad" eingeben (Cortana Suchleiste)
+        * Rechtsklick auf den Blauen Editor -> Als Administrator ausführen
+    2. Unter Linux / Mac:
+        * Öffne ein Terminal
+2. Öffne die Hosts Datei:
+    1. Unter Windows:
+        * C:\Windows\System32\drivers\etc\hosts
+    2. Unter Linux / Mac:
+        * /etc/hosts
+3. Füge folgende Zeile am Ende der Datei hinzu:
+    ```
+    127.0.0.1   meine-wunschdomain.de   www.meine-wunschdomain.de
+    ```
+    ℹ️ Ersetze "meine-wunschdomain.de" durch die Domain, unter der deine Seite später erreichbar sein soll. Am besten überprüfst du auch vorher, ob diese noch verfügbar ist.
+    
+    ℹ️ Die Leerstellen zwischen den drei Angaben können Leerzeichen oder Tabs sein - das ist egal.
+4. Datei speichern und verlassen.
+
+### 3.3 Docker Desktop öffnen / starten
+
+**Unter Windows**: Vergewissere dich, dass der Dienst von Docker Desktop for Windows läuft.
+
+Im Windows Systray (Unten rechts) findest du folgendes Icon: 
+
+![Windows Systray Icon von Docker](./docs/img/docker_tray.png)
+
+> ℹ️ Solltest du hier kein solches Icon finden, läuft "Docker Desktop" noch nicht. Dann einfach starten über das Startmenü / Cortana Suche / ...
+
+Mit einem Doppelklick auf das Systray Icon öffnet sich das Docker Desktop "Dashboard".
+
+Vergewissere dich hier, dass der Status unten Links wie folgt aussieht und der Status "Running" beim darüberfahren mit der Maus erscheint:
+
+![Docker Desktop - Status: RUNNING](./docs/img/docker_desktop_running.png)
+
+Ist der Status Gelb (und nicht "Starting...") oder gar Rot, öffne nochmal den Systray, klicke mit Rechtsklick auf das Icon und wähle die Option "Restart Docker...".
+
+
+### 3.4 Docker Stack starten
+
+- Windows
+
+    ![Starte start.bat per Doppelclick](./docs/img/start_batch.png)
+
+- Linux / Mac
+
+    ```bash
+    $ ./start.sh
+    ```
+
+Anschließend rattert ein Prozess los, der sehr viel Zeug ausgibt, das jetzt an dieser Stelle zu Umfangreich wäre, zu erklären. Ist auch nicht besonders wichtig - erst im Fehlerfall.
+
+Ist dieser Prozess durchgelaufen, sollte das Docker Dashboard so aussehen wie das [Titelbild oben](#hostbbq-wordpress-development-kit-wdk).
+
+### 3.5 Webseite aufrufen
+Gib nun einfach die URL http://meine-wunschdomain.de in die Adresszeile deines Browsers ein - et voilà:
+
+> ⚠ Dein Browser oder Internet Security - Programm könnte an dieser Stelle meckern, dass es "unsicher" oder "nicht vertrauenswürdig" ist, diese Seite zu öffnen. Dies liegt schlicht und einfach an einem SSL-Zertifikat, das (für den Zweck der Lokalen Entwicklung ausreichend) "selbst" signiert ist und nicht von einer großen "Certificate Authority" geprüft wurde. Einfach mit "Ich kenne das Risiko", "Trotzdem besuchen", ö.ä. übergehen. Keine Gefahr 😉.
+
+Es öffnet sich ein Einrichtungsassistent, mit dem du Sprache, Benutzer und E-Mail deines Systems einrichten kannst.
+
+> ⚠ Der MySQL Server braucht beim ersten Start ein wenig länger, um das Initiale Datenbank-Setup durchzuführen. Sollte die Seite also Melden "Error Connecting to Database..." o.ä., könnte es vielleicht helfen, noch 1-2 Minuten zu warten und. ggf. den Log des MySQL Docker Containers im Dashboard zu prüfen.

start.sh

@@ -0,0 +1,10 @@
+#!/bin/bash
+if [ ! -d "./wordpress/html" ]; then
+    echo "Erzeuge Volume ./wordpress/html"
+    mkdir ./wordpress/html
+fi
+if [ ! -d "./mysql/db" ]; then
+    echo "Erzeuge Volume ./mysql/db"
+    mkdir ./mysql/db
+fi
+docker compose up -d --build --force-recreate