Wie man einen benutzerdefinierten Element-Webclient auf Nginx hostet

Wenn Sie Ihren Matrix-Homeserver öffnen können, aber nicht möchten, dass Benutzer auf die öffentliche Element-Website angewiesen sind, können Sie Element Web als statische Website auf Ihrem eigenen Nginx-Server hosten. Die Dateien werden von Nginx bereitgestellt; der Matrix-Homeserver bleibt ein separater Dienst, der Konten, Räume, Nachrichten und die Föderation verwaltet. Diese Unterscheidung ist wichtig: Die Verwendung von Synapse als Webclient installiert oder konfiguriert Synapse nicht.

Diese Einsteigeranleitung verwendet die Hostnamen chat.example.orgfür die Element-Website und matrix.example.orgden Homeserver. Ersetzen Sie beide durch Ihre tatsächlichen Hostnamen. Die Befehle setzen einen Linux-Server im Debian- oder Ubuntu-Stil voraus; Paketpfade und Dienstnamen variieren je nach Distribution.

Was Sie vor Beginn benötigen

Halten Sie folgende Elemente bereit, bevor Sie Serverdateien ändern:

• Eine Domain oder Subdomain für den Webclient, deren DNS auf den Nginx-Host verweist.
• Ein funktionierender Matrix-Homeserver, der über eine HTTPS-URL erreichbar ist, wie z. B. https://matrix.example.org.
• Nginx ist installiert, und ich habe die Berechtigung, die Website-Konfiguration zu bearbeiten und den Dienst neu zu laden.
• Ein gültiges TLS-Zertifikat für den Hostnamen des Webclients ist erforderlich. Benutzer sollten sich über HTTPS anmelden, da ihr Browser Anmeldeinformationen und Sitzungstoken an die Website sendet.
• Ein aktuelles, stabiles Element Web-Release-Archiv des offiziellen Projekts. Vermeiden Sie die Bereitstellung einer Entwicklungsversion auf einem öffentlichen Dienst, es sei denn, Sie beabsichtigen ausdrücklich, Entwicklungssoftware auszuführen.

Element Web ist eine Browseranwendung, die aus statischen Dateien besteht. Die aktuelle Installationsanleitung des Projekts empfiehlt, eine Release-Version herunterzuladen, diese auf dem Server zu entpacken, den Webserver auf die resultierenden Dateien zu verweisen und die Konfiguration vorzunehmen . Unter Debian und Ubuntu dokumentiert das Projekt außerdem ein Element-Web-Paket, das sein Web-Root-Verzeichnis unter `/var/www/webserver` und seine Konfiguration unter `/var/ config.jsonwww/webserver` installiert . Die folgenden Schritte verwenden das Release-Archiv, sodass Sie ein dediziertes Dokumenten-Root-Verzeichnis auswählen können./usr/share/element-web/etc/element-web/config.json

Lesen Sie die Installationsanleitung und die offiziellen Versionshinweise von Element Web, bevor Sie eine Version auswählen. Wenn Sie stattdessen das Debian-Paket verwenden, geben Sie in Nginx das dokumentierte Web-Root-Verzeichnis des Pakets an und bearbeiten Sie die Paketkonfigurationsdatei. Kopieren Sie die unten stehenden Archivpfade nicht unverändert.

1. Laden Sie die Element Web-Dateien herunter und installieren Sie sie.

Das Dokumentenstammverzeichnis ist das Verzeichnis, das Nginx ausliefert, wenn ein Besucher Ihre Website aufruft. Erstellen Sie ein separates Stammverzeichnis und entpacken Sie die Release-Datei dort. Ersetzen Sie die Platzhalter durch die tatsächlichen Archiv- und Verzeichnisnamen, die Sie heruntergeladen haben; Release-Versionen ändern sich im Laufe der Zeit.

sudo install -d -o root -g www-data -m 0755 /var/www/element
tar -xzf element-vX.Y.Z.tar.gz
ls

Das Archiv wird normalerweise in ein versioniertes Verzeichnis entpackt. Kopieren Sie den Inhalt dieses Verzeichnisses, einschließlich index.htmlder JavaScript-Bundles, Schriftarten, Bilder und der Beispielkonfiguration, in das Nginx-Dokumentenverzeichnis. Beispiel: Wenn das extrahierte Verzeichnis den Namen „nginx.example.com“ trägt element-vX.Y.Z, …

