julian.kiedaischandClaude Opus 5.5
fb1a467221
/svc/examples lists FILIUS' examples, which lie beside F in the image (GPL like this repository, kept out of the dashboard); /svc/projects makes a project from one; /svc/projects/<id>/import takes a .fls (up to 64 MiB), /copy copies a project as it is now, /export gives it back as a .fls with its warnings. Large files go into the blob store on import and come back from it on export, which is refused when one is missing. Found on the way: Node's request body is a Buffer, and Yjs takes no Buffer into a document, so every .fls with binary files would have failed; and fflate, now in the bundle, imports createRequire itself, which the build's banner declared again, so F did not start. The banner names it otherwise and a test builds and starts the bundle. The proxy's /svc/ takes 70 MB. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
98 lines
5.6 KiB
Markdown
98 lines
5.6 KiB
Markdown
# mdg-filius
|
|
|
|
Netzwerksimulation nach [FILIUS](https://www.lernsoftware-filius.de) 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`](https://github.com/filius-project/filius-ipad)
|
|
(Swift, GPLv2 oder GPLv3) — Vorlage für Kern, `.fls`-Codec und Tests,
|
|
* [`filius1/filius`](https://gitlab.com/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/FILIUS_WEB_PLAN.md` im Dashboard.
|
|
|
|
## Entwickeln
|
|
|
|
```bash
|
|
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:
|
|
|
|
```bash
|
|
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).
|