227 lines
4.5 KiB
Markdown
227 lines
4.5 KiB
Markdown
# 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.
|
||
|