Zum Inhalt

2026-06-30 – Trennung von Immohai-Dokumentation und Developer Playbook

Ziel

Die Dokumentationsstruktur wurde bereinigt, damit Immohai-Projektdokumentation und allgemeines Developer-Playbook-Material künftig sauber getrennt werden können.

Immohai bleibt das konkrete Praxisprojekt. Das Developer Playbook soll später als eigenständiges, projektübergreifendes Repository geführt werden.

Ausgangslage

Die Immohai-Dokumentation enthielt bisher sowohl projektspezifische Inhalte als auch allgemeine Anleitungen zu Servereinrichtung, Git, Docker, Nginx, Domains, HTTPS und Entwicklungsumgebung.

Dadurch war die Dokumentation funktional, aber inhaltlich vermischt.

Der Ordner docs/setup/ enthielt viele Inhalte, die nicht nur für Immohai gelten, sondern später für mehrere Apps wiederverwendet werden sollen.

Entscheidung

Die Dokumentation wurde in zwei Bereiche getrennt:

docs/
→ Immohai-spezifische Projektdokumentation

playbook-staging/
→ allgemeine Inhalte für das spätere Developer Playbook

Der Bereich playbook-staging/ ist ein temporärer Übergangsbereich innerhalb des Immohai-Repositories. Er dient dazu, allgemeine Inhalte zu sammeln und vorzubereiten, bevor sie in ein eigenes Repository übertragen werden.

Neue Struktur

Aktueller Zielzustand:

Immohai/
├── docs/
│   ├── api/
│   ├── architecture/
│   ├── calculations/
│   ├── changelog/
│   ├── decisions/
│   ├── deployment/
│   ├── document-templates/
│   ├── journal/
│   ├── project/
│   ├── roadmap/
│   ├── user-guide/
│   └── index.md
│
├── playbook-staging/
│   ├── setup/
│   └── deployment/
│
├── docker-compose.yml
├── mkdocs.yml
└── README.md

Verschobene Inhalte

Die allgemeinen Setup-Inhalte wurden aus der Immohai-Dokumentation in den Playbook-Staging-Bereich verschoben:

docs/setup/
→ playbook-staging/setup/

Dazu gehören unter anderem:

  • Server-Auswahl
  • Server-Einrichtung
  • Benutzer und SSH
  • Firewall und Sicherheit
  • Backups
  • Git und GitHub
  • Docker und Docker Compose
  • Nginx
  • SSL
  • Monitoring
  • Logging
  • Windows-PC
  • VS Code
  • Remote SSH
  • Python
  • Terminal
  • Troubleshooting

Diese Inhalte sind nicht gelöscht, sondern nur aus der Immohai-Doku herausgelöst.

Deployment-Dokumentation

Die Deployment-Dokumentation wurde ebenfalls getrennt.

Immohai-spezifische Deployment-Dokumentation bleibt unter:

docs/deployment/

Allgemeine Deployment-Anleitungen für das spätere Developer Playbook liegen unter:

playbook-staging/deployment/

Aktuelle Dateien:

docs/deployment/index.md
docs/deployment/domain-dns-reverse-proxy.md

playbook-staging/deployment/index.md
playbook-staging/deployment/01-domain-dns-reverse-proxy.md

Immohai-spezifische Deployment-Dokumentation

Die Immohai-Dokumentation beschreibt jetzt konkret:

  • verwendete Domain
  • aktive Subdomains
  • DNS-Einträge
  • lokale Docker-Ports
  • Nginx-Weiterleitungen
  • HTTPS-Status
  • Certbot-Renewal-Test
  • aktuelle öffentliche URLs

Aktuelle URLs:

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

Die spätere Playbook-Subdomain ist vorbereitet:

https://playbook.ohaisoft.com

Allgemeine Playbook-Deployment-Dokumentation

Die allgemeine Anleitung in playbook-staging/deployment/01-domain-dns-reverse-proxy.md beschreibt projektübergreifend:

  • Domain kaufen
  • DNS A-Records einrichten
  • Subdomain-Struktur planen
  • Docker-Container auf lokale Ports legen
  • Nginx Reverse Proxy einrichten
  • Port-80-Konflikte lösen
  • Firewall prüfen
  • HTTPS mit Certbot einrichten
  • automatische Zertifikatserneuerung testen
  • typische Fehler und Checklisten

Immohai dient darin nur noch als Praxisbeispiel.

MkDocs-Navigation

Die Datei mkdocs.yml wurde angepasst.

Der große allgemeine Setup-Bereich wurde aus der Immohai-Navigation entfernt.

Die Immohai-Doku zeigt jetzt vor allem projektspezifische Bereiche:

  • Projekt
  • Architektur
  • Berechnungen
  • Deployment
  • API
  • Entscheidungen
  • Roadmap
  • User Guide
  • Journal
  • Changelog
  • Vorlagen

Der allgemeine Setup-Bereich liegt weiterhin im Repository, aber außerhalb der Immohai-MkDocs-Navigation.

Build-Prüfung

Die MkDocs-Dokumentation wurde geprüft mit:

docker compose exec docs mkdocs build --strict

Ergebnis:

Documentation built in ...

Der Build läuft erfolgreich.

Der allgemeine Hinweis des Material-for-MkDocs-Images zu MkDocs 2.0 ist kein Fehler der Immohai-Dokumentation.

Git-Status

Die Änderungen wurden committed und nach GitHub gepusht.

Damit ist der aktuelle Stand versioniert und auf GitHub gesichert.

Ergebnis

Die Dokumentation ist jetzt besser getrennt:

docs/
→ konkrete Immohai-Projektdokumentation

playbook-staging/
→ vorbereitete Inhalte für das spätere Developer Playbook

Damit ist die Grundlage geschaffen, um als nächsten Schritt ein eigenes Repository für das Developer Playbook anzulegen.

Nächste Schritte

  1. Eigenes GitHub-Repository developer-playbook erstellen.
  2. Lokale Serverstruktur vorbereiten:
/home/fober/workspace/
├── developer-playbook/
└── apps/
    └── Immohai/
  1. Inhalte aus playbook-staging/ in das neue Developer-Playbook-Repository übertragen.
  2. Developer Playbook mit MkDocs einrichten.
  3. Developer Playbook über playbook.ohaisoft.com veröffentlichen.
  4. Immohai später nach /home/fober/workspace/apps/Immohai migrieren.

Checkliste

  • [x] Immohai-Doku und allgemeines Playbook-Material strukturell getrennt
  • [x] docs/setup/ nach playbook-staging/setup/ verschoben
  • [x] Deployment-Dokumentation aufgeteilt
  • [x] Immohai-spezifische Deployment-Doku gekürzt
  • [x] Allgemeine Deployment-Anleitung im Playbook-Staging vorbereitet
  • [x] MkDocs-Navigation bereinigt
  • [x] MkDocs-Build geprüft
  • [x] Änderungen in Git gesichert
  • [ ] Eigenes Repository developer-playbook erstellen
  • [ ] playbook-staging/ in das neue Repository übertragen
  • [ ] playbook.ohaisoft.com einrichten