sudo cp -a element-vX.Y.Z/. /var/www/element/
sudo find /var/www/element -type d -exec chmod 755 {} \;
sudo find /var/www/element -type f -exec chmod 644 {} \;
ls -l /var/www/element/index.html /var/www/element/config.sample.json

Verwenden Sie im Kopierbefehl den tatsächlichen Verzeichnisnamen mit Versionsnummer. Nginx benötigt Lesezugriff auf diese Dateien, keinen Schreibzugriff. Erstellen Sie vor Aktualisierungen eine Kopie der aktuellen Version und Konfiguration, um diese im Falle eines Bereitstellungsfehlers wiederherstellen zu können.

2. Konfigurieren Sie den Client für die Verwendung Ihres Homeservers.

Element benötigt eine Homeserver-Adresse, bevor es gestartet werden kann. Kopieren Sie die Beispieldatei und legen Sie die Standard-API-URL des Matrix-Clients fest. In diesem Beispiel ist Synapse unter folgender Adresse erreichbar https://matrix.example.org:

cd /var/www/element
sudo cp config.sample.json config.json
sudoedit /var/www/element/config.json

Bearbeiten Sie die Datei /var/www/element/config.jsonund stellen Sie sicher, dass sie ein gültiges JSON-Objekt mit einem default_server_configEintrag enthält, zum Beispiel:

{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "https://matrix.example.org"
    }
  }
}

Dadurch wird der von Element standardmäßig angebotene Server festgelegt. Es wird kein Synapse-Konto erstellt und niemand wird gezwungen, diesen Server auszuwählen. Die aktuelle Element-Konfigurationsanleitung beschreibt dies default_server_configals die bevorzugte Methode zur Angabe der Homeserver-Verbindungsinformationen. Die ältere default_hs_urlOption ist veraltet. Wenn Sie die Benutzer auf einen Server beschränken möchten, bietet Element eine separate disable_custom_urlsEinstellung. Prüfen Sie, ob dies für Ihre Community geeignet ist, bevor Sie sie aktivieren.

Sie können auch eingeschränkte Anpassungen vornehmen, z. B. ein Standarddesign oder bestimmte Branding-Details, indem Sie die dokumentierten Elementoptionen verwenden. Dies ist nicht mit einem vollständigen White-Label-Austausch gleichzusetzen: Das Projekt dokumentiert ausgewählte Anpassungseinstellungen und keine uneingeschränkte Umgestaltung des Brandings. Prüfen Sie im Konfigurationsleitfaden, welche Optionen von der von Ihnen installierten Version unterstützt werden; kopieren Sie keine Einstellungen aus einer anderen Version, ohne diese vorher zu überprüfen.

Die aktuelle Konfigurationsreferenz von Element Web finden Sie hier . Die developDokumentation kann sich im Zuge der Projektentwicklung ändern. Überprüfen Sie daher alle optionalen Schlüssel anhand der Version, die Sie bereitstellen.

3. Fügen Sie eine Nginx-Site für den Webclient hinzu.

Erstellen Sie eine Website-Konfiguration für Ihren Client-Hostnamen. In diesem Beispiel wird davon ausgegangen, dass Sie bereits ein Zertifikat für chat.example.orgdie angegebenen Zertifikatspfade besitzen. Die Zertifikatsausstellung wird nicht behandelt, da die richtige Methode von Ihrem Host, Ihrem DNS-Anbieter und Ihrer bestehenden TLS-Konfiguration abhängt.

server {
    listen 80;
    server_name chat.example.org;
    return 301 https://$host$request_uri;
}

server {
    listen 443 ssl;
    server_name chat.example.org;

    ssl_certificate     /etc/letsencrypt/live/chat.example.org/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/chat.example.org/privkey.pem;

    root /var/www/element;
    index index.html;

    # Revalidate the client files after deployments.
    add_header Cache-Control "no-cache" always;

    # Element Web hosting security headers.
    add_header X-Frame-Options "SAMEORIGIN" always;
    add_header X-Content-Type-Options "nosniff" always;
    add_header X-XSS-Protection "1; mode=block" always;
    add_header Content-Security-Policy "frame-ancestors 'self'" always;

    location / {
        try_files $uri $uri/ =404;
    }
}

