App und Doku veröffentlichen¶

Ziel¶

Diese Seite beschreibt den vollständigen Prüfablauf, um eine App, ihre Dokumentation und optional das Developer Playbook öffentlich erreichbar zu machen.

Die Anleitung verbindet die vorherigen Schritte:

Domain und DNS
Port-Strategie
Nginx Reverse Proxy
HTTPS mit Certbot
öffentlicher Funktionstest

Grundprinzip¶

Eine Veröffentlichung ist erst abgeschlossen, wenn alle Ebenen funktionieren:

DNS
↓
Server
↓
Docker-Container
↓
lokaler Port
↓
Nginx Reverse Proxy
↓
HTTPS
↓
Browser-Test

Es reicht nicht, nur den Container zu starten. Die öffentliche URL muss ebenfalls geprüft werden.

Empfohlene Serverstruktur¶

Für mehrere Projekte wird folgende Struktur empfohlen:

/home/<user>/workspace/
├── developer-playbook/
└── apps/
    ├── App1/
    ├── App2/
    └── App3/

Das Developer Playbook liegt direkt unter workspace.

Konkrete Apps liegen unter workspace/apps.

Praxisbeispiel Immohai¶

Aktueller Stand:

/home/fober/workspace/developer-playbook
/home/fober/projects/immohai

Geplante spätere Zielstruktur:

/home/fober/workspace/
├── developer-playbook/
└── apps/
    └── Immohai/

Immohai wird später kontrolliert nach workspace/apps/Immohai verschoben.

Diese Migration ist nicht Teil der Veröffentlichung. Sie muss separat vorbereitet und geprüft werden.

Veröffentlichungsziel¶

Allgemeines Schema:

https://playbook.example.com
https://app1.example.com
https://docs.app1.example.com

Praxisbeispiel:

https://playbook.ohaisoft.com
https://immohai.ohaisoft.com
https://docs.immohai.ohaisoft.com

Schritt 1: Git-Status prüfen¶

Vor Änderungen im Projektordner:

git status

Erwartung:

working tree clean

Falls lokale Änderungen vorhanden sind:

prüfen
committen
oder bewusst verwerfen

Schritt 2: Docker-Container prüfen¶

Im jeweiligen Projektordner:

docker compose ps

Allgemein:

docker ps --format "table {{.Names}}\t{{.Ports}}"

Erwartung im Praxisbeispiel:

developer-playbook-docs    127.0.0.1:8100->8000/tcp
immohai-web                127.0.0.1:8200->80/tcp
immohai-docs               127.0.0.1:8201->8000/tcp

Schritt 3: Lokale Ports testen¶

Auf dem Server:

curl -I http://127.0.0.1:8100
curl -I http://127.0.0.1:8200
curl -I http://127.0.0.1:8201

Erwartung:

HTTP/1.1 200 OK

oder ein anderer erfolgreicher HTTP-Status.

Wenn ein lokaler Dienst nicht erreichbar ist, liegt das Problem noch vor Nginx.

Dann prüfen:

docker compose ps
docker compose logs --tail=100

Schritt 4: DNS prüfen¶

nslookup playbook.ohaisoft.com
nslookup immohai.ohaisoft.com
nslookup docs.immohai.ohaisoft.com

Erwartung:

Address: 46.225.28.194

Wenn DNS nicht stimmt, zuerst DNS korrigieren.

Schritt 5: Nginx prüfen¶

sudo nginx -t

Erwartung:

syntax is ok
test is successful

Status prüfen:

sudo systemctl status nginx

Nginx neu laden:

sudo systemctl reload nginx

Schritt 6: HTTP öffentlich testen¶

curl -I http://playbook.ohaisoft.com
curl -I http://immohai.ohaisoft.com
curl -I http://docs.immohai.ohaisoft.com

Erwartung vor HTTPS:

HTTP/1.1 200 OK

Erwartung nach HTTPS-Einrichtung:

