Hoe host je een Custom Element-webclient op Nginx?

Als je je Matrix-homeserver kunt openstellen, maar niet wilt dat gebruikers afhankelijk zijn van de openbare Element-website, kun je Element Web als statische site hosten op je eigen Nginx-server. De bestanden worden door Nginx aangeboden; de Matrix-homeserver blijft een aparte service die accounts, kamers, berichten en federatie afhandelt. Dit onderscheid is belangrijk: het verwijzen van de webclient naar Synapse installeert of configureert Synapse niet.

Deze handleiding voor beginners gebruikt chat.example.orgde hostnamen van de Element-site en matrix.example.orgde homeserver. Vervang beide door uw eigen hostnamen. De commando's gaan ervan uit dat u een Linux-server gebruikt die lijkt op Debian of Ubuntu; pakketpaden en servicenamen kunnen per distributie verschillen.

Wat je nodig hebt voordat je begint

Zorg dat u de volgende items bij de hand hebt voordat u serverbestanden wijzigt:

• Een domein of subdomein voor de webclient, waarbij de DNS verwijst naar de Nginx-host.
• Een werkende Matrix-homeserver die bereikbaar is via een HTTPS-URL, zoals https://matrix.example.org.
• Nginx is geïnstalleerd, met toestemming om de siteconfiguratie te bewerken en de service opnieuw te laden.
• Een geldig TLS-certificaat voor de hostnaam van de webclient is vereist. Gebruikers dienen via HTTPS in te loggen, omdat hun browser inloggegevens en sessietokens naar de site verzendt.
• Een archief met de meest recente stabiele Element Web-release van het officiële project. Vermijd het implementeren van een ontwikkelingsversie op een openbare dienst, tenzij u specifiek van plan bent ontwikkelingssoftware te draaien.

Element Web is een browserapplicatie die bestaat uit statische bestanden. De huidige installatie-instructies van het project raden aan om een ​​release te downloaden, deze op de server uit te pakken, de webserver naar de resulterende bestanden te laten verwijzen en te configureren config.json. Op Debian en Ubuntu documenteert het project ook een Element Web-pakket dat de webroot installeert onder /usr/share/element-weben de configuratie onder /etc/element-web/config.json. De onderstaande stappen gebruiken het release-archief, zodat u een specifieke documentroot kunt kiezen.

Bekijk de installatie-instructies en officiële releases van Element Web voordat u een versie kiest. Als u in plaats daarvan het Debian-pakket gebruikt, wijs Nginx dan naar de gedocumenteerde webroot van het pakket en bewerk het configuratiebestand van het pakket; kopieer de onderstaande archiefpaden niet ongewijzigd.

1. Download en installeer de Element Web-bestanden.

Een documentroot is de map die Nginx gebruikt wanneer een bezoeker uw site opent. Maak een aparte rootmap aan en pak de release daar uit. Vervang de daadwerkelijke archief- en mapnamen door de namen die u hebt gedownload; releaseversies kunnen in de loop der tijd veranderen.

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

Het archief wordt normaal gesproken uitgepakt naar een map met versiebeheer. Kopieer de inhoud van die map, inclusief index.htmlJavaScript-bundels, lettertypen, afbeeldingen en de voorbeeldconfiguratie, naar de documentroot van Nginx. Als de uitgepakte map bijvoorbeeld de naam heeft 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

Gebruik de daadwerkelijke versie van de mapnaam in het kopieercommando. Nginx heeft leesrechten nodig voor deze bestanden, geen schrijfrechten. Bewaar een kopie van de huidige release en configuratie vóór upgrades, zodat u deze kunt herstellen als een implementatie mislukt.

2. Configureer de client om uw thuisserver te gebruiken.

Element heeft een homeserver-adres nodig voordat het kan starten. Kopieer het voorbeeldbestand en stel de standaard Matrix client API-URL in. In dit voorbeeld is Synapse bereikbaar via https://matrix.example.org:

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

Bewerk het bestand /var/www/element/config.jsonen zorg ervoor dat het een geldig JSON-object met een default_server_configitem bevat, bijvoorbeeld:

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

