From 9e76382fa86987a271e1ad12551853316afcaed7 Mon Sep 17 00:00:00 2001
From: Michael Schiemer <kontakt@michaelschiemer.de>
Date: Sun, 18 May 2025 17:14:15 +0200
Subject: [PATCH] docs: add initial docs for commits, deployment, env variables
 and setup

---
 docs/COMMITS.md    | 76 ++++++++++++++++++++++++++++++++++++++++++++++
 docs/DEPLOYMENT.md | 43 ++++++++++++++++++++++++++
 docs/ENV.md        | 40 ++++++++++++++++++++++++
 docs/SETUP.md      | 48 +++++++++++++++++++++++++++++
 4 files changed, 207 insertions(+)
 create mode 100644 docs/COMMITS.md
 create mode 100644 docs/DEPLOYMENT.md
 create mode 100644 docs/ENV.md
 create mode 100644 docs/SETUP.md

diff --git a/docs/COMMITS.md b/docs/COMMITS.md
new file mode 100644
index 00000000..d9b5035e
--- /dev/null
+++ b/docs/COMMITS.md
@@ -0,0 +1,76 @@
+# 📘 Commit-Konventionen – Conventional Commits
+
+Dieses Projekt verwendet das [Conventional Commits](https://www.conventionalcommits.org)-Format für einheitliche und nachvollziehbare Commit-Nachrichten.
+
+---
+
+## 🔧 Format
+
+```
+<type>[optional scope]: <beschreibung>
+```
+
+**Beispiel:**
+
+```
+feat: add Ansible deploy playbook
+```
+
+- **Englisch**
+- **Präsens** (z. B. „add“, nicht „added“)
+- **Keine abschließenden Punkte**
+- **Optionaler Body** bei größeren Änderungen
+
+---
+
+## 📦 Commit-Typen
+
+| Typ        | Beschreibung                                           |
+|------------|--------------------------------------------------------|
+| `feat`     | ✨ Neues Feature                                        |
+| `fix`      | 🐛 Fehlerbehebung                                      |
+| `docs`     | 📘 Nur Dokumentation (z. B. README, .env.example)      |
+| `style`    | 🎨 Formatierung, keine Änderung am Verhalten           |
+| `refactor` | 🔁 Code-Umstrukturierung ohne neues Verhalten/Feature  |
+| `test`     | 🧪 Tests hinzufügen oder anpassen                      |
+| `chore`    | 🔧 Projektpflege (z. B. `.gitignore`, `.mailmap`, Cleanup) |
+
+---
+
+## ✅ Gute Commit-Beispiele
+
+```bash
+chore: initial commit with Docker + Ansible setup
+feat: add restart task to deploy role
+fix: correct Docker volume path
+docs: add .env.example as reference
+chore: add .mailmap to unify author identity
+```
+
+---
+
+## 🛑 Vermeide unklare Messages wie:
+
+```bash
+"update"
+"bugfixes"
+"misc"
+"more changes"
+```
+
+Diese helfen später weder dir noch Tools oder anderen.
+
+---
+
+## 🧠 Tipps
+
+- Nutze aussagekräftige, prägnante Beschreibungen
+- Schreibe deine Commits so, dass man daraus verstehen kann, **was passiert** – ohne Git-Diff zu lesen
+- Wenn du mehrere Dinge in einem Commit machst, überlege, ob es **mehrere Commits** sein sollten
+
+---
+
+## 📚 Weitere Infos
+
+- [conventionalcommits.org](https://www.conventionalcommits.org)
+- [semantic-release](https://semantic-release.gitbook.io/semantic-release/) – für automatische Releases basierend auf Commit-Typen
diff --git a/docs/DEPLOYMENT.md b/docs/DEPLOYMENT.md
new file mode 100644
index 00000000..dbb52a92
--- /dev/null
+++ b/docs/DEPLOYMENT.md
@@ -0,0 +1,43 @@
+# 🚀 Deployment-Anleitung (Ansible-basiert)
+
+Dieses Projekt verwendet Ansible zur automatisierten Bereitstellung.
+
+---
+
+## 🧱 Struktur
+
+- `ansible/setup.yml` → Bereitet Zielserver vor (Docker, Git, Benutzer)
+- `ansible/deploy.yml` → Clont Projekt & startet Docker Compose
+
+---
+
+## 📂 Vorbereitung
+
+1. Zielserver (Debian)
+2. SSH-Zugang (z. B. via `~/.ssh/id_rsa`)
+3. Eintrag in `ansible/inventory.ini`:
+
+```ini
+[web]
+123.123.123.123 ansible_user=root
+```
+
+---
+
+## ▶️ Ausführen
+
+```bash
+# Setup ausführen (nur einmal)
+ansible-playbook -i ansible/inventory.ini ansible/setup.yml
+
+# Projekt deployen (beliebig oft)
+ansible-playbook -i ansible/inventory.ini ansible/deploy.yml
+```
+
+---
+
+## 🔐 Hinweis
+
+- `.env` wird **nicht** automatisch übertragen
+- Serverpfade ggf. per `dest:` in `git:`-Modul anpassen
+
diff --git a/docs/ENV.md b/docs/ENV.md
new file mode 100644
index 00000000..9f1c7fe1
--- /dev/null
+++ b/docs/ENV.md
@@ -0,0 +1,40 @@
+# 🔐 Umgebungsvariablen (.env)
+
+Dieses Projekt verwendet `.env`-Dateien zur Konfiguration von Docker Compose und anderen Tools.
+
+---
+
+## 📄 Beispiel: .env
+
+```env
+COMPOSE_PROJECT_NAME=michaelschiemer
+APP_PORT=8080
+PHP_VERSION=8.2
+```
+
+> Diese Datei sollte **nicht** versioniert werden.
+
+---
+
+## 📄 Beispiel: .env.example
+
+Diese Datei enthält Beispielwerte und wird mit dem Projekt mitgeliefert.
+
+---
+
+## 📌 Nutzung in docker-compose.yml
+
+```yaml
+php:
+  image: php:${PHP_VERSION}-fpm
+web:
+  ports:
+    - "${APP_PORT}:80"
+```
+
+---
+
+## 📦 Empfehlung
+
+- `.env` → lokal, nicht versioniert
+- `.env.example` → ins Git, immer aktuell halten
diff --git a/docs/SETUP.md b/docs/SETUP.md
new file mode 100644
index 00000000..52ddfa8f
--- /dev/null
+++ b/docs/SETUP.md
@@ -0,0 +1,48 @@
+# ⚙️ Setup-Anleitung
+
+Diese Datei beschreibt, wie du das Projekt lokal einrichtest und startest.
+
+---
+
+## 🔧 Voraussetzungen
+
+- Docker & Docker Compose
+- Python 3 (für Ansible, optional pipx)
+- Optional: Ansible (für Server-Setup)
+- Optional: PhpStorm oder VS Code
+
+---
+
+## 📦 Projektstruktur
+
+```
+.
+├── app/              # PHP/NGINX-Anwendung
+├── ansible/          # Setup- und Deployment-Playbooks
+├── docker-compose.yml
+├── .env              # Lokale Konfiguration (nicht versioniert)
+├── Makefile          # Komfortbefehle
+└── docs/             # Dokumentation
+```
+
+---
+
+## ▶️ Lokaler Start
+
+```bash
+# Container starten
+docker compose up --build
+
+# Alternativ mit Makefile
+make deploy
+```
+
+---
+
+## 🧪 Lokale Tests
+
+- `http://localhost:8080` → NGINX + PHP
+- Logs anzeigen: `docker compose logs -f`
+
+---
+