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/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.
+