Hiermee wordt de server ingesteld die Element standaard aanbiedt. Er wordt geen Synapse-account aangemaakt en gebruikers worden niet gedwongen deze server te selecteren. De huidige configuratiehandleiding van Element beschrijft dit default_server_configals de aanbevolen manier om verbindingsinformatie voor de thuisserver te verstrekken. De oudere default_hs_urloptie is verouderd. Als u gebruikers wilt beperken tot één server, beschrijft Element een aparte disable_custom_urlsinstelling; bepaal of dit geschikt is voor uw community voordat u deze inschakelt.

U kunt ook beperkte aanpassingen configureren, zoals een standaardthema of bepaalde merkdetails, met behulp van de gedocumenteerde Element-opties. Dit is niet hetzelfde als een volledige white-label vervanging: het project documenteert geselecteerde aanpassingsinstellingen in plaats van onbeperkte rebranding. Raadpleeg de configuratiehandleiding voor de opties die worden ondersteund door de exacte versie die u installeert; kopieer geen instellingen van een andere versie zonder deze eerst te controleren.

Raadpleeg de huidige configuratiehandleiding van Element Web . De developdocumentatie kan veranderen naarmate het project zich ontwikkelt, dus controleer of alle optionele sleutels overeenkomen met de release die u implementeert.

3. Voeg een Nginx-site toe voor de webclient.

Maak een siteconfiguratie aan voor de hostnaam van uw client. Dit voorbeeld gaat ervan uit dat u al een certificaat hebt chat.example.orgop de aangegeven certificaatpaden. Certificaatuitgifte is niet inbegrepen, omdat de juiste methode afhangt van uw host, DNS-provider en bestaande TLS-configuratie.

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;
    }
}

Plaats het blok in het juiste sitebestand voor uw distributie, schakel die site indien nodig in en controleer of de globale Nginx-configuratie het standaardbestand laadt mime.types. Nginx gebruikt MIME-typen om browsers te laten weten of een reactie JavaScript, CSS, JSON of een ander type bestand is. Het rootmoet verwijzen naar de map die het bestand direct bevat index.html.

De bovenstaande 'no-cache'-header is een eenvoudige, implementatievriendelijke basislijn: browsers valideren bestanden opnieuw na een update in plaats van verouderde clientcode te blijven gebruiken. De hostingrichtlijnen van Element vereisen specifiek dat /config.*.json, /i18n, /version, en /index.htmlniet in de cache worden opgeslagen en raden hervalidatie aan voor de site-root. Als u later caching voor grotere statische bestanden toevoegt, zorg er dan voor dat die paden actueel blijven en controleer de bestandsnamen van de release voordat u cacheregels aanmaakt.

In de README van Element wordt aanbevolen om anti-framing- en content-type-headers te gebruiken voor zelfgehoste websites. Als u elders al een Content Security Policy (CSP) hebt ingesteld, voeg deze dan toe frame-ancestors 'self'aan dat bestaande beleid in plaats van een tweede CSP-header te verzenden. Een restrictieve CSP kan vereiste applicatiescripts blokkeren, dus kopieer geen algemeen beleid zonder het eerst te testen op de geïmplementeerde client.

Lees de hosting- en cachingvereisten van Element Web en de officiële documentatie van de Nginx-kernmodule voor meer informatie over het gedrag van root, try_files, en de afhandeling van statische bestanden.

4. Valideer de configuratie en herlaad Nginx.

Test de configuratie voordat u deze toepast. Als Nginx een foutmelding geeft, laat het huidige proces dan doorlopen terwijl u het betreffende bestand en de betreffende regel corrigeert; laad geen defecte configuratie opnieuw.

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

De test moet aangeven dat de syntax correct is en dat de configuratietest geslaagd is. De HTTPS-verzoeken moeten de beoogde host bereiken en een succesvol antwoord retourneren. Controleer ook of het configuratiebestand zelf geldige JSON is.

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

Open de pagina vervolgens https://chat.example.orgin een browser. Je zou het Element-inlogscherm of welkomstscherm moeten zien, met je Matrix-homeserver als standaard. Probeer een testaccount, controleer de ontwikkelaarstools van je browser op mislukte netwerkverzoeken en bevestig dat inloggen, het laden van de kamerslijst en het verzenden van berichten werken. Dat een pagina succesvol laadt, bewijst alleen dat Nginx de webclient heeft bediend; het bewijst niet dat de homeserver bereikbaar of correct geconfigureerd is.

