Kommunikationsdokumentation ergänzen

Dokumentiert Matrix-Kommunikation, Telekom-Telefonie und den VPS-Asterisk-Entwicklungsbetrieb.

docs-site/content/index.md

@@ -5,3 +5,4 @@ Diese Dokumentation unterstützt dich bei der täglichen Nutzung von FEDEO.
 ## Einstieg
 
 - [Bedienung](./bedienung/README.md)
+- [Kommunikationslösung auf Basis des Matrix-Standards](./kommunikationslösung-matrix.md)

docs-site/content/kommunikationslösung-matrix.md

@@ -0,0 +1,371 @@
+# Kommunikationslösung auf Basis des Matrix-Standards
+
+Dieser Entwurf beschreibt eine FEDEO-Kommunikationslösung für Chat, Anrufe und Videokonferenzen auf Basis des Matrix-Standards. Ziel ist eine souverän betreibbare Lösung, die Mandantenfähigkeit, Datenschutz, Rechteverwaltung und die bestehenden FEDEO-Workflows berücksichtigt.
+
+## Zielbild
+
+FEDEO erhält einen integrierten Kommunikationsbereich, der interne Zusammenarbeit und externe Kommunikation abdeckt:
+
+- Chat in Einzel-, Gruppen-, Projekt-, Vorgangs- und Kundenräumen
+- Audioanrufe aus Direktchats, Gruppenräumen und Kontakten
+- Videokonferenzen mit Bildschirmfreigabe und Einladungslinks
+- Ende-zu-Ende-verschlüsselte private Kommunikation
+- revisionsfähige Verknüpfung von relevanten Kommunikationsereignissen mit FEDEO-Objekten
+- optional föderierte Kommunikation mit externen Matrix-Organisationen
+
+Matrix wird dabei nicht als isolierter Messenger betrieben, sondern als Kommunikationsschicht neben dem bestehenden FEDEO-Backend.
+
+## Empfohlene Architektur
+
+```text
+Nutzerinnen und Nutzer
+  |
+  | FEDEO Web, Mobile App, optional Element Desktop/Mobile
+  v
+FEDEO Frontend
+  |
+  | FEDEO API, SSO, Rechte, Objektkontext
+  v
+FEDEO Backend
+  |
+  | Provisionierung, Webhooks, Audit-Metadaten
+  v
+Matrix Homeserver
+  |
+  +-- PostgreSQL für Matrix-Daten
+  +-- Redis für Worker und Caches
+  +-- Medien-Repository für Anhänge
+  +-- TURN/STUN für direkte Medienverbindungen
+  +-- MatrixRTC / LiveKit SFU für Gruppenanrufe und Videokonferenzen
+```
+
+### Kernkomponenten
+
+| Komponente | Empfehlung | Aufgabe |
+| --- | --- | --- |
+| Matrix Homeserver | Synapse | Standardnaher, bewährter Homeserver mit guter Betriebsdokumentation |
+| Matrix Client im FEDEO Web | Matrix JS SDK oder eingebetteter Element-Web-Ausschnitt | Chat, Raumliste, Nachrichten, Reaktionen, Anhänge |
+| Mobile Integration | Matrix SDK über FEDEO Mobile oder Deep Link zu Element X | Pushfähige mobile Kommunikation |
+| Identität | OIDC/SSO über FEDEO Auth, perspektivisch Matrix Authentication Service | Einheitlicher Login und zentrale Nutzerverwaltung |
+| Audio/Video | MatrixRTC mit Element Call und LiveKit SFU | Moderne Anrufe und Videokonferenzen |
+| NAT Traversal | coturn | STUN/TURN für stabile Medienverbindungen |
+| Reverse Proxy | bestehender Traefik-Ansatz | TLS, Routing, `.well-known/matrix/*` |
+| Administration | FEDEO Admin-Oberfläche plus Synapse Admin API | Nutzer, Räume, Richtlinien, Sperren |
+
+## Betriebsmodell
+
+Für FEDEO ist ein eigener Matrix-Homeserver pro Installation oder pro großer Betreiberinstanz sinnvoll. Der Matrix-Server sollte nicht öffentlich als offener Registrierungsserver betrieben werden. Nutzer werden ausschließlich durch FEDEO angelegt, aktualisiert und deaktiviert.
+
+Empfohlene Domains:
+
+- `app.example.com`: FEDEO Oberfläche
+- `matrix.example.com`: Matrix Client-Server und Federation API
+- `call.example.com`: Element Call / MatrixRTC
+- `livekit.example.com`: LiveKit SFU
+- `turn.example.com`: TURN/STUN
+
+Die öffentliche Matrix-Serverkennung kann trotzdem `example.com` lauten. Dafür werden `.well-known/matrix/client` und `.well-known/matrix/server` über Traefik ausgeliefert.
+
+## Mandantenmodell
+
+Matrix selbst ist raumbasiert, FEDEO ist mandantenbasiert. Deshalb sollte FEDEO die Mandantenlogik explizit auf Matrix-Räume und Spaces abbilden.
+
+### Räume und Spaces
+
+- Pro FEDEO-Mandant wird ein Matrix Space angelegt.
+- Projekte, Vorgänge, Helpdesk-Konversationen, interne Teams und Kundenkontakte werden als Räume im Mandanten-Space geführt.
+- Direkträume werden nutzerbezogen angelegt, aber über FEDEO mandantengebunden sichtbar gemacht.
+- Externe Räume erhalten einen klaren Status, zum Beispiel `intern`, `extern`, `kunde`, `lieferant`.
+
+### Raumalias-Konvention
+
+Beispiele:
+
+- `#tenant-<mandant>-team:example.com`
+- `#tenant-<mandant>-project-<projekt>:example.com`
+- `#tenant-<mandant>-ticket-<ticket>:example.com`
+- `#tenant-<mandant>-customer-<kunde>:example.com`
+
+Interne technische IDs sollten nicht als sichtbarer Anzeigename genutzt werden. Nutzerinnen und Nutzer sehen sprechende Namen wie `Projekt: Website Relaunch` oder `Kunde: Muster GmbH`.
+
+## Rechte und Rollen
+
+FEDEO bleibt führend für Berechtigungen. Matrix übernimmt die technische Durchsetzung im Raum.
+
+| FEDEO-Rolle | Matrix-Abbildung |
+| --- | --- |
+| Mandantenadmin | Space-Admin und Raumadmin |
+| Teamleitung | Moderatorin oder Moderator in Team- und Projekträumen |
+| Mitarbeitende | Mitglied mit Schreibrechten |
+| Externe Kontakte | Eingeschränkte Mitgliedschaft in ausgewählten Räumen |
+| Automationen | Application-Service- oder Bot-Nutzer mit minimalen Rechten |
+
+Änderungen an Rollen, Teams oder Mandantenzugehörigkeiten lösen im FEDEO-Backend eine Synchronisation mit Matrix aus. Beim Entzug eines Zugriffs wird die Person aus den betroffenen Räumen entfernt. Bei Ende-zu-Ende-verschlüsselten Räumen muss zusätzlich berücksichtigt werden, dass bereits erhaltene Nachrichten auf Geräten verbleiben können.
+
+## Chat
+
+Der Chat wird als erste Ausbaustufe umgesetzt.
+
+### Funktionen
+
+- Direktnachrichten
+- Gruppenräume
+- Mandanten-, Team-, Projekt- und Vorgangsräume
+- Datei- und Bildanhänge
+- Erwähnungen, Reaktionen und Lesestatus
+- Suche in nicht verschlüsselten Räumen über den Homeserver
+- lokale Suche in verschlüsselten Räumen über Client-Indizes
+- Verknüpfung von Nachrichten mit FEDEO-Objekten
+
+### Integration in FEDEO
+
+FEDEO sollte keine vollständige Kopie aller Nachrichten in der eigenen Datenbank speichern. Stattdessen speichert FEDEO nur Referenzen:
+
+- Matrix Raum-ID
+- Matrix Event-ID
+- FEDEO Objekt-Typ und Objekt-ID
+- Zeitstempel
+- beteiligter FEDEO-Nutzer
+- optionale Vorschau, falls Datenschutzrichtlinie dies erlaubt
+
+So bleibt Matrix das Kommunikationssystem, während FEDEO nachvollziehen kann, welche Kommunikation zu welchem Objekt gehört.
+
+## Audioanrufe
+
+Einzelanrufe können direkt über Matrix-VoIP in Direktchats gestartet werden. Der FEDEO-Client zeigt dafür in Kontakt-, Kunden-, Mitarbeitenden- und Chatansichten einen Anruf-Button.
+
+### Anforderungen
+
+- WebRTC-Unterstützung im Browser
+- STUN/TURN über coturn
+- Geräteauswahl für Mikrofon und Lautsprecher
+- Anrufbenachrichtigung im Web und mobil
+- Statusanzeige `verfügbar`, `beschäftigt`, `im Anruf`, `abwesend`
+
+Für klassische Telefonie kann später ein SIP-Gateway ergänzt werden. Das sollte jedoch getrennt von der ersten Matrix-Einführung betrachtet werden, damit Chat und WebRTC-Kommunikation nicht durch Telefoniekomplexität ausgebremst werden.
+
+## Videokonferenzen
+
+Für Gruppenanrufe und Videokonferenzen wird MatrixRTC mit Element Call und LiveKit empfohlen. Matrix übernimmt dabei Raumzustand, Identität, Berechtigungen und Signalisierung; LiveKit übernimmt als SFU die effiziente Medienverteilung.
+
+### Funktionen
+
+- Videokonferenzen aus Matrix-Räumen
+- spontane Besprechungen aus Projekten, Vorgängen oder Kundenakten
+- Bildschirmfreigabe
+- Einladungslink für externe Gäste
+- Wartebereich für externe Gäste
+- Moderationsrechte für Stummschalten, Entfernen und Raumverwaltung
+- optionale Aufzeichnung erst in einer späteren, gesondert freizugebenden Ausbaustufe
+
+### Konfiguration
+
+Clients finden den MatrixRTC-Dienst über `.well-known/matrix/client`. Dort wird der LiveKit-JWT-Dienst als `org.matrix.msc4143.rtc_foci` angekündigt. Diese Datei muss öffentlich lesbar sein, als JSON ausgeliefert werden und CORS für Webclients erlauben.
+
+Beispiel:
+
+```json
+{
+  "m.homeserver": {
+    "base_url": "https://matrix.example.com"
+  },
+  "org.matrix.msc4143.rtc_foci": [
+    {
+      "type": "livekit",
+      "livekit_service_url": "https://call.example.com/livekit/jwt"
+    }
+  ]
+}
+```
+
+## Authentifizierung und Nutzerverwaltung
+
+FEDEO sollte Identität und Lebenszyklus der Nutzer zentral steuern.
+
+### Empfohlener Ablauf
+
+1. Nutzer wird in FEDEO angelegt.
+2. FEDEO erzeugt oder aktualisiert den Matrix-Nutzer.
+3. FEDEO weist den Nutzer den passenden Spaces und Räumen zu.
+4. Login erfolgt über FEDEO SSO/OIDC.
+5. Deaktivierung in FEDEO deaktiviert auch den Matrix-Zugang und entfernt Raumzugriffe.
+
+Die Matrix User-ID sollte stabil und nicht personenbezogen änderungsanfällig sein:
+
+```text
+@u_<fedeo_user_id>:example.com
+```
+
+Der Anzeigename kann weiterhin den echten Namen enthalten und bei Änderungen synchronisiert werden.
+
+## Datenschutz und Compliance
+
+Matrix erlaubt starke Datenschutzkonzepte, erfordert aber klare Betriebsregeln.
+
+### Empfehlungen
+
+- Ende-zu-Ende-Verschlüsselung für Direktnachrichten und vertrauliche Projekträume aktivieren.
+- Nicht verschlüsselte Räume nur dort nutzen, wo serverseitige Suche, Archivierung oder Compliance-Funktionen ausdrücklich benötigt werden.
+- Medienaufbewahrung mandantenweit konfigurierbar machen.
+- Externe Gäste optisch klar kennzeichnen.
+- Federation standardmäßig deaktivieren oder auf erlaubte Domains beschränken.
+- Aufzeichnungen von Videokonferenzen nur mit expliziter Einwilligung und sichtbarem Status erlauben.
+- Administrative Zugriffe protokollieren.
+- Klare Löschfristen für Räume, Anhänge und Audit-Referenzen definieren.
+
+## Federation
+
+Matrix kann mit anderen Homeservern föderieren. Für FEDEO sollte Federation als kontrollierbare Option umgesetzt werden.
+
+### Betriebsmodi
+
+| Modus | Beschreibung | Empfehlung |
+| --- | --- | --- |
+| geschlossen | Keine Federation, nur interne Nutzer und explizite Gäste | Standard für kleine Installationen |
+| allowlist | Federation nur mit freigegebenen Domains | Empfehlung für B2B-Kommunikation |
+| offen | Federation mit beliebigen Matrix-Servern | Nur für bewusst öffentliche Communities |
+
+Für steuer-, kunden- und projektnahe Kommunikation ist `allowlist` der beste Zielmodus.
+
+## Brücken zu anderen Systemen
+
+Matrix unterstützt Brücken zu anderen Kommunikationsdiensten. Für FEDEO sind Brücken nützlich, sollten aber nicht zur ersten Produktstufe gehören.
+
+Mögliche spätere Erweiterungen:
+
+- E-Mail-Brücke für Helpdesk- oder Kundenkommunikation
+- Slack- oder Teams-Brücke für externe Projektpartner
+- WhatsApp- oder SMS-Brücke nur nach gesonderter Datenschutzprüfung
+- SIP-Brücke für Telefonie
+
+Brücken müssen pro Mandant aktivierbar sein und brauchen klare Hinweise, welche Daten an externe Dienste fließen.
+
+## FEDEO-Produktoberfläche
+
+Die Kommunikation sollte in FEDEO an zwei Stellen sichtbar sein.
+
+### Globaler Kommunikationsbereich
+
+- Raumliste
+- Direktnachrichten
+- Suche
+- Anrufe
+- laufende Besprechungen
+- Benachrichtigungen
+
+### Objektbezogene Kommunikation
+
+In Projekten, Kunden, Vorgängen, Helpdesk-Tickets und Dokumenten erscheint ein Kommunikations-Tab:
+
+- zugeordneter Raum
+- relevante Nachrichtenreferenzen
+- Start von Chat, Anruf oder Besprechung
+- Teilnehmerverwaltung entsprechend FEDEO-Rechten
+
+So bleibt Kommunikation dort, wo die Arbeit stattfindet.
+
+## Backend-Integration
+
+Das FEDEO-Backend erhält ein Kommunikationsmodul mit folgenden Aufgaben:
+
+- Matrix-Nutzer provisionieren
+- Spaces und Räume anlegen
+- Raum-Mitgliedschaften synchronisieren
+- Matrix-Event-Webhooks empfangen
+- FEDEO-Objekte mit Matrix-Räumen verknüpfen
+- Benachrichtigungseinstellungen verwalten
+- Admin-Aktionen auditieren
+
+Technisch kann dies über Matrix Admin API, Client-Server API und Application Services erfolgen. Für Automationen empfiehlt sich ein eigener Application Service, weil er reservierte Nutzer- und Raum-Namensräume sauber verwalten kann.
+
+## Deployment-Erweiterung
+
+Der bestehende Docker-/Traefik-Ansatz kann um folgende Dienste erweitert werden:
+
+- `matrix-synapse`
+- `matrix-db` oder gemeinsame PostgreSQL-Instanz mit getrennter Datenbank
+- `redis`
+- `coturn`
+- `element-web` optional als Fallback-Client
+- `element-call`
+- `livekit`
+- `matrix-rtc-jwt-service`
+
+Für produktive Installationen sollte Matrix eine eigene PostgreSQL-Datenbank erhalten. Medien sollten in S3-kompatiblen Speicher ausgelagert werden, damit große Anhänge und Konferenzartefakte nicht den Applikationsserver füllen.
+
+## Monitoring
+
+Wichtige Kennzahlen:
+
+- aktive Nutzerinnen und Nutzer
+- Anzahl Räume pro Mandant
+- Nachrichtenrate
+- Medien-Speicherverbrauch
+- Zustellverzögerung
+- fehlgeschlagene Anrufe
+- LiveKit Paketverlust, Latenz und Teilnehmerzahl
+- TURN-Nutzung
+- Federation-Fehler
+
+Logs von FEDEO, Synapse, LiveKit, coturn und Traefik sollten über eine gemeinsame Korrelation, zum Beispiel Request-ID oder Nutzer-ID, untersuchbar sein.
+
+## Risiken und Gegenmaßnahmen
+
+| Risiko | Gegenmaßnahme |
+| --- | --- |
+| Komplexität durch zwei Systeme | FEDEO bleibt führend für Nutzer, Rechte und Objektbezug |
+| Datenschutz bei externen Räumen | Externe Kennzeichnung, Federation-Allowlist, Mandantenrichtlinien |
+| E2EE erschwert Suche und Archivierung | Raumtyp bewusst wählen, lokale Suche, Metadatenreferenzen statt Vollkopie |
+| Medienverbindungen scheitern in Firmennetzen | coturn sauber betreiben, UDP und TCP/TLS-Fallback anbieten |
+| Betriebskosten durch Video | LiveKit skalierbar betreiben, Limits pro Mandant definieren |
+| Gästezugriff wird unübersichtlich | Einladungslinks mit Ablaufdatum, Wartebereich, Moderationsrechte |
+
+## Umsetzung in Phasen
+
+### Phase 1: Fundament und Chat
+
+- Synapse mit PostgreSQL, Redis, Traefik und `.well-known` betreiben
+- FEDEO-Nutzer zu Matrix synchronisieren
+- Mandanten-Spaces und erste Teamräume anlegen
+- Chat im FEDEO-Frontend integrieren
+- Benachrichtigungen und Raumreferenzen speichern
+
+### Phase 2: Objektbezogene Kommunikation
+
+- Räume automatisch für Projekte, Vorgänge und Kunden anlegen
+- Kommunikations-Tab in FEDEO-Objekten ergänzen
+- Rechteänderungen aus FEDEO nach Matrix synchronisieren
+- externe Gäste einladen und kennzeichnen
+
+### Phase 3: Audio und Video
+
+- coturn bereitstellen
+- MatrixRTC, Element Call und LiveKit integrieren
+- Anruf- und Videobuttons in Chat, Kontakten und Projekten ergänzen
+- Gäste-Links und Wartebereich umsetzen
+
+### Phase 4: Compliance und Skalierung
+
+- Aufbewahrungsrichtlinien pro Mandant
+- Monitoring und Admin-Dashboards
+- Federation-Allowlist
+- optionale Brücken
+- optionale Aufzeichnung mit Einwilligungsworkflow
+
+## Offene Entscheidungen
+
+- Soll Federation initial deaktiviert oder direkt mit Allowlist ausgeliefert werden?
+- Welche Räume müssen serverseitig durchsuchbar sein und bleiben deshalb unverschlüsselt?
+- Sollen externe Gäste Matrix-Konten erhalten oder nur temporäre Konferenzzugänge?
+- Wird Element als sichtbarer Fallback-Client angeboten oder soll alles primär in FEDEO stattfinden?
+- Welche Mandantenlimits gelten für Speicher, Teilnehmerzahl und Videodauer?
+
+## Quellen und Standards
+
+- Matrix Specification: https://spec.matrix.org/
+- Matrix Application Services: https://matrix.org/docs/older/application-services/
+- Matrix Bridges: https://www.matrix.org/docs/communities/bridging/
+- Synapse Worker-Dokumentation: https://matrix-org.github.io/synapse/develop/workers.html
+- Element Call Self-Hosting: https://github.com/element-hq/element-call/blob/livekit/docs/self-hosting.md
+- Element MatrixRTC Konfiguration: https://docs.element.io/latest/element-server-suite-pro/configuring-components/configuring-matrix-rtc/
+- LiveKit Self-Hosting: https://docs.livekit.io/transport/self-hosting/