301 Moved Permanently

oder eine Weiterleitung auf HTTPS.

Schritt 7: HTTPS öffentlich testen¶

curl -I https://playbook.ohaisoft.com
curl -I https://immohai.ohaisoft.com
curl -I https://docs.immohai.ohaisoft.com

Erwartung:

HTTP/2 200

oder:

HTTP/1.1 200 OK

Schritt 8: Certbot Renewal testen¶

sudo certbot renew --dry-run

Erwartung:

Congratulations, all simulated renewals succeeded

Schritt 9: Browser-Test¶

Im Browser prüfen:

https://playbook.ohaisoft.com
https://immohai.ohaisoft.com
https://docs.immohai.ohaisoft.com

Zu prüfen:

richtige Seite wird angezeigt
HTTPS ist aktiv
keine Zertifikatswarnung
App und Dokumentation zeigen unterschiedliche Inhalte
Navigation funktioniert
keine offensichtlichen 404-Fehler

Schritt 10: Dokumentation aktualisieren¶

Nach erfolgreicher Veröffentlichung dokumentieren:

öffentliche URL
lokaler Port
Docker-Service
Nginx-Konfiguration
HTTPS-Status
besondere Fehler und Lösungen

Keine Secrets dokumentieren.

Praxisbeispiel: aktueller Stand¶

Dienst	Öffentliche URL	Lokaler Port	Container
Developer Playbook	`https://playbook.ohaisoft.com`	`127.0.0.1:8100`	`developer-playbook-docs`
Immohai App	`https://immohai.ohaisoft.com`	`127.0.0.1:8200`	`immohai-web`
Immohai Dokumentation	`https://docs.immohai.ohaisoft.com`	`127.0.0.1:8201`	`immohai-docs`

Typischer Prüfblock¶

Für das Praxisbeispiel:

cd /home/fober/workspace/developer-playbook
git status
docker compose ps
curl -I http://127.0.0.1:8100
curl -I https://playbook.ohaisoft.com

cd /home/fober/projects/immohai
git status
docker compose ps
curl -I http://127.0.0.1:8200
curl -I http://127.0.0.1:8201
curl -I https://immohai.ohaisoft.com
curl -I https://docs.immohai.ohaisoft.com

sudo nginx -t
sudo certbot renew --dry-run

Best Practices¶

Erst lokal testen, dann öffentlich testen.
Erst HTTP testen, dann HTTPS testen.
Nach jeder Nginx-Änderung sudo nginx -t ausführen.
Nach jeder Docker-Änderung Containerstatus prüfen.
Bei Fehlern immer Ebene für Ebene prüfen: DNS, Docker, Nginx, HTTPS.
Öffentliche URLs und lokale Ports dokumentieren.
Keine Secrets dokumentieren.

Typische Fehler¶

Fehler	Ursache	Lösung
lokale App funktioniert nicht	Container läuft nicht	`docker compose ps` und Logs prüfen
öffentliche URL funktioniert nicht	Nginx oder DNS falsch	DNS und Nginx prüfen
HTTPS funktioniert nicht	Zertifikat fehlt oder Certbot-Problem	Certbot prüfen
falscher Inhalt erscheint	`server_name` oder `proxy_pass` falsch	Nginx-Dateien prüfen
Browser zeigt alte Seite	Cache oder Container nicht aktualisiert	Container neu starten und Cache prüfen
MkDocs zeigt alte Navigation	Container nicht neu gestartet	`docker compose restart`

Checkliste¶

[ ] Git-Status geprüft
[ ] Docker-Container laufen
[ ] lokale Ports erreichbar
[ ] DNS zeigt auf Server
[ ] Nginx-Konfiguration gültig
[ ] HTTP öffentlich getestet
[ ] HTTPS öffentlich getestet
[ ] Certbot Renewal getestet
[ ] Browser-Test durchgeführt
[ ] Dokumentation aktualisiert