5. Zorg ervoor dat de detectie van de thuisserver werkt wanneer dat nodig is.

Als uw Matrix-ID's een servernaam gebruiken zoals example.orgterwijl de Synapse API zich bevindt op matrix.example.org, kunnen Matrix-clients een client-bekende respons op gebruiken https://example.org/.well-known/matrix/clientom de API-URL te achterhalen. Dit optionele ontdekkings-eindpunt hoort op het domein in de Matrix-ID te staan, niet automatisch op de hostnaam van de Element-webclient. Een minimale respons ziet er als volgt uit:

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

Geef het aan als JSON met de CORS-headers die nodig zijn voor browsergebaseerde clients. De installatiedocumentatie van Synapse geeft een Nginx-voorbeeld en stelt dat public_baseurlde URL moet overeenkomen met de URL die clients gebruiken om Synapse te bereiken. Als uw Element-configuratie direct de juiste homeserver-URL instelt en uw gebruikers die clientspecifieke instelling invoeren, is discovery mogelijk niet nodig voor deze basisconfiguratie.

Volg de algemeen bekende richtlijnen van Synapse en test de uiteindelijke URL curlvoordat u verwacht dat de gebruikers-ID-detectie werkt. Voor een optimale beveiliging adviseert Synapse om de thuisserver, indien mogelijk, op een ander geregistreerd domein te hosten dan gevoelige webapplicaties; aparte subdomeinen bieden enige bescherming, maar een apart geregistreerd domein is de sterkere aanbeveling.

Veelvoorkomende problemen die je moet vermijden

• Nginx geeft een 403-foutmelding: controleer de leesrechten van bestanden en mappen en bevestig dat de Nginx-worker toegang heeft tot elke bovenliggende map.
• De pagina is leeg of geeft een 404-foutmelding voor JavaScript: zorg ervoor rootdat de URL verwijst naar de inhoud van de uitgepakte release-directory en niet naar een directory erboven of eronder. Controleer de Nginx-fout- en toegangslogboeken.
• Het element laadt wel, maar er kan geen verbinding worden gemaakt of ingelogd: controleer de base_urlinstellingen config.json, het HTTPS-certificaat van de homeserver, de firewalltoegang en eventuele CORS- of reverse-proxy-configuraties aan de Synapse-kant. CORS wordt afgedwongen door browsers; een statische Nginx-site kan een origin policy van de homeserver niet zelf aanpassen.
• Recente wijzigingen worden niet weergegeven: controleer de cacheheaders op /, /index.html, /config.json, /version, en /i18n, en vernieuw vervolgens de browser nadat u hebt bevestigd dat de geïmplementeerde bestanden zijn vervangen.
• De inlogpagina werkt alleen via HTTP: voltooi de TLS-configuratie en leid HTTP door naar HTTPS voordat u gebruikers uitnodigt om in te loggen.

Definitieve implementatiechecklist

• De hostnaam van Element Web verwijst naar de Nginx-server en beschikt over een geldig HTTPS-certificaat.
• De documentmap bevat de bestanden index.html, assets en een geldige release config.json.
• De JSON-gegevens m.homeserver.base_urlverwijzen naar de bereikbare HTTPS-client-API voor uw Matrix-homeserver.
• sudo nginx -tNginx serveert zowel de homepage als config.jsonde server via HTTPS.
• De browser kan inloggen en een daadwerkelijke aanvraag naar de thuisserver sturen zonder certificaat-, CORS- of ontbrekende-bestandfouten.
• Uw cacheregels zorgen ervoor dat nieuwe clientbestanden en configuraties na een upgrade van kracht worden.

Zodra deze controles geslaagd zijn, wordt de aangepaste Element Web-client door Nginx aangeboden en kan deze communiceren met de Matrix-homeserver. Zorg ervoor dat Element Web up-to-date blijft, bewaar een back-up van de vorige release en configuratie en controleer na elke upgrade de homeserver-URL en de netwerkverzoeken van de browser opnieuw.

Officiële referenties

• Installatiehandleiding Element Web
• Configuratiehandleiding voor Element Web
• Element Webhosting, securityheaders en caching-richtlijnen
• Synapse client bekende URI-documentatie
• Beveiligingsrichtlijnen voor Synapse
• Nginx core module documentatie