docs-site/content/telekom-telefonie.md

@@ -0,0 +1,103 @@
+# Telekom-Telefonie in FEDEO
+
+FEDEO kann den lokalen Asterisk-Stack als Übergang zur externen Telefonie nutzen. Die Telekom-Anbindung wird mandantenbezogen in FEDEO unter **Firmeneinstellungen -> Integrationen -> Telefonie-Trunk** gepflegt.
+
+## Zugangsdaten
+
+Für Telekom-SIP ist der Registrar normalerweise `tel.t-online.de`. Die SIP-ID ist in der Regel die Rufnummer mit Vorwahl ohne Leerzeichen und Sonderzeichen, zum Beispiel `0301234567`.
+
+Wenn dein Anschluss statt einer separaten SIP-ID die klassischen Zugangsdaten nutzt, kann der Authentifizierungsnutzer aus Anschlusskennung, Zugangsnummer, Mitbenutzernummer und `@t-online.de` gebildet werden:
+
+```env
+TELEPHONY_TELEKOM_AUTH_USER=<anschlusskennung><zugangsnummer>#<mitbenutzernummer>@t-online.de
+```
+
+## FEDEO Einstellungen
+
+Öffne **Firmeneinstellungen -> Integrationen** und fülle den Bereich **Telefonie-Trunk** aus:
+
+- `SIP-ID / Rufnummer`: Rufnummer mit Vorwahl ohne Leerzeichen und Sonderzeichen
+- `Kennwort`: persönliches Kennwort oder SIP-Kennwort
+- `Auth-User`: optional, falls dein Anschluss nicht direkt mit der SIP-ID authentifiziert
+- `Absendernummer`: optional, meist identisch zur SIP-ID
+- `Eingehende Nebenstelle`: lokale FEDEO/Asterisk-Nebenstelle, z. B. `1001`
+- `Ausgehender Prefix`: standardmäßig `0`
+- `Öffentliche Signaling-Adresse`: öffentliche IP oder DNS-Name, unter dem Asterisk von Telekom erreichbar ist
+- `Öffentliche Medien-Adresse`: öffentliche RTP-Adresse, leer nutzt die Signaling-Adresse
+- `Lokale Netze`: interne Netze, für die Asterisk keine öffentliche Adresse einsetzen soll
+
+Das Kennwort wird nicht wieder an das Frontend zurückgegeben. In der Oberfläche siehst du nur, ob ein Kennwort gespeichert ist.
+
+Nach dem Speichern muss die Konfiguration mit **In Asterisk anwenden** in die Asterisk-Include-Dateien geschrieben werden. FEDEO lädt danach PJSIP und den Dialplan über AMI neu und fordert die Telekom-Registration an. Den Laufzeitstatus findest du unter **Kommunikation -> Telefonie Setup** im Bereich **Externe Telefonie**.
+
+Wenn du die öffentliche Signaling- oder Medien-Adresse änderst, muss Asterisk anschließend neu gestartet werden, weil PJSIP-Transporte diese Werte nicht vollständig im laufenden Betrieb neu laden.
+
+## `.env` Fallback
+
+Die `.env`-Werte bleiben nur als lokaler Fallback für den Asterisk-Teststack erhalten, falls keine mandantenbezogene Konfiguration gepflegt ist.
+
+```env
+TELEPHONY_ENABLED=true
+TELEPHONY_EXTERNAL_PROVIDER=telekom
+TELEPHONY_EXTERNAL_ENABLED=true
+
+TELEPHONY_TELEKOM_ENABLED=true
+TELEPHONY_TELEKOM_REGISTRAR=tel.t-online.de
+TELEPHONY_TELEKOM_SIP_USER=<rufnummer_mit_vorwahl_ohne_sonderzeichen>
+TELEPHONY_TELEKOM_AUTH_USER=
+TELEPHONY_TELEKOM_PASSWORD=<persönliches_kennwort_oder_sip_kennwort>
+TELEPHONY_TELEKOM_CALLER_ID=<rufnummer_mit_vorwahl_ohne_sonderzeichen>
+TELEPHONY_TELEKOM_INBOUND_EXTENSION=1001
+TELEPHONY_TELEKOM_OUTBOUND_PREFIX=0
+TELEPHONY_ASTERISK_GENERATED_DIR=/var/lib/fedeo/asterisk/generated
+TELEPHONY_ASTERISK_AMI_HOST=asterisk-dev
+TELEPHONY_ASTERISK_AMI_PORT=5038
+TELEPHONY_ASTERISK_AMI_USER=fedeo
+TELEPHONY_ASTERISK_AMI_PASSWORD=fedeo-ami-dev
+```
+
+Wenn das Backend lokal auf dem Host läuft, muss es AMI über `127.0.0.1:5038` erreichen. Der Entwicklungsstack mappt dafür `TELEPHONY_DEV_AMI_PORT` auf den Asterisk-Container.
+
+Wenn `TELEPHONY_TELEKOM_AUTH_USER` leer bleibt, verwendet Asterisk automatisch `TELEPHONY_TELEKOM_SIP_USER` als Authentifizierungsnutzer.
+
+## Start
+
+```bash
+docker compose --profile telephony-dev up -d asterisk-dev
+```
+
+Beim Start erzeugt der Container die Dateien `pjsip.telekom.conf` und `extensions.telekom.conf` in einem Docker-Volume. Ausgehende Anrufe mit Prefix `0` und internationale Ziele mit `+` werden über den Telekom-Trunk geroutet. Eingehende Anrufe landen standardmäßig auf Nebenstelle `1001`.
+
+## FreePBX als Diagnose-PBX
+
+Für Provider-Tests kann zusätzlich das optionale Profil `freepbx-dev` gestartet werden. FreePBX ist hier nicht als dauerhafte FEDEO-Abhängigkeit gedacht, sondern als Referenzoberfläche, um Trunk-, NAT-, CLIP- und Routing-Parameter gegen einen Provider wie Easybell zu prüfen.
+
+```bash
+docker compose --profile freepbx-dev up -d freepbx-dev-db freepbx-dev
+```
+
+Beim ersten Start muss FreePBX einmal gegen die lokale MariaDB installiert werden:
+
+```bash
+docker compose --profile freepbx-dev exec -T -w /usr/local/src/freepbx freepbx-dev \
+  bash -lc 'php install -n --dbuser=freepbxuser --dbpass="$(cat /run/secrets/freepbx_user_password)" --dbhost=freepbx-dev-db'
+```
+
+Danach ist die Oberfläche lokal unter `http://localhost:18080` erreichbar. Beim ersten Öffnen zeigt FreePBX die Ersteinrichtung für den Web-Admin-Benutzer. Diese Zugangsdaten gelten nur für die FreePBX-Diagnoseoberfläche und sind unabhängig von FEDEO.
+
+Die Standardports sind bewusst konfliktarm gesetzt:
+
+- Web: `18080` / `18443`
+- SIP UDP: `15060`
+- RTP UDP: `18000-18100`
+
+Das verwendete FreePBX-Image ist aktuell nur für `linux/amd64` veröffentlicht. Auf Apple-Silicon-Hosts nutzt Docker Desktop deshalb über `FREEPBX_DEV_PLATFORM=linux/amd64` Emulation; für Diagnosezwecke ist das ausreichend, aber nicht als Produktionssetup gedacht.
+
+Für einen möglichst realistischen Easybell-Test kann der FEDEO-Asterisk kurz gestoppt und FreePBX auf dem üblichen SIP-Port gestartet werden:
+
+```bash
+docker compose --profile telephony-dev stop asterisk-dev
+FREEPBX_DEV_SIP_PORT=5060 docker compose --profile freepbx-dev up -d freepbx-dev
+```
+
+In FreePBX sollte der RTP-Bereich unter **Settings -> Asterisk SIP Settings** ebenfalls auf `18000-18100` gesetzt werden, damit er zur Compose-Portfreigabe passt. Wenn der Trunk dort erfolgreich registriert und ein Testanruf möglich ist, können die funktionierenden PJSIP- und NAT-Werte nach FEDEO übernommen werden.

docs-site/content/vps-asterisk-dev.md

@@ -0,0 +1,17 @@
+# FEDEO Dev mit VPS-Asterisk
+
+Der Easybell-Trunk liegt auf dem Testserver `188.245.76.1`. Lokal braucht FEDEO nur den WebSocket-Endpunkt und einen AMI-Tunnel.
+
+## AMI-Tunnel starten
+
+```sh
+ssh -i /private/tmp/fedeo_testserver_key -N -L 5038:127.0.0.1:5038 root@188.245.76.1
+```
+
+## Backend mit VPS-Asterisk starten
+
+```sh
+./scripts/start-backend-vps-asterisk.sh
+```
+
+Die Variablen liegen in `telephony/vps-asterisk.env`. Dort werden keine Provider-Zugangsdaten gespeichert; der Trunk bleibt auf dem VPS.