BauIN/docs/server-anforderungen.md

KI-BauIN – Server-Anforderungen (Staging und Produktion)

Stand: 5. Oktober 2026. Für den ITM-Entwickler, der die Server aufbaut. Hintergründe stehen in docs/tech-stack.md, Termine in docs/projektplan.md.

Überblick

• Zwei Umgebungen, gleich aufgebaut: Staging (Pilot mit BauIn, ab KW 44) und Produktion (ab KW 51). Getrennte Server, getrennte Datenbanken, getrennte API-Schlüssel.
• Ein Server je Umgebung reicht: Anwendung, MySQL, Meilisearch und Worker laufen auf derselben VM.
• Betrieb nativ, ohne Docker: Nginx, PHP-FPM, Worker unter systemd, Cron für den Scheduler.
• Die Versionen entsprechen der Entwicklung. Abweichungen bitte vorher abstimmen.

Ausstattung je Server (Vorschlag)

	Vorschlag	Anmerkung
Betriebssystem	Ubuntu Server 24.04 LTS	Debian 12/13 geht auch
CPU	4 vCPU
RAM	16 GB	Meilisearch hält Vektoren mit 4.096 Dimensionen; endgültig nach dem Meilisearch-Test (KW 41)
Platte	150 GB SSD, erweiterbar	Daten (MySQL, Uploads, Meilisearch) am besten auf eigenem Volume
Verschlüsselung	Festplattenverschlüsselung gewünscht	Entscheidung mit BauIn offen
Zeitzone	Europe/Berlin, NTP aktiv

Software

Paket	Version	Hinweise
PHP (FPM und CLI)	8.5	Erweiterungen: bcmath, ctype, curl, dom, fileinfo, gd, iconv, intl, mbstring, opcache, openssl, pcntl, pdo_mysql, simplexml, sodium, tokenizer, xml, xmlreader, xmlwriter, zip, zlib
Composer	2.x
Node.js mit npm	22 LTS	nur zum Bauen der Oberfläche beim Deployment
MySQL	8.4 LTS	utf8mb4 / utf8mb4_unicode_ci, nur auf 127.0.0.1, max_allowed_packet mindestens 64M
Meilisearch	v1.54.2 (fest)	eigener systemd-Dienst, nur auf 127.0.0.1:7700, Master-Key gesetzt, --no-analytics
Nginx	aktuelle Version der Distribution	client_max_body_size 200M (ZIP mit LVs), HTTP → HTTPS
poppler-utils, qpdf	Distribution	Text und Seitenzahlen aus PDFs lesen, große PDFs teilen (Grenze der KI-API: 50 MB)
git, unzip	Distribution	Deployment aus Gitea

Dienste

• php8.5-fpm: Pool läuft unter einem eigenen Benutzer (Vorschlag kibauin).
• nginx
• mysql
• meilisearch: eigener Benutzer, Daten auf dem Datenvolume.
• Worker: zwei Instanzen php artisan queue:work database --sleep=3 --tries=3 --max-time=3600 unter systemd, Benutzer kibauin, mit automatischem Neustart.
• Scheduler: Cron-Zeile * * * * * cd /srv/ki-bauin/current && php artisan schedule:run.

Die Vorlagen für den Nginx-Server-Block, die systemd-Units, die Cron-Zeile, das Deploy-Skript und das Backup-Skript liefern wir bis KW 44 im Repository (deploy/).

Netzwerk

• Eingehend: nur 443 sowie 80 für die Weiterleitung und die Zertifikatsausstellung. SSH nur mit Schlüssel und möglichst nur über VPN oder freigegebene IP-Adressen.

• Zugriff für BauIn: offen, ob aus dem Internet mit Login und 2FA oder nur über VPN bzw. freigegebene IP-Adressen (Fragenkatalog B2).

• Ausgehend:

  • https://api-werk.de (KI-API)
  • der Gitea von ITM (Deployment)
  • SMTP für Benachrichtigungen
  • Paketquellen für Updates

  Die Anwendung selbst lädt nichts von fremden Servern.

• MySQL und Meilisearch sind nur lokal erreichbar.

Verzeichnisse

/srv/ki-bauin/
├── releases/<zeitstempel>/   je Deployment ein Verzeichnis
├── current -> releases/…     aktive Version (Symlink)
└── shared/
    ├── .env                  Rechte 0600, Besitzer kibauin
    └── storage/              u. a. storage/app/private = Uploads (nie über Nginx ausliefern)

Konfiguration und Geheimnisse

• In shared/.env stehen APP_KEY, das Datenbank-Passwort, der Meilisearch-Master-Key und die Mail-Zugangsdaten.
• Die Schlüssel der KI-API stehen nicht in der .env. Sie werden in der Anwendung unter Verwaltung → Einstellungen eingetragen und verschlüsselt in der Datenbank gespeichert. Danach sind sie nur noch beschreibbar, nicht mehr lesbar.
• Der APP_KEY muss zusätzlich sicher außerhalb des Servers aufbewahrt werden, z. B. im Passwortmanager. Ohne ihn lassen sich verschlüsselte Felder aus einem Backup nicht wiederherstellen.

Backups (Vorschlag, Entscheidung mit BauIn offen)

• Was: täglich mysqldump --single-transaction, dazu shared/storage/app/private und shared/.env.
• Wie: vor dem Verlassen des Servers verschlüsseln (z. B. restic), Ziel außerhalb des Servers.
• Aufbewahrung: z. B. 7 tägliche, 4 wöchentliche, 6 monatliche Stände.
• Meilisearch wird nicht gesichert, der Index wird aus MySQL neu aufgebaut.
• Restore-Test: einmal vollständig vor dem Produktivstart (KW 3/2027).

Überwachung

• Lebenszeichen: https://<domain>/up antwortet mit HTTP 200.
• Worker und Scheduler melden Lebenszeichen, fehlgeschlagene Jobs werden gezählt. Die Artisan-Befehle dafür liefern wir.
• Alarm per Mail, wenn die Anwendung, ein Worker oder der Scheduler ausfällt, wenn die Platte zu über 80 % voll ist oder wenn die KI-API nicht erreichbar ist.

Deployment

Ablauf, als Skript geliefert:

1. Code aus dem Gitea holen.
2. composer install --no-dev --optimize-autoloader
3. npm ci && npm run build
4. php artisan migrate --force
5. Konfiguration, Routen und Views cachen.
6. php artisan queue:restart
7. PHP-FPM neu laden.

Wer im Betrieb deployt und Updates einspielt, ist noch offen (Fragenkatalog C12).

Termine

Bis	Was
KW 43	Staging-Server mit SSH-Zugang und Grundinstallation
KW 44	Staging fertig: Domain, Zertifikat, Dienste, erstes Deployment
KW 51	Produktionsserver fertig
KW 3/2027	Backups und Alarmierung in Produktion, Restore-Test

Offen

• Standort und Rechenzentrum der Server, Festplattenverschlüsselung
• Domain(s) und Zertifikat (Let's Encrypt oder eigenes)
• Ziel und Zuständigkeit der Backups
• Zugriff für BauIn: Internet oder VPN
• SMTP-Server und Absenderadresse