Developer Playbook¶
Das Developer Playbook ist eine wiederverwendbare technische Dokumentation für private und kleinere professionelle Softwareprojekte.
Es beschreibt, wie ein Projekt von der Servereinrichtung bis zur veröffentlichten Webapp aufgebaut, dokumentiert, betrieben und gewartet werden kann.
Zielgruppe¶
Dieses Playbook richtet sich an Entwicklerinnen, Entwickler und technisch arbeitende Projektverantwortliche, die eigene Softwareprojekte strukturiert aufbauen möchten.
Es ist besonders geeignet für Projekte mit:
- einem Linux-Server
- Git und GitHub
- Docker und Docker Compose
- Nginx als Reverse Proxy
- HTTPS über Let's Encrypt
- MkDocs für technische Dokumentation
- Remote-Entwicklung mit VS Code
Grundprinzipien¶
| Prinzip | Bedeutung |
|---|---|
| Wiederverwendbarkeit | Anleitungen sollen nicht nur für ein einzelnes Projekt gelten. |
| Nachvollziehbarkeit | Entscheidungen werden mit Begründung dokumentiert. |
| Trennung von Allgemein und Konkret | Allgemeine Empfehlungen werden von Projektbeispielen getrennt. |
| Sicherheit | Secrets, Passwörter, Tokens und Private Keys werden nicht dokumentiert. |
| Wartbarkeit | Struktur, Checklisten und Fehlerlösungen sollen langfristig nutzbar bleiben. |
Struktur¶
| Bereich | Inhalt |
|---|---|
| Setup | Grundlegende Einrichtung von Server, Git, Docker, Nginx, Entwicklungsumgebung und Veröffentlichung |
| Veröffentlichung | Domain, DNS, lokale Ports, Reverse Proxy, HTTPS und öffentliche Tests als Teil des Setups |
| Troubleshooting | Typische Fehler und Lösungen |
| Checklisten | Wiederverwendbare Prüf- und Arbeitslisten |
| Betrieb und Wartung | Grundlagen für Updates, Logs, Monitoring, Backups und spätere Migrationen |
Reihenfolge¶
Das Playbook folgt einem praktischen Ablauf:
Server auswählen
↓
Server einrichten und absichern
↓
Git und GitHub einrichten
↓
Docker und Docker Compose installieren
↓
Projektstruktur anlegen
↓
App und Dokumentation lokal auf Server-Ports starten
↓
Domain und DNS einrichten
↓
Nginx Reverse Proxy einrichten
↓
HTTPS mit Certbot aktivieren
↓
öffentliche URLs testen
↓
typische Fehler beheben und Checklisten abarbeiten
Praxisbeispiel Immohai¶
Immohai dient als konkretes Praxisbeispiel für dieses Playbook.
| Thema | Entscheidung |
|---|---|
| Serveranbieter | Hetzner Cloud |
| Hetzner-Projekt | AppsOhai |
| Servername | ubuntu-4gb-nbg1-1 |
| Serverbetriebssystem | Ubuntu LTS |
| Server-Benutzer | fober |
| Containerisierung | Docker Compose |
| Reverse Proxy | Nginx |
| HTTPS | Certbot / Let's Encrypt |
| Dokumentation | MkDocs |
| Remote-Entwicklung | VS Code Remote SSH |
| App-Domain | immohai.ohaisoft.com |
| Doku-Domain | docs.immohai.ohaisoft.com |
| Playbook-Domain | playbook.ohaisoft.com |
Abgrenzung¶
Das Developer Playbook enthält allgemeine, wiederverwendbare Anleitungen.
Immohai-spezifische Projektdokumentation bleibt im Immohai-Repository. Das Playbook darf Immohai als Praxisbeispiel verwenden, soll aber nicht zu einer reinen Immohai-Dokumentation werden.
Sicherheitsregel¶
In diesem Playbook werden keine Zugangsdaten gespeichert.
Nicht zulässig sind insbesondere:
- Passwörter
- API-Tokens
- SSH Private Keys
- Datenbank-Zugangsdaten
- persönliche Zugangsdaten
.env-Dateien mit Secrets
Öffentliche IP-Adressen, Domains, Ports und allgemeine Konfigurationen dürfen als technische Dokumentation verwendet werden, sofern daraus keine Zugangsdaten hervorgehen.