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