Fügen Sie den Block in die entsprechende Site-Datei Ihrer Distribution ein, aktivieren Sie die Site gegebenenfalls und prüfen Sie, ob die globale Nginx-Konfiguration die Standarddatei lädt mime.types. Nginx verwendet MIME-Typen, um Browsern mitzuteilen, ob eine Antwort JavaScript, CSS, JSON oder ein anderer Dateityp ist. Die rootKonfiguration muss auf das Verzeichnis verweisen, das die Datei direkt enthält index.html.

Der oben genannte „no-cache“-Header stellt eine einfache, bereitstellungsfreundliche Basis dar: Browser validieren Dateien nach einem Update neu, anstatt veralteten Clientcode zu verwenden. Die Hosting-Hinweise von Element schreiben ausdrücklich vor, dass `<script>` /config.*.json, `<script>` /i18n, /version`<script>` und `<script>` /index.htmlnicht zwischengespeichert werden dürfen, und empfehlen eine erneute Validierung für das Stammverzeichnis der Website. Wenn Sie später eine längerfristige Zwischenspeicherung für große statische Ressourcen hinzufügen, halten Sie diese Pfade aktuell und überprüfen Sie die Namenskonventionen der Ressourcen in der jeweiligen Version, bevor Sie Cache-Regeln erstellen.

Die README-Datei von Element empfiehlt für selbstgehostete Websites die Verwendung von Anti-Framing- und Content-Type-Headern. Falls Sie bereits eine Content Security Policy (CSP) an anderer Stelle eingerichtet haben, ergänzen Sie frame-ancestors 'self'diese bestehende Richtlinie, anstatt einen zweiten CSP-Header zu senden. Eine restriktive CSP kann erforderliche Anwendungsskripte blockieren. Kopieren Sie daher keine umfassende Richtlinie, ohne sie vorher auf dem bereitgestellten Client zu testen.

Lesen Sie die Hosting- und Caching-Anforderungen von Element Web sowie die offizielle Dokumentation des Nginx-Kernmoduls, um mehr über das Verhalten von root, try_filesund der Verarbeitung statischer Dateien zu erfahren.

4. Überprüfen Sie die Konfiguration und laden Sie Nginx neu.

Testen Sie die Konfiguration, bevor Sie sie anwenden. Falls Nginx einen Fehler meldet, lassen Sie den aktuellen Prozess weiterlaufen, während Sie die gemeldete Datei und Zeile korrigieren; laden Sie keine fehlerhafte Konfiguration neu.

sudo nginx -t
sudo systemctl reload nginx
curl -I https://chat.example.org/
curl -I https://chat.example.org/config.json

Der Test sollte melden, dass die Syntax korrekt ist und der Konfigurationstest erfolgreich war. Die HTTPS-Anfragen sollten den vorgesehenen Host erreichen und eine erfolgreiche Antwort zurückgeben. Prüfen Sie außerdem, ob die Konfigurationsdatei selbst gültiges JSON ist.

curl -fsS https://chat.example.org/config.json | python3 -m json.tool

Öffnen Sie die Seite anschließend https://chat.example.orgin einem Browser. Sie sollten den Element-Anmelde- oder Willkommensbildschirm mit Ihrem Matrix-Homeserver als Standardseite sehen. Erstellen Sie ein Testkonto, prüfen Sie die Entwicklertools Ihres Browsers auf fehlgeschlagene Netzwerkanfragen und vergewissern Sie sich, dass Anmeldung, Laden der Raumliste und Nachrichtenversand funktionieren. Ein erfolgreich geladenes Konto beweist lediglich, dass Nginx den Webclient bedient hat; es beweist nicht, dass der Homeserver erreichbar oder korrekt konfiguriert ist.

5. Sicherstellen, dass die Homeserver-Erkennung bei Bedarf funktioniert.

Wenn Ihre Matrix-IDs einen Servernamen wie beispielsweise verwenden, example.orgwährend die Synapse-API unter erreichbar ist matrix.example.org, können Matrix-Clients die API-URL mithilfe einer bekannten Client-Antwort unter https://example.org/.well-known/matrix/clientermitteln. Dieser optionale Discovery-Endpunkt gehört zur Domain in der Matrix-ID und nicht automatisch zum Hostnamen des Element-Webclients. Eine minimale Antwort sieht folgendermaßen aus:

{
  "m.homeserver": {
    "base_url": "https://matrix.example.org"
  }
}

