Skip to content

Deployment (Server)

Production-Stack: Runtime-Images, Traefik HTTPS, PgBouncer mTLS. Kein docker-compose.dev.yml. Lokal entwickeln: Setup.

Einmalig

  1. Projektordner auf dem Server ablegen.
  2. .env aus .env.example mit starken Passwörtern.
  3. QGIS-Soll: LINETRA_PG_HOST = öffentlicher Hostname (SAN des Server-Zerts), LINETRA_PG_PORT=5432, LINETRA_PG_SSLMODE=verify-full. Optional PGBOUNCER_TLS_HOST gleich setzen.
  4. Traefik: docker-compose.override.yml hängt HTTP(S) (frontend-prod, marketing-prod, backend, editor-updates) ans Netz traefik. Kein TCP-Entrypoint linetra-pg, kein Host-Publish von Postgres.
  5. PKI + Start:
./scripts/pki/init-ca.sh                 # interne CA + PgBouncer-Serverzertifikat
./scripts/pki/issue-client-cert.sh edit  # optional CLI-Cert; Kollegen: Settings → Nutzer → QGIS-Cert-ZIP
./scripts/deploy_server.sh               # compose mtls+production + App-Rollen

deploy_server.sh startet Compose mit Profilen mtls und production (up -d, ohne Dev-Override) und legt die App-Rollen an. Schema von Null: Alembic (Control + Mandanten) — kein Dump-Restore.

./scripts/alembic_upgrade_all.sh

Rollen später nachziehen: ./scripts/create_app_roles.sh.

Auf dem NAS-Traefik (/var/deploy/core auf diesem Host): Entrypoint linetra-pg und Publish 10.13.13.1:3401 entfernen, sonst bleibt :3401 auf wg0 offen. WireGuard-Service nicht abschalten (andere NAS-Dienste).

Web-CMS (Produktion)

Neu bauen und deployen:

./scripts/stack.sh prod up --build
./scripts/alembic_upgrade_all.sh

Nur Images: ./scripts/build.sh prod. Nur starten ohne Rebuild: ./scripts/stack.sh prod up. Erster Start inkl. App-Rollen: ./scripts/deploy_server.sh (danach alembic_upgrade_all.sh). Compose-CLI-Hilfe: ./scripts/stack.sh --help.

  • App-Host: https://linetra-web.nasarek.dev (Traefik → frontend-prod). Legacy linetra.nasarek.dev / linetra-app.nasarek.dev leiten dorthin um.
  • Marketing-Host: https://linetra-org.nasarek.dev (Traefik → marketing-prod, HTTP Basic Auth aus MARKETING_BASIC_AUTH_USERS bis Go-Live).
  • API is same-origin via Next.js rewrite /api → backend:8000.
  • Set SESSION_SECRET, COOKIE_SECURE=true, CORS_ORIGINS=https://linetra-web.nasarek.dev,https://linetra-org.nasarek.dev, NEXT_PUBLIC_APP_URL=https://linetra-web.nasarek.dev, NEXT_PUBLIC_MARKETING_URL=https://linetra-org.nasarek.dev.
  • Basic Auth für Org: htpasswd -nbB preview 'secret' | sed 's/\$/$$/g' → MARKETING_BASIC_AUTH_USERS in .env.

Worker

Service Queues Aufgabe
celery celery, sync Standard- und Sync-Tasks
celery-assistant assistant Assistant-Pipeline (Prozessmanagement)
celery-documents documents Textextraktion für Dokumente (Concurrency 1; Dokumente)
celery-beat — Zeitpläne, u. a. linetra.documents.sweep alle 120 s

celery-documents ist in docker-compose.yml und docker-compose.dev.yml definiert und teilt das Volume linetra_files mit der API. Nach einem Update einmal starten (docker compose up -d celery-documents, ohne --build, wenn das Image schon gebaut ist). Ohne den Worker bleiben hochgeladene Dokumente im Status „empfangen“.

Netzwerk

Weg Live? Auth Port
FastAPI → postgres:5432 ja App-User / Session, nur Compose-Netz unpublished
QGIS → PgBouncer ja mTLS, sslmode=verify-full, CN = {slug}_edit / {slug}_read ${PGBOUNCER_PORT:-5432}
pgAdmin → postgres:5432 ja pgAdmin-Login (PGADMIN_DEFAULT_*), dann POSTGRES_PASSWORD 127.0.0.1:${PGADMIN_PORT:-5051}
Traefik TCP :3401 / wg0 Ist, abgeschaltet — zu (auch auf WireGuard)
  • TLS steckt in PgBouncer. Kein Traefik-TLS auf diesem TCP-Port (libpq SSLRequest ≠ TLS ClientHello → stiller Fehlschlag). Passthrough nur, falls Traefik doch in der Kette bleibt — Standard ist Direct-Publish.
  • Superuser postgres nicht über den Proxy.
  • pgAdmin (Ops) nur über SSH-Tunnel: ssh -L 5051:127.0.0.1:5051 <server> (oder VS Code Ports), dann http://localhost:5051. Server Linetra ist vorregistriert; Passwort = POSTGRES_PASSWORD. Kein Traefik-Host.
  • WireGuard: Hülle für andere Dienste, nicht nötig für QGIS oder die Apps.
  • Lokal: Compose darf localhost:3401 weiter mappen — nicht das Server-Soll.

Abnahme: ./scripts/pki/verify-mtls.sh (mit Zertifikat Login, ohne Zertifikat Abweisung). Von außen ss/curl: 3401 geschlossen auf public und wg0.

Details: Datenbankzugang, ADR-0002, ADR-0003.

Kollegen onboarden

Nur Linetra Editor (GIS über die API): Konto im Dashboard (Settings → Nutzer, Rolle editor oder admin). Kein Client-Zertifikat. Anleitung: Linetra Editor nutzen.

QGIS direkt an die Live-DB:

  1. Zertifikatspaket: Konto → Profil → QGIS-Cert-ZIP (Self-Service) oder Admin unter Organisation/Nutzer (nach ./scripts/pki/init-ca.sh) — pro Web-User (ADR-0055). CLI ./scripts/pki/issue-client-cert.sh nur für Ops/Workstation.
  2. QGIS-Werte: Host = LINETRA_PG_HOST, Port 5432, DB linetra_<slug>, User = persönlicher CN aus ZIP / /auth/me (z. B. {slug}_u_0fc67079), SSL verify-full, Zertifikat + Schlüssel + CA. Shared {slug}_edit-Certs greifen am Proxy nicht mehr.
  3. Nach ./scripts/create_app_roles.sh: pgbouncer.get_auth braucht aktive client_cert_grants (ZIP-Download schreibt sie). ADR-0013-Workstation: Grant für das Ops-Cert manuell anlegen.
  4. WireGuard nur, wenn andere NAS-Dienste das verlangen — nicht für diese Verbindung.

Siehe Benutzerhandbuch: QGIS-Verbindung. Plugin-Implementierung: plugin-per-user-certs.md.

Editor-Desktop aktualisieren

Signierte Bundles und latest.json liegen unter https://linetra-web.nasarek.dev/editor-updates/ (nginx-Service editor-updates, Dateien in editor-updates/files/; Legacy-Host bleibt während der Umstellung erreichbar). Ablauf: Editor-Updates, ADR-0018.