Zum Inhalt

Backend im Docker-Container (Entwicklung)

Stand: 13.10.2026 13:38 Branch: main Status: Anleitung

Änderungshistorie anzeigen

Zweck: Das gebaute Backend als Container betreiben, zum Beispiel auf einem Rechner oder NAS im Heimnetz. Grundlage für den späteren Containerbetrieb gemäss Hosting-Planung.
Abgrenzung: Der Container ersetzt nicht die lokale Entwicklung nach dem lokalen Backend-Setup. Quellcode wird weiterhin lokal bearbeitet, gebaut und getestet. Eine vollständige Entwicklungsumgebung auf dem NAS ist nicht umgesetzt und im Projektstatus als spätere Prüfaufgabe vermerkt.

1. Bestandteile

Datei Inhalt
compose.yaml Dienst backend mit Healthcheck, Ressourcengrenzen und gehärteten Container-Einstellungen
backend/Dockerfile Zweistufiger Build auf node:22-bookworm-slim mit OpenSSL für Prisma; Laufzeit als Benutzer node
backend/.dockerignore Schliesst node_modules, .env, Tests, Skripte, Migrationen und Seed vom Image aus
.env.example Vorlage für Bindeadresse und Port des Containers
backend/src/health.controller.ts Endpunkt GET /v1/health, antwortet mit { "status": "ok" }

2. Sicherheitseigenschaften

  • Der Container läuft als nicht privilegierter Benutzer node.
  • Das Dateisystem des Containers ist schreibgeschützt; nur /tmp ist beschreibbar.
  • Alle Linux-Sonderrechte sind entzogen (cap_drop: ALL, no-new-privileges).
  • Speicher, CPU, Prozessanzahl und Loggrösse sind begrenzt.
  • Der Port ist standardmässig nur an 127.0.0.1 gebunden.
  • Zugangsdaten gelangen nicht ins Image; sie werden beim Start aus backend/.env gelesen.
  • Der Health-Endpunkt gibt keine Daten preis und prüft nur, ob die Anwendung antwortet.

3. Voraussetzungen

  • Docker mit Compose (Docker Desktop oder Docker Engine, zum Beispiel auf dem NAS)
  • Vollständige backend/.env wie bei der lokalen Entwicklung
  • In backend/.env muss NODE_ENV=development stehen

Wichtig: compose.yaml setzt NODE_ENV bewusst nicht selbst. Der Wert kommt aus backend/.env. Fehlt er dort, gilt der Standardwert production aus dem Image. Dann wäre die Versandsperre des MailService (MAIL_DEV_CATCH_ALL) aus, und Einladungen gingen an reale Adressen (ADR-016). Zudem verlangt der Produktivmodus AWS KMS für TOTP-Geheimnisse.

4. Starten und prüfen

Im Hauptordner des Repositorys:

cd "C:\03 Dev\divelogix360"
docker compose build
docker compose up -d
docker compose ps

Nach rund 30 Sekunden zeigt docker compose ps den Dienst als healthy. Zusätzlich im Browser oder per PowerShell:

Invoke-RestMethod http://127.0.0.1:3000/v1/health

Erwartet: status : ok.

Logs ansehen und stoppen:

docker compose logs -f backend
docker compose down

5. Zugriff aus dem Heimnetz

Für einen bewussten Zugriff aus dem Heimnetz, zum Beispiel bei Betrieb auf dem NAS, wird im Hauptordner eine Datei .env aus der Vorlage .env.example erstellt und BACKEND_BIND_ADDRESS=0.0.0.0 gesetzt. Diese Datei ist nicht versioniert.

  • Keine Portweiterleitung im Router und keine direkte Internetfreigabe einrichten.
  • Der Zugriff ohne TLS ist nur im vertrauenswürdigen Heimnetz zulässig.

6. Datenbankmigrationen

Das Image enthält bewusst keine Migrationen. Migrationen werden gemäss ADR-010 kontrolliert mit npx prisma migrate deploy aus dem lokalen Klon angewendet, nicht beim Containerstart.

Änderungshistorie

Datum, Uhrzeit Version Änderung Autor
13.10.2026 13:38 1.0 Anleitung für den Containerbetrieb des Backends erstellt; Docker-Paket mit Node 22, OpenSSL und NODE_ENV aus backend/.env übernommen Claude