Om een aangepaste Element Web-client op Nginx te hosten, downloadt u een officiële, vooraf gecompileerde Element Web-release, plaatst u de statische bestanden op uw webserver, configureert u deze config.jsonmet uw Matrix-homeserver en serveert u de site via HTTPS. Nginx voert Element zelf niet uit: het serveert de bestanden van de browserapplicatie, terwijl de applicatie afzonderlijk verbinding maakt met uw Matrix-homeserver. Gebruik een andere hostnaam voor de client en de homeserver, bijvoorbeeld chat.example.comen matrix.example.com.
Deze handleiding gaat ervan uit dat u Debian of Ubuntu gebruikt, een Nginx-server met een openbare DNS-naam hebt en een bestaande Matrix-homeserver hebt die via HTTPS bereikbaar is. Er wordt gebruikgemaakt van het officiële release-archief in plaats van een ontwikkelingsversie. De huidige projectdocumentatie van Element beschrijft de geïmplementeerde webapplicatie als statische content en vereist belangrijke configuratie- en toegangspunt-URL's om caching te voorkomen. Raadpleeg de release-opmerkingen en de huidige configuratiedocumentatie bij het kiezen van een release of het wijzigen van opties.
1. Bereid de hostnaam en server voor
Maak een A-record aan die chat.example.comverwijst naar het openbare IPv4-adres van de Nginx-server. Voeg alleen een AAAA-record toe als de server bereikbaar is via IPv6. Sta inkomende TCP-poorten 80 en 443 toe via de hostfirewall en de cloudfirewall. Controleer of deze poorten niet al bezet zijn door een andere webserver.
Installeer Nginx en maak een map aan voor de webapplicatie:
sudo apt update
sudo apt install nginx
sudo mkdir -p /var/www/element
Open op een andere computer de officiële Element Web-releasespagina en kies een gepubliceerde stabiele release. Download het vooraf gecompileerde webarchief en zet dit archief vervolgens over naar de server. Vermijd het gebruik van de developbranch of een nightly build voor een openbare dienst, tenzij u van plan bent preview-software uit te voeren.
2. Installeer de statische bestanden en stel de homeserver in.
Pak eerst het release-archief uit in een tijdelijke map. Controleer de hoofdstructuur van het archief en kopieer vervolgens de webbestanden naar die map /var/www/element; behoud de mapstructuur van de release. De pakketstructuur kan veranderen, dus zorg ervoor dat index.htmlde bestanden, de bundels i18nen het configuratiebestand terechtkomen op de locatie waar de documentroot van Nginx zal verwijzen.
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
Gebruik de map waarin de releasebestanden zich bevinden index.htmlals bron bij het kopiëren van de inhoud van de release naar de map /var/www/element. Als het archief één versiebeheerde hoofdmap heeft, kopieer dan de inhoud van die map in plaats van een extra genest niveau aan te maken. Vervang een live-implementatie niet voordat de nieuwe bestanden compleet zijn; een onvolledige kopie kan ertoe leiden dat gebruikers JavaScript-bundels missen.
Kopieer het releasebestand config.sample.jsonnaar de juiste locatie config.jsonals het archief dit bevat, en bewerk vervolgens het nieuwe bestand. Element heeft een standaard homeserver-verbindingsinstelling nodig om te starten. De aanbevolen vorm is default_server_config, waarbij de basis-URL van de client-API wordt gebruikt. Het onderstaande voorbeeld is illustratief; vervang de URL door de daadwerkelijke URL die door uw Matrix-homeserver wordt aangeboden:
{
"default_server_config": {
"m.homeserver": {
"base_url": "https://matrix.example.com"
}
},
"brand": "Example Chat"
}
De configuratiedocumentatie van Element ondersteunt ook default_server_name, wat gebruikmaakt van Matrix- .well-knownontdekking. Gebruik dit default_server_configwanneer u de URL van de homeserver direct wilt opgeven. Plaats geen wachtwoorden, toegangstokens, ondertekeningssleutels of andere geheimen in dit openbare JSON-bestand. De brandoptie wijzigt enkele app-labels; het is geen volledige white-label rebranding.
3. Configureer Nginx voor de app
Maak een Nginx-serverblok aan, bijvoorbeeld ` /etc/nginx/sites-available/element<servernaam>`. Vervang indien nodig het domein. Deze eenvoudige configuratie serveert Element als statische bestanden en stuurt ontbrekende paden door naar ` index.html<servernaam>`, terwijl alle reacties worden gemarkeerd voor hervalidatie. Dit conservatieve cachebeleid voorkomt dat gebruikers na een release een verouderde app-shell of verouderde configuratie ontvangen; u kunt de assetcaching later aanpassen als uw implementatieproces de vereiste paden van Element die niet in de cache mogen worden opgeslagen, behoudt.
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;
}
}
De webhostingrichtlijnen van Element geven aan dat /config.*.json, /i18n, /versionof niet in de cache moeten worden opgeslagen /index.htmlen raden browservalidatie aan bij het laden van de pagina. Het voorbeeld is van toepassing no-cacheop alles als een eenvoudig uitgangspunt. Het bevat ook de door Element aanbevolen beveiligingsheaders, waaronder een framebeleid en bescherming tegen MIME-sniffing. Als u elders al een Content Security Policy (CSP) hebt gedefinieerd, voeg deze dan samen frame-ancestors 'self'met dat beleid in plaats van conflicterende beleidsregels te verzenden.
Schakel de site in en valideer Nginx voordat u de pagina opnieuw laadt:
sudo ln -s /etc/nginx/sites-available/element /etc/nginx/sites-enabled/element
sudo nginx -t
sudo systemctl reload nginx
4. Voeg HTTPS toe en test de client.
Het element moet via HTTPS worden aangeboden. Zodra DNS naar deze server verwijst en poort 80 bereikbaar is, installeer je Certbot volgens de actuele instructies voor jouw distributie. Vraag vervolgens een certificaat aan en installeer het met de Nginx-integratie. Het Certbot-project documenteert de certbot --nginxworkflow en de controles op verlenging; de pakketinstallatie verschilt per besturingssysteem, dus gebruik de actuele Nginx-instructies voor jouw versie. Als Certbot het serverblok wijzigt, voer het sudo nginx -tdan opnieuw uit en controleer of de verlenging is ingepland.
Open dit https://chat.example.comin een privévenster van de browser. Het Element-inlogscherm zou zonder ontbrekende scripts of stijlen moeten laden, je verwachte homeserver moeten weergeven en een geldig slotpictogram in de adresbalk van de browser moeten tonen. Log in met een testaccount en controleer of de browser de homeserver kan bereiken. Als het inloggen mislukt, controleer dan de ontwikkelaarsconsole en het netwerkpaneel van de browser op geblokkeerde verzoeken, certificaatfouten of een onjuiste URL base_url.
Veelvoorkomende implementatieproblemen
- Een lege of gedeeltelijk geladen pagina: controleer of Nginx
rootverwijst naar de map met de bestanden index.htmlen of de bundels en i18nde bijbehorende map zijn gekopieerd. - De verkeerde homeserver wordt weergegeven: valideer de JSON-syntaxis
config.jsonen bevestig dat het bestand zich in de webroot bevindt. Als u een domeinspecifieke configuratie hebt ingesteld config.chat.example.com.json, probeert Element dat bestand eerst config.json; de bestanden worden niet samengevoegd. - Gebruikers zien na een update oude instellingen: zorg ervoor dat
index.htmlde versionconfiguratie i18n-JSON-bestanden niet in de cache worden opgeslagen. Wis of valideer de browsercache na het wijzigen van het Nginx-beleid. - De login laadt wel, maar API-verzoeken mislukken: controleer of de URL van de homeserver correct is, HTTPS gebruikt en is geconfigureerd voor toegang via de browser, inclusief het juiste CORS-gedrag waar nodig. Het hosten van Element op Nginx fungeert niet als proxy voor of vervanging van de Matrix homeserver.
Voor een succesvolle implementatie laadt de client via HTTPS op het aangepaste domein, verwijst de configuratie naar de beoogde homeserver en kan een testaccount inloggen zonder mislukte netwerkverzoeken. De webhostingdocumentatie van Element en de Nginx-indexdocumentatie zijn de belangrijkste referenties voor de hier beschreven statische implementatie en het serverblokgedrag.