Baseline standards: design, SOP, CI policy

2025-12-20 15:17:15 +01:00
commit 769462c439
4 changed files with 632 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,96 @@
+# wlkns-dev-standards
+
+## Zweck
+Dieses Repository definiert **verbindliche Entwicklungs‑, Design‑ und CI‑Standards** für Software‑Projekte.
+
+Es ist kein Projekt‑Template im engeren Sinn, sondern ein **Meta‑Repository**:
+- Referenz
+- Regelwerk
+- Entscheidungsgrundlage
+- Qualitätsmaßstab
+
+Alles, was hier beschrieben ist, gilt als **Best Practice** und ist projektübergreifend anwendbar.
+
+---
+
+## Zielgruppe
+- Einzelentwickler mit professionellem Anspruch
+- kleine Teams
+- Homelab‑ und Infrastruktur‑Projekte
+- Open‑Source‑Projekte mit Fokus auf Wartbarkeit
+
+Nicht Zielgruppe:
+- Prototypen ohne Langzeitanspruch
+- schnelle Wegwerf‑Skripte
+- „Hauptsache läuft“-Setups
+
+---
+
+## Grundprinzipien
+
+- **Klarheit vor Cleverness**
+- **Reproduzierbarkeit vor Geschwindigkeit**
+- **Ein erlaubter Weg statt vieler Optionen**
+- **Explizite Regeln statt impliziter Annahmen**
+
+Wenn ein Prozess nur funktioniert, weil man weiß, *wie er gemeint ist*, ist er falsch.
+
+---
+
+## Struktur des Repositories
+
+```text
+wlkns-dev-standards/
+├─ design/        # Design‑System & UI‑Prinzipien
+├─ sop/           # Standard Operating Procedures
+├─ ci/            # CI‑Regeln & Gate‑Policies
+├─ templates/     # Referenz‑ & Start‑Templates
+├─ README.md
+└─ CHANGELOG.md
+```
+
+Jeder Ordner ist thematisch abgeschlossen und unabhängig nutzbar.
+
+---
+
+## Nutzung
+
+Dieses Repository wird **nicht eingebunden**, sondern **referenziert**.
+
+Typische Nutzung:
+- als Entscheidungsgrundlage bei neuen Projekten
+- als Review‑Maßstab
+- als Quelle für Templates
+- als Dokumentation für Dritte
+
+Empfohlen:
+- relevante Dokumente im Projekt verlinken
+- Templates kopieren, nicht verändern
+
+---
+
+## Versionierung
+
+Änderungen an Regeln oder Standards werden:
+- dokumentiert
+- versioniert
+- rückwirkend nachvollziehbar gehalten
+
+Siehe: `CHANGELOG.md`
+
+---
+
+## Status
+
+Aktueller Reifegrad: **aktiv in Entwicklung**
+
+Inhalte gelten als stabil, sofern nicht explizit anders gekennzeichnet.
+
+---
+
+## Lizenz & Veröffentlichung
+
+Das Repository ist derzeit **privat**, wird jedoch mit dem Anspruch gepflegt, jederzeit öffentlich nutzbar zu sein.
+
+Keine Inhalte setzen interne Systeme, Namen oder proprietäre Werkzeuge voraus.
+
--- a/ci/ci_policy.md
+++ b/ci/ci_policy.md
@ -0,0 +1,168 @@
+# CI_POLICY.md
+
+## Zweck
+Diese CI‑Policy definiert **verbindliche Regeln für Continuous Integration** in allen Projekten, die den wlkns‑Standards folgen.
+
+CI ist hier kein Komfort‑Feature, sondern ein **Qualitäts‑ und Sicherheits‑Gate**.
+
+Wenn die CI rot ist, ist das Ergebnis **nicht auslieferbar**. Diskussion zwecklos.
+
+---
+
+## Grundhaltung
+
+- CI ersetzt kein Denken
+- CI erzwingt Mindestqualität
+- CI ist reproduzierbar
+- CI ist deterministisch
+
+Eine Pipeline darf **nichts tun**, was lokal nicht ebenfalls prüfbar ist.
+
+---
+
+## Single Source of Truth
+
+Die fachliche Prüflogik liegt **nicht** in der CI‑Pipeline selbst.
+
+**Regel:**
+> Alles, was die CI prüft, muss lokal über definierte Befehle prüfbar sein.
+
+Bevorzugt:
+- `make check`
+- `make test`
+- `make lint`
+
+Die CI ruft diese Targets lediglich auf.
+
+---
+
+## Mindest‑Stages (verpflichtend)
+
+Jede Pipeline besteht mindestens aus folgenden Stages:
+
+1. **Preflight / Validation**
+2. **Lint / Static Checks**
+3. **Tests**
+4. **Build**
+
+Optional (projektspezifisch):
+- Security‑Scans
+- Image‑Scans
+- Deployment
+
+---
+
+## Stage 1 – Preflight
+
+Ziel:
+- Validierung der Projektstruktur
+- Prüfung der Voraussetzungen
+
+Typische Checks:
+- benötigte Dateien vorhanden
+- `.env.example` vollständig
+- keine Secrets im Repository
+- Tool‑Versionen kompatibel
+
+Fehlschlag ⇒ sofortiger Abbruch.
+
+---
+
+## Stage 2 – Lint / Static Checks
+
+Ziel:
+- einheitlicher Stil
+- frühe Fehlererkennung
+
+Regeln:
+- Linter sind Pflicht
+- Projekt‑spezifische Regeln sind erlaubt
+- Warnungen dürfen **nicht** ignoriert werden
+
+Ein Projekt ohne Linter gilt als unvollständig.
+
+---
+
+## Stage 3 – Tests
+
+Ziel:
+- funktionale Korrektheit
+- Schutz vor Regressionen
+
+Regeln:
+- automatisiert
+- reproduzierbar
+- ohne Seiteneffekte
+
+Keine Tests bedeutet:
+- kein Merge
+- kein Release
+
+---
+
+## Stage 4 – Build
+
+Ziel:
+- verifizierbare Artefakte
+
+Regeln:
+- Build muss lokal reproduzierbar sein
+- bei Containern: Image baubar
+- kein Push bei Fehlschlag
+
+Ein erfolgreicher Build bestätigt **technische Lieferfähigkeit**.
+
+---
+
+## Merge‑ & Release‑Regeln
+
+- Merges nur bei grüner Pipeline
+- Releases nur aus validierten Commits
+- kein Bypass der CI
+
+**Regel:**
+> Ein Commit ohne grüne CI existiert nicht.
+
+---
+
+## Tool‑Neutralität
+
+Diese Policy ist bewusst **CI‑System‑agnostisch**.
+
+Unterstützte Umgebungen (Beispiele):
+- GitHub Actions
+- Gitea Actions
+- GitLab CI
+
+Die Regeln bleiben identisch – nur die Syntax ändert sich.
+
+---
+
+## Verhältnis zu SOPs
+
+Diese CI‑Policy ergänzt die bestehenden SOPs.
+
+Beispiel:
+- Container‑SOP definiert `make check`
+- CI ruft exakt dieses Target auf
+
+Keine doppelte Logik. Keine Abweichungen.
+
+---
+
+## Anti‑Patterns
+
+- CI mit Projekt‑spezifischer Logik
+- Checks nur in der CI, nicht lokal
+- manuelles Überspringen von Stages
+- „temporär deaktivierte“ Tests
+
+Wenn die CI im Weg ist, ist das Problem **nicht** die CI.
+
+---
+
+## Status
+
+Version: **v1.0 (Baseline)**
+
+Änderungen an dieser Policy sind selten, bewusst und versioniert vorzunehmen.
--- a/design/DESIGN.md
+++ b/design/DESIGN.md
@ -0,0 +1,142 @@
+# DESIGN.md
+
+## Ziel
+Dieses Dokument definiert das **visuelle und strukturelle Design‑Fundament** für alle Projekte, die sich an den wlkns‑Standards orientieren.
+
+Ziel ist kein Show‑Design, sondern:
+- hohe Lesbarkeit
+- geringe kognitive Last
+- langfristige Wartbarkeit
+- klare Wiedererkennbarkeit
+
+Design ist hier **Arbeitsmittel**, kein Selbstzweck.
+
+---
+
+## Grundhaltung
+
+- **Light‑Mode first**
+- ruhig, technisch, sachlich
+- modern, aber nicht modisch
+- funktional vor dekorativ
+
+Merksatz:
+> Sieht gut aus. Stört nicht. Funktioniert.
+
+Dark Mode ist optional und wird **abgeleitet**, nicht gleichwertig entworfen.
+
+---
+
+## Farb‑System
+
+### Design‑Prinzipien
+- Farbe transportiert Bedeutung
+- keine rein dekorativen Farben
+- Akzentfarben sparsam einsetzen
+- Rot ist Fehlerfarbe – immer
+
+### Farb‑Tokens (Light Mode)
+
+**Primärfarbe (Identität)**
+- `--color-primary: #1F2A37;`  
+  Verwendung: Header, Navigation, Überschriften
+
+**Akzentfarbe (Interaktion)**
+- `--color-accent: #0EA5A4;`  
+  Verwendung: Links, aktive Zustände, Fokus
+
+**Statusfarben**
+- Success: `#16A34A`
+- Warning: `#D97706`
+- Error: `#DC2626`
+
+**Neutrale Farben**
+- Background: `#F8FAFC`
+- Surface: `#FFFFFF`
+- Border: `#E5E7EB`
+- Text Primary: `#111827`
+- Text Secondary: `#4B5563`
+
+Farben dürfen nur aus diesem Set verwendet werden.
+
+---
+
+## Typografie
+
+### Grundsatz
+Lesbarkeit schlägt Individualität.
+
+### Schriftarten
+- **Primary UI Font:** Inter
+- **Code / Monospace:** JetBrains Mono
+
+### Schriftschnitte
+- Headings: SemiBold
+- Body: Regular
+- Hervorhebung: Medium
+
+### Regeln
+- maximal eine Schriftfamilie pro Kontext
+- keine verspielten Fonts
+- keine Schriftmischung ohne funktionalen Grund
+
+---
+
+## Layout‑Prinzipien
+
+- 8‑px‑Grid
+- Weißraum vor Linien
+- Inhalte in klaren Sections
+- visuelle Hierarchie vor Rahmen
+
+### Komponenten‑Denken
+- Header
+- Content‑Bereich
+- Status / Feedback
+
+Jede Oberfläche soll sich **vorhersehbar** anfühlen.
+
+---
+
+## Interaktion & Feedback
+
+- Hover‑Effekte sind dezent
+- Animationen nur, wenn sie Information transportieren
+- Fokus‑Zustände müssen sichtbar sein
+
+Kein visuelles Feedback ohne funktionale Bedeutung.
+
+---
+
+## Do / Don’t
+
+### Do
+- konsistente Abstände
+- klare Typo‑Hierarchien
+- ruhige Farbflächen
+
+### Don’t
+- harte Kontraste ohne Grund
+- Schatten als Deko
+- mehr als eine Akzentfarbe pro Screen
+
+---
+
+## Geltungsbereich
+
+Dieses Design‑System gilt für:
+- Web‑Oberflächen
+- Desktop‑GUIs
+- Dokumentation
+- Status‑Dashboards
+
+CLI‑Ausgaben orientieren sich an denselben Prinzipien (Lesbarkeit, Klarheit, Zurückhaltung).
+
+---
+
+## Status
+
+Version: **v1.0 (Baseline)**
+
+Änderungen am Design‑Fundament erfolgen bewusst, versioniert und dokumentiert.
+
--- a/sop/container-deployment.md
+++ b/sop/container-deployment.md
@ -0,0 +1,226 @@
+# SOP: Container Deployment (Makefile‑Driven)
+
+**Status:** Operational  
+**Geltungsbereich:** generisch, projekt‑ und technologieübergreifend
+
+---
+
+## Zweck
+Dieses Dokument definiert ein **verbindliches Standard Operating Procedure (SOP)** für containerbasierte Applikationen.
+
+Ziel ist ein Deployment‑Ansatz, der:
+- reproduzierbar
+- sicher
+- nachvollziehbar
+- CI‑fähig
+- agentenfähig
+
+ist – unabhängig von Projekt, Teamgröße oder Hosting‑Umgebung.
+
+---
+
+## Grundprinzip
+
+Das Setup basiert auf einer **strikten Trennung von Verantwortlichkeiten**:
+
+- **Konfiguration:** `.env`
+- **Orchestrierung:** Docker Compose
+- **Steuerung & Validierung:** Makefile
+- **Ausführung:** Container
+
+Das **Makefile ist die einzige erlaubte Benutzerschnittstelle** und damit die Single Source of Truth.
+
+---
+
+## 0. Voraussetzungen & Systemanforderungen
+
+### 0.1 Zielsystem
+- Linux (empfohlen)
+  - Ubuntu ≥ 22.04
+  - Debian ≥ 12
+- macOS / Windows (eingeschränkt, nicht offiziell supported)
+
+### 0.2 Erforderliche Software
+| Tool | Mindestversion | Zweck |
+|-----|----------------|-------|
+| Docker Engine | ≥ 24.x | Container Runtime |
+| Docker Compose Plugin | ≥ 2.x | Orchestrierung |
+| GNU Make | ≥ 4.x | Steuerung & Validierung |
+| curl | aktuell | Healthchecks |
+| lsof / ss | systemabhängig | Port‑Prüfung |
+
+### 0.3 Berechtigungen
+- Benutzer ist Mitglied der `docker`‑Gruppe **oder** darf Docker via sudo ausführen
+- Schreibrechte im Projektverzeichnis
+
+---
+
+## 1. Projektstruktur (Baseline)
+
+```text
+project/
+├── Dockerfile
+├── docker-compose.yml
+├── Makefile
+├── .env.example
+├── .env            # lokal, nicht versioniert
+└── app/            # Anwendungscode
+```
+
+---
+
+## 2. Dockerfile – Image‑Definition
+
+### Prinzip: Multi‑Stage Build
+
+**Warum?**
+- kleinere Images
+- reduzierte Angriffsfläche
+- saubere Trennung von Build‑ und Runtime‑Abhängigkeiten
+
+### Referenz‑Dockerfile (Beispiel)
+
+```dockerfile
+# Stage 1: Build
+FROM node:18-alpine AS builder
+WORKDIR /build
+
+COPY package*.json ./
+RUN npm install
+
+COPY . .
+RUN npm run build
+
+# Stage 2: Runtime
+FROM node:18-alpine
+WORKDIR /app
+
+COPY --from=builder /build/dist ./dist
+COPY --from=builder /build/package*.json ./
+RUN npm install --omit=dev
+
+RUN addgroup -S app && adduser -S app -G app
+USER app
+
+EXPOSE 8080
+CMD ["node", "dist/server.js"]
+```
+
+### Regeln
+- Build‑Tools gehören **nicht** ins Runtime‑Image
+- Runtime‑Container laufen **nicht als root**
+
+---
+
+## 3. docker‑compose.yml – Orchestrierung
+
+Docker Compose beschreibt **ausschließlich den Zielzustand** der Laufzeitumgebung.
+
+> Compose ist deklarativ. Keine Logik. Keine Prüfungen.
+
+### Referenz
+
+```yaml
+services:
+  app:
+    build: .
+    ports:
+      - "${PORT}:8080"
+    environment:
+      - APP_URL=http://localhost:${PORT}
+    healthcheck:
+      test: ["CMD", "curl", "-f", "http://localhost:8080/health"]
+      interval: 30s
+      timeout: 10s
+      retries: 3
+```
+
+### Regeln
+- Ports niemals hardcoden
+- Konfiguration ausschließlich über ENV
+- Healthcheck ist Pflicht
+
+---
+
+## 4. Makefile – Steuerung & Kontrolle
+
+Das Makefile ist die **zentrale Kontrollinstanz**.
+
+### Referenz
+
+```make
+-include .env
+export
+
+PORT ?= 8080
+
+.PHONY: build check up up-safe down logs health
+
+build:
+	docker compose build
+
+check:
+	@docker compose version > /dev/null
+	@test -f .env || (echo ".env missing" && exit 1)
+
+up:
+	docker compose up -d
+
+up-safe: check
+	$(MAKE) up
+
+down:
+	docker compose down
+
+logs:
+	docker compose logs -f
+
+health:
+	@docker inspect --format='{{json .State.Health.Status}}' \
+	$$(docker compose ps -q app)
+```
+
+### Zentrale Regeln
+- `make up-safe` ist der **einzige erlaubte Startpunkt**
+- Direkte Nutzung von `docker compose` ist untersagt
+
+---
+
+## 5. CI‑Gate‑Policy
+
+Die CI nutzt **dieselben Prüfregeln** wie der lokale Preflight‑Check.
+
+### Prüfungen
+- Dockerfile baubar
+- Compose valide
+- `.env.example` vollständig
+- keine Secrets im Repository
+- Build erfolgreich
+
+### Regel
+> Merge oder Deployment nur bei grüner Pipeline.
+
+---
+
+## 6. Anti‑Patterns (verboten)
+
+- direkter Aufruf von `docker compose up`
+- hardcodierte Ports
+- Logik im Compose‑File
+- Secrets im Repository
+- Root‑User im Runtime‑Container
+- fehlende Healthchecks
+
+**Merksatz:**
+> Wenn etwas schneller geht, weil es Prüfungen umgeht – ist es falsch.
+
+---
+
+## Fazit
+
+Dieses SOP definiert einen kontrollierten, sicheren und reproduzierbaren Weg für Container‑Deployments.
+
+Kein Komfort auf Kosten von Stabilität.  
+Kein Start ohne Prüfung.  
+Keine Magie – nur Disziplin.
+