Um einen benutzerdefinierten Element Web-Client auf Nginx zu hosten, laden Sie eine offizielle, vorkompilierte Element Web-Version herunter, platzieren Sie deren statische Dateien auf Ihrem Webserver, konfigurieren Sie ihn config.jsonmit Ihrem Matrix-Homeserver und stellen Sie die Website über HTTPS bereit. Nginx führt Element selbst nicht aus: Es stellt die Browser-Anwendungsdateien bereit, während die Anwendung separat eine Verbindung zu Ihrem Matrix-Homeserver herstellt. Verwenden Sie für Client und Homeserver unterschiedliche Hostnamen, z. B. `<client.html>` und `<homeserver.html> chat.example.com` matrix.example.com.
Diese Anleitung setzt Debian oder Ubuntu, einen Nginx-Server mit einem öffentlichen DNS-Namen und einen bestehenden Matrix-Homeserver voraus, der über HTTPS erreichbar ist. Sie verwendet das offizielle Release-Archiv anstelle einer Entwicklungsversion. Die aktuelle Projektdokumentation von Element beschreibt die bereitgestellte Webanwendung als statischen Inhalt und erfordert wichtige Konfigurationen und Einstiegspunkt-URLs, um Caching zu vermeiden. Beachten Sie die Versionshinweise und die aktuelle Konfigurationsdokumentation, wenn Sie eine Version auswählen oder Optionen ändern.
1. Hostnamen und Server vorbereiten
Erstellen Sie einen A-Record, der chat.example.comauf die öffentliche IPv4-Adresse des Nginx-Servers verweist. Fügen Sie einen AAAA-Record nur hinzu, wenn der Server über IPv6 erreichbar ist. Erlauben Sie eingehenden TCP-Verkehr über die Ports 80 und 443 in der Host-Firewall und der Cloud-Firewall. Stellen Sie sicher, dass diese Ports nicht bereits von einem anderen Webserver belegt sind.
Installieren Sie Nginx und erstellen Sie ein Verzeichnis für die Webanwendung:
sudo apt update
sudo apt install nginx
sudo mkdir -p /var/www/element
Öffnen Sie auf einem anderen Rechner die offizielle Element Web-Releases-Seite und wählen Sie eine veröffentlichte stabile Version aus. Laden Sie das zugehörige vorkompilierte Webarchiv herunter und übertragen Sie es anschließend auf den Server. Vermeiden Sie die Verwendung von developBranches oder Nightly Builds für öffentliche Dienste, es sei denn, Sie beabsichtigen, eine Vorabversion der Software bereitzustellen.
2. Installieren Sie die statischen Dateien und konfigurieren Sie den Homeserver.
Entpacken Sie das Release-Archiv zunächst in ein temporäres Verzeichnis. Überprüfen Sie die Struktur des Archivs und kopieren Sie anschließend die Webdateien in das /var/www/elementZielverzeichnis. Achten Sie dabei darauf, die Verzeichnisstruktur des Releases beizubehalten. Da sich die Paketstruktur ändern kann, stellen Sie sicher , dass die Dateien `<file> index.html`, die Bundles, i18ndie Konfigurationsdatei und die Datei `<file>` im selben Verzeichnis wie das Dokumentenverzeichnis von Nginx landen.
sudo mkdir -p /tmp/element-release
tar -xzf /tmp/element-web-REPLACE_WITH_RELEASE.tar.gz -C /tmp/element-release
find /tmp/element-release -maxdepth 2 -name index.html
Verwenden Sie das Verzeichnis, das index.htmldie Release-Inhalte enthält, als Quelle, wenn Sie diese kopieren /var/www/element. Falls das Archiv ein versioniertes Hauptverzeichnis besitzt, kopieren Sie dessen Inhalt, anstatt eine zusätzliche Unterverzeichnisebene zu erstellen. Ersetzen Sie keine laufende Bereitstellung, bevor die neuen Dateien vollständig kopiert sind; eine unvollständige Kopie kann dazu führen, dass JavaScript-Bundles fehlen.
Kopieren Sie die Release-Datei config.sample.json, config.jsonfalls diese im Archiv enthalten ist, und bearbeiten Sie anschließend die neue Datei. Element benötigt zum Starten eine Standard-Homeserver-Verbindungseinstellung. Die empfohlene Form ist default_server_config, wobei die Basis-URL der Client-API verwendet wird. Das folgende Beispiel dient der Veranschaulichung; ersetzen Sie die URL durch die tatsächliche URL Ihres Matrix-Homeservers:
{
"default_server_config": {
"m.homeserver": {
"base_url": "https://matrix.example.com"
}
},
"brand": "Example Chat"
}
Die Konfigurationsdokumentation von Element unterstützt auch default_server_namedie Matrix- .well-knownErkennung. Verwenden Sie diese Option default_server_config, wenn Sie die Homeserver-URL direkt angeben möchten. Speichern Sie keine Passwörter, Zugriffstoken, Signaturschlüssel oder andere Geheimnisse in dieser öffentlichen JSON-Datei. Die brandOption ändert einige App-Bezeichnungen; es handelt sich nicht um ein vollständiges White-Label-Rebranding.
3. Konfigurieren Sie Nginx für die App
Erstellen Sie einen Nginx-Serverblock wie beispielsweise `<head>` /etc/nginx/sites-available/element. Ersetzen Sie die Domain bei Bedarf. Diese einfache Konfiguration stellt Element als statische Dateien bereit und sendet fehlende Pfade an `<head>` index.html, während alle Antworten zur erneuten Validierung markiert werden. Diese konservative Cache-Richtlinie verhindert, dass Benutzer nach einer Veröffentlichung eine veraltete Anwendungsshell oder Konfiguration erhalten. Sie können das Asset-Caching später anpassen, sofern Ihr Bereitstellungsprozess die erforderlichen Pfade von Element beibehält, die nicht zwischengespeichert werden dürfen.
server {
listen 80;
listen [::]:80;
server_name chat.example.com;
root /var/www/element;
index index.html;
location / {
try_files $uri $uri/ =404;
add_header Cache-Control "no-cache" always;
add_header X-Frame-Options SAMEORIGIN always;
add_header X-Content-Type-Options nosniff always;
add_header Content-Security-Policy "frame-ancestors 'self'" always;
}
}
Die Hinweise von Element zum Webhosting raten davon ab, `<script>`, `<script>` oder `<script>` zwischenzuspeichern /config.*.jsonund /i18nempfehlen /versionstattdessen /index.htmleine Browser-Neuvalidierung beim Seitenaufruf. Das Beispiel dient no-cacheals einfacher Ausgangspunkt und ist allgemein anwendbar. Es enthält außerdem die von Element empfohlenen Sicherheitsheader, darunter eine Frame-Richtlinie und Schutz vor MIME-Sniffing. Falls Sie bereits eine Content Security Policy (CSP) definiert haben, integrieren Sie diese frame-ancestors 'self'in die bestehende Richtlinie, anstatt widersprüchliche Richtlinien zu senden.
Aktivieren Sie die Website und überprüfen Sie Nginx, bevor Sie sie neu laden:
sudo ln -s /etc/nginx/sites-available/element /etc/nginx/sites-enabled/element
sudo nginx -t
sudo systemctl reload nginx
4. HTTPS hinzufügen und den Client testen
Element sollte über HTTPS bereitgestellt werden. Sobald die DNS-Auflösung auf diesen Server erfolgt und Port 80 erreichbar ist, installieren Sie Certbot gemäß der aktuellen Anleitung für Ihre Distribution und fordern Sie anschließend ein Zertifikat über die Nginx-Integration an und installieren Sie es. Das Certbot-Projekt dokumentiert den certbot --nginxAblauf und die Erneuerungsprüfungen; die Paketinstallation variiert je nach Betriebssystem, verwenden Sie daher die aktuelle Nginx-Anleitung für Ihre Version. Falls Certbot den Serverblock ändert, führen Sie den Vorgang sudo nginx -terneut aus und überprüfen Sie, ob die Erneuerung geplant ist.
Öffnen Sie die Seite https://chat.example.comin einem privaten Browserfenster. Der Element-Anmeldebildschirm sollte ohne fehlende Skripte oder Stile geladen werden, Ihren erwarteten Homeserver anzeigen und ein gültiges Schlosssymbol in der Adressleiste des Browsers aufweisen. Melden Sie sich mit einem Testkonto an und überprüfen Sie, ob der Browser den Homeserver erreichen kann. Falls die Anmeldung fehlschlägt, überprüfen Sie die Entwicklerkonsole und das Netzwerk-Panel des Browsers auf blockierte Anfragen, Zertifikatfehler oder fehlerhafte Einstellungen base_url.
Häufige Bereitstellungsprobleme
- Eine leere oder nur teilweise geladene Seite: Überprüfen Sie, ob Nginx
rootauf das Verzeichnis verweist, das die Datei enthält index.html, und ob die Bundles und i18ndas Verzeichnis mitkopiert wurden. - Der falsche Homeserver wird angezeigt: Überprüfen Sie die JSON-Syntax
config.jsonund stellen Sie sicher, dass sich die Datei im Web-Root-Verzeichnis befindet. Wenn Sie einen domänenspezifischen Homeserver konfigurieren config.chat.example.com.json, versucht Element, diese Datei vor dem Homeserver zu config.jsonverwenden; die Dateien werden nicht zusammengeführt. - Nach einem Update werden Nutzern die alten Einstellungen angezeigt: Stellen Sie sicher
index.html, dass die Konfigurationsdateien (`<binary data, 4 bytes>`, ` version...i18n - Die Anmeldung funktioniert, aber API-Anfragen schlagen fehl: Überprüfen Sie, ob die Homeserver-URL korrekt ist, HTTPS verwendet und für den Browserzugriff konfiguriert ist, einschließlich des erforderlichen CORS-Verhaltens. Hosting Element auf Nginx fungiert nicht als Proxy oder Ersatz für den Matrix-Homeserver.
Für eine erfolgreiche Bereitstellung wird der Client über HTTPS unter der benutzerdefinierten Domain geladen, seine Konfiguration verweist auf den vorgesehenen Homeserver, und ein Testkonto kann sich ohne Netzwerkfehler anmelden. Die Webhosting-Hinweise von Element und die Nginx-Indexdokumentation sind die wichtigsten Referenzen für die hier beschriebene statische Bereitstellung und das Serverblock-Verhalten.