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 zum laufenden Deployment aufgebaut, dokumentiert 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 und Entwicklungsumgebung |
| Deployment | Veröffentlichung von Anwendungen über Domain, DNS, Reverse Proxy und HTTPS |
| Troubleshooting | Typische Fehler und Lösungen |
| Entscheidungen | Technische Entscheidungen und Begründungen |
| Changelog | Änderungen am Playbook |
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 |
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.