wlkns-dev-standards/sop/container-deployment.md

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)

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)

# 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

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

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