mdg-filius

Netzwerksimulation nach FILIUS für den Browser — als App „Filius" im MDG-Dashboard, gemeinsam bearbeitbar.

Based on Filius by Dr. Stefan Freischlad and the Filius project.

Dieses Projekt ist unabhängig. Es wird weder vom ursprünglichen Filius-Projekt (Universität Siegen) noch von filius-project (Filius on iPad) herausgegeben, betrieben oder unterstützt.

Herkunft

Der Simulationskern ist eine Übertragung nach TypeScript aus

• filius-project/filius-ipad (Swift, GPLv2 oder GPLv3) — Vorlage für Kern, .fls-Codec und Tests,
• filius1/filius (Java, GPLv2 oder GPLv3) — Referenz für Dateiformat und Verhalten.

Jede übertragene Datei nennt in ihrem Kopf die Quelldatei. CHANGES.md führt die Herkunft je Paket. Lizenz dieses Repos: GPL-3.0 (LICENSE).

Aufbau

Pfad	Inhalt
packages/core	Simulationskern: Modell, Ereignis-Warteschlange, Protokolle, Anwendungen — ohne DOM, ohne Node
packages/fls	.fls lesen, schreiben, Unbekanntes bewahren
packages/doc	gemeinsames Dokument (Yjs): Projekt ⇄ Dokument, Schnappschuss des Kerns, Hausmeister, die Änderungen der Werkzeuge und des Geräte-Blatts (mit Javas Eingabeprüfung)
packages/protocol	die eine Nachrichtenliste zwischen Editor und Simulationsraum (/sim)
packages/sim	Simulationsraum (für Server F und den Web Worker) und LocalSimHost
packages/editor	Oberfläche im Iframe des Dashboards (React, Vite), auf einem Projekt von F (?project=<uuid>) oder mit einem Raum in der eigenen Seite (Entwicklung): Fläche, Palette, Werkzeuge des Entwurfs, Geräte-Blatt, Aktionsmodus (Desktops, Anwendungen, Datenaustausch), Dokumentationsmodus (Text, Gliederungsfläche, Bild exportieren, Bericht als PDF); npm run dev -w @mdg-filius/editor öffnet die Entwicklungsseite
packages/server	Filius-Dienst auf Server F: gemeinsame Dokumente über Hocuspocus (/sync), gespeichert in Postgres (Stand und Aktualisierungen, verdichtet), Hausmeister; Anmeldung mit der Eintrittskarte des Dashboards (/__auth, Keks, Lese- und Schreibstufe); Dienstweg des Dashboards (/svc/*: Projekte anlegen, löschen, einfrieren, Zugänge widerrufen); Simulationsräume auf /sim in worker_threads, einer je Projekt für alle; /healthz; liefert Seite und Bundle des Editors aus (editor/ neben main.mjs, vorab gepackt); FILIUS-Dateien über /svc/*: Projekte aus den Java-Beispielen (examples/ neben main.mjs) und aus .fls, Kopie, Export; npm run build -w @mdg-filius/server bündelt ihn nach dist/main.mjs und den Faden der Räume nach dist/simWorker.mjs
deploy	Image (Dockerfile), ein Stack je Umgebung (docker-compose.yml, *.env.example), Eintrag für den externen OpenResty (proxy.conf)

Plan und Entscheidungen: knowledge/plans/done/FILIUS_WEB_PLAN.md im Dashboard.

Entwickeln

npm install
npm run hooks      # Sprachprüfung vor jedem Commit (braucht das Dashboard drumherum)
npm run check      # Typprüfung + Tests (die Server-Tests starten eine Wegwerf-Postgres in Docker, oder nehmen FILIUS_TEST_DATABASE_URL)
npm run test:browser  # Tests im echten Browser (Playwright: Chromium; der Touch-Test auch in WebKit als iPad hoch und quer)

Server F braucht zum Start DATABASE_URL, FILIUS_TICKET_SECRET (mit dem Dashboard geteilt, das die Karten signiert), FILIUS_SERVICE_KEY (der Schlüssel des Dashboards für /svc/*) und FILIUS_ORIGINS (die Herkünfte des Editors, durch Kommas getrennt); FILIUS_PORT ist 8080, wenn nicht gesetzt. Fehlt eine davon, startet er nicht. Ohne HTTPS (Entwicklerrechner) setzt FILIUS_INSECURE_COOKIE=1 den Keks ohne Secure.

Betrieb

Zwei Docker-Stacks auf Server F, je mit eigener Datenbank, eigenem FILIUS_TICKET_SECRET und FILIUS_SERVICE_KEY:

Name	Port	gehört zu
test-filius.hub.mdg-hamburg.de	8081	test-dashboard
filius.hub.mdg-hamburg.de	8080	dashboard

Im Klon auf F, je Umgebung einmal:

cp deploy/test.env.example deploy/test.env    # leere Werte füllen
docker compose -f deploy/docker-compose.yml --env-file deploy/test.env up -d --build

(für die Produktion dasselbe mit production). Die Umgebungsdatei bestimmt Stack-Namen, Volume, Image-Tag und Port; die beiden Stacks teilen nichts. Braucht Docker Compose v2. Gesichert werden muss nur das Volume <stack>_db (Befehl in deploy/docker-compose.yml).

deploy/proxy.conf ist der Eintrag für den externen OpenResty (in dessen conf.d); vorher die Adresse von F für filius-lxc.invalid einsetzen. FILIUS_ORIGINS ist jeweils der eigene Name mit https://.

Die Uhr von F muss per NTP laufen (beim LXC: die des Proxmox-Hosts). Eine Eintrittskarte trägt ganze Sekunden; F nimmt sie bis 5 s vor seiner Uhr. Ging F 886 ms nach, scheiterte fast jede Anmeldung. node tools/live/clock.mjs <adresse> <port> misst den Versatz.

Messen und Abnehmen an einem laufenden F: tools/live/ (m3.ts Last, m4.ts Dokumentgröße, m5.ts Dauerverbindung, acceptance.ts zwei Browser in einem Projekt) mit den Geheimnissen der Umgebung in /root/.filius-test.env; jeder Lauf legt frische Projekte an und löscht sie.

Das Image liefert auch den Editor aus: F nimmt den Ordner editor/ neben main.mjs (anderswo FILIUS_EDITOR_DIR). Es läuft auf Node 24, die Entwicklung auf Node 20; vor einem Update einmal mit docker compose … up --build auf test-filius prüfen.

Code, Kommentare und Testnamen sind englisch; sichtbare Texte stehen hinter i18n-Schlüsseln (Deutsch/Englisch).