Stellen Sie die Daten als JSON mit den für browserbasierte Clients erforderlichen CORS-Headern bereit. Die Installationsdokumentation von Synapse enthält ein Nginx-Beispiel und gibt an, dass public_baseurldie URL mit der URL übereinstimmen sollte, über die Clients Synapse erreichen. Wenn Ihre Element-Konfiguration die korrekte Homeserver-URL direkt festlegt und Ihre Benutzer diese clientseitige Einstellung verwenden, ist die automatische Erkennung für diese Basiskonfiguration möglicherweise nicht erforderlich.

Befolgen Sie die bewährten Client-Richtlinien von Synapse und testen Sie die finale URL, curlbevor Sie die Benutzer-ID-Erkennung erwarten. Aus Sicherheitsgründen empfiehlt Synapse, den Homeserver nach Möglichkeit auf einer anderen registrierten Domain als sensible Webanwendungen zu hosten. Separate Subdomains bieten zwar einen gewissen Schutz, eine separate registrierte Domain ist jedoch die sicherere Wahl.

Häufige Probleme, die es zu vermeiden gilt

• Nginx zeigt einen 403-Fehler an: Überprüfen Sie die Leseberechtigungen für Dateien und Verzeichnisse und stellen Sie sicher, dass der Nginx-Worker jedes übergeordnete Verzeichnis durchlaufen kann.
• Die Seite ist leer oder gibt einen 404-Fehler für JavaScript zurück: Stellen Sie sicher, rootdass der Pfad zum extrahierten Release-Verzeichnis und nicht zu einem übergeordneten oder untergeordneten Verzeichnis führt. Überprüfen Sie die Nginx-Fehler- und Zugriffsprotokolle.
• Das Element wird geladen, kann aber keine Verbindung herstellen oder sich anmelden: Überprüfen Sie die base_urlURL config.json, das HTTPS-Zertifikat des Homeservers, den Firewall-Zugriff und jegliche CORS- oder Reverse-Proxy-Konfigurationen auf Synapse-Seite. CORS wird von Browsern erzwungen; eine statische Nginx-Website kann die Ursprungsrichtlinie des Homeservers nicht selbstständig korrigieren.
• Die kürzlich vorgenommenen Änderungen werden nicht angezeigt: Überprüfen Sie die Cache-Header auf /, /index.html, /config.json, /version, und /i18nund aktualisieren Sie den Browser anschließend neu, nachdem Sie sich vergewissert haben, dass die bereitgestellten Dateien ersetzt wurden.
• Die Anmeldeseite funktioniert nur über HTTP: Schließen Sie die TLS-Einrichtung ab und leiten Sie HTTP auf HTTPS um, bevor Sie Benutzer zum Anmelden einladen.

Checkliste für die endgültige Bereitstellung

• Der Element Web-Hostname wird zum Nginx-Server aufgelöst und verfügt über ein gültiges HTTPS-Zertifikat.
• Das Dokumentenstammverzeichnis enthält die Release-Dateien index.html, Assets und eine gültige Datei config.json.
• Die JSON- m.homeserver.base_urlObjekte verweisen auf die erreichbare HTTPS-Client-API für Ihren Matrix-Homeserver.
• sudo nginx -tNginx liefert sowohl die Startseite als config.jsonauch die HTTPS-Seite aus.
• Der Browser kann sich anmelden und eine echte Anfrage an den Homeserver senden, ohne dass Zertifikats-, CORS- oder Dateifehler auftreten.
• Ihre Cache-Regeln sorgen dafür, dass neue Clientdateien und Konfigurationen nach einem Upgrade wirksam werden.

Sobald diese Prüfungen erfolgreich abgeschlossen sind, wird der benutzerdefinierte Element Web-Client von Nginx bereitgestellt und kann mit dem Matrix-Homeserver kommunizieren. Halten Sie Element Web auf dem neuesten Stand, bewahren Sie eine Sicherungskopie der vorherigen Version und Konfiguration auf und überprüfen Sie nach jedem Upgrade die Homeserver-URL und die Browser-Netzwerkanfragen erneut.

Offizielle Referenzen

• Element Web Installationsdokumentation
• Element Web-Konfigurationsleitfaden
• Element Webhosting, Sicherheitsheader und Caching-Leitfaden
• Synapse-Client-Dokumentation zu bekannten URIs
• Synapse-Sicherheitsleitfaden
• Dokumentation des Nginx-Kernmoduls