Comment héberger un client web Custom Element sur Nginx

Si vous pouvez accéder à votre serveur Matrix mais que vous ne souhaitez pas que les utilisateurs dépendent du site web public d'Element, vous pouvez héberger Element Web comme un site statique sur votre propre serveur Nginx. Les fichiers sont servis par Nginx ; le serveur Matrix reste un service distinct qui gère les comptes, les salons, les messages et la fédération. Cette distinction est importante : configurer Synapse pour qu'il s'affiche dans le client web n'installe ni ne configure Synapse.

Ce guide pour débutants utilise `<nom_du_site>` et ` <nom_du_serveur> chat.example.org` pour le site Element et ` matrix.example.org<nom_du_serveur>` pour le serveur d'accueil. Remplacez ces noms par vos noms d'hôtes réels. Les commandes supposent un serveur Linux de type Debian ou Ubuntu ; les chemins d'accès aux paquets et les noms de services varient selon la distribution.

Ce dont vous avez besoin avant de commencer

Préparez les éléments suivants avant de modifier les fichiers du serveur :

• Un domaine ou un sous-domaine pour le client web, avec un DNS pointant vers l'hôte Nginx.
• Un serveur d'accueil Matrix fonctionnel accessible via une URL HTTPS, telle que https://matrix.example.org.
• Nginx est installé, avec l'autorisation de modifier sa configuration et de recharger le service.
• Un certificat TLS valide est requis pour le nom d'hôte du client web. Les utilisateurs doivent se connecter via HTTPS car leur navigateur envoie les identifiants et les jetons de session au site.
• Archive de la version stable actuelle d'Element Web provenant du projet officiel. Évitez de déployer une version de développement sur un service public, sauf si vous souhaitez spécifiquement exécuter un logiciel en développement.

Element Web est une application web composée de fichiers statiques. Les instructions d'installation actuelles du projet recommandent de télécharger une version, de la décompresser sur le serveur, de configurer le serveur web pour qu'il pointe vers les fichiers obtenus, puis de procéder à la configuration config.json. Sous Debian et Ubuntu, le projet propose également un paquet Element Web qui installe son répertoire racine web sous `/usr/local/bin` /usr/share/element-webet sa configuration sous `/usr/ /etc/element-web/config.jsonlocal/bin`. Les étapes ci-dessous utilisent l'archive de la version, ce qui vous permet de choisir un répertoire racine dédié.

Avant de choisir une version d'Element Web, veuillez consulter les instructions d'installation et les versions officielles . Si vous utilisez le paquet Debian, configurez Nginx pour qu'il pointe vers le répertoire racine web documenté du paquet et modifiez le fichier de configuration ; ne copiez pas les chemins d'accès aux archives ci-dessous sans les modifier.

1. Téléchargez et installez les fichiers Web Element

Le répertoire racine est celui que Nginx utilise lorsqu'un visiteur accède à votre site. Créez un répertoire racine dédié et décompressez-y l'archive. Remplacez les noms d'archive et de répertoire par ceux que vous avez téléchargés ; les versions de l'archive évoluent avec le temps.

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

L'archive est généralement décompressée dans un répertoire versionné. Copiez le contenu de ce répertoire, y compris index.htmlles fichiers JavaScript, les polices, les images et la configuration d'exemple, dans le répertoire racine de Nginx. Par exemple, si le répertoire extrait est nommé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

Utilisez le nom de répertoire versionné réel dans la commande de copie. Nginx a besoin d'un accès en lecture à ces fichiers, et non en écriture. Conservez une copie de la version et de la configuration actuelles avant les mises à niveau afin de pouvoir les restaurer en cas d'échec de déploiement.

2. Configurez le client pour qu'il utilise votre serveur domestique.

Element nécessite l'adresse d'un serveur d'accueil pour démarrer. Copiez le fichier d'exemple et définissez l'URL par défaut de l'API client Matrix. Dans cet exemple, Synapse est accessible à l'adressehttps://matrix.example.org :

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

Modifiez-le /var/www/element/config.jsonet assurez-vous qu'il contient un objet JSON valide avec une default_server_configentrée, par exemple :

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

Cela configure le serveur proposé par défaut par Element. Aucun compte Synapse n'est créé et aucun utilisateur n'est obligé de sélectionner ce serveur. Le guide de configuration actuel d'Element indique default_server_configqu'il s'agit de la méthode recommandée pour fournir les informations de connexion au serveur d'accueil. L'ancienne default_hs_urloption est obsolète. Si vous souhaitez limiter l'accès des utilisateurs à un seul serveur, Element propose une disable_custom_urlsoption dédiée ; évaluez sa pertinence pour votre communauté avant de l'activer.

Vous pouvez également configurer une personnalisation limitée, comme un thème par défaut ou certains éléments de marque, à l'aide des options documentées d'Element. Il ne s'agit pas d'un remplacement complet par une marque blanche : le projet documente des paramètres de personnalisation sélectionnés plutôt qu'un changement de marque sans restriction. Consultez le guide de configuration pour connaître les options prises en charge par la version exacte que vous installez ; ne copiez pas les paramètres d'une autre version sans les avoir vérifiés.

Consultez la documentation de configuration actuelle d'Element Webdevelop . Celle-ci pouvant évoluer au fil du projet, vérifiez la compatibilité de chaque clé optionnelle avec la version déployée.

3. Ajouter un site Nginx pour le client web

Créez une configuration de site pour le nom d'hôte de votre client. Cet exemple suppose que vous disposez déjà d'un certificat chat.example.orgaux emplacements indiqués. L'émission du certificat n'est pas incluse, car la méthode appropriée dépend de votre hébergeur, de votre fournisseur DNS et de votre configuration TLS existante.

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

Placez le bloc dans le fichier de configuration approprié à votre distribution, activez ce site si nécessaire et vérifiez que la configuration globale de Nginx charge bien le mime.typesfichier standard. Nginx utilise les types MIME pour indiquer aux navigateurs si une réponse est un fichier JavaScript, CSS, JSON ou autre. Le chemin rootd'accès doit pointer vers le répertoire contenant directement le fichier index.html.

L'en-tête « no-cache » ci-dessus constitue une base simple et facile à déployer : les navigateurs revalident les fichiers après une mise à jour plutôt que de continuer à utiliser un code client obsolète. Les notes d'hébergement d'Element exigent spécifiquement que les fichiers /config.*.json`<script>` /i18n, /version`<script>`, `<script>` et ` /index.html<script>` ne soient pas mis en cache et recommandent la revalidation de la racine du site. Si vous ajoutez ultérieurement une mise en cache à plus long terme pour les ressources statiques volumineuses, veillez à maintenir ces chemins à jour et vérifiez la nomenclature des ressources de la version avant de créer les règles de cache.

Le fichier README d'Element recommande l'utilisation des en-têtes anti-framing et Content-Type pour les sites auto-hébergés. Si vous avez déjà configuré une politique de sécurité du contenu (CSP), ajoutez frame-ancestors 'self'-y les règles au lieu d'envoyer un second en-tête CSP. Une CSP restrictive peut bloquer des scripts d'application essentiels ; par conséquent, ne copiez pas une politique trop générale sans l'avoir testée sur le client déployé.

Consultez les exigences d'hébergement et de mise en cache d'Element Web ainsi que la documentation officielle du module principal de Nginx pour connaître le comportement de root, try_files, et la gestion des fichiers statiques.

4. Validez la configuration et rechargez Nginx.

Testez la configuration avant de l'appliquer. Si Nginx signale une erreur, laissez le processus en cours d'exécution pendant que vous corrigez le fichier et la ligne concernés ; ne rechargez pas une configuration défectueuse.

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

Le test doit indiquer que la syntaxe est correcte et que le test de configuration a réussi. Les requêtes HTTPS doivent atteindre l'hôte prévu et renvoyer une réponse positive. Vérifiez également que le fichier de configuration est un fichier JSON valide.

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

Ouvrez ensuite la page https://chat.example.orgdans un navigateur. Vous devriez voir l'écran de connexion ou d'accueil d'Element, avec votre serveur Matrix comme serveur par défaut. Créez un compte de test, vérifiez dans les outils de développement de votre navigateur si des requêtes réseau ont échoué et assurez-vous que la connexion, le chargement de la liste des salons et l'envoi de messages fonctionnent. Le chargement réussi d'une page prouve seulement que Nginx a servi le client web ; cela ne prouve pas que le serveur est accessible ou correctement configuré.

5. Faire en sorte que la découverte du serveur d'accueil fonctionne lorsque nécessaire.

Si vos identifiants Matrix utilisent un nom de serveur tel que `<nom_serveur>` example.orgalors que l'API Synapse est accessible à `<adresse_API>` matrix.example.org, les clients Matrix peuvent utiliser une réponse client connue à ` https://example.org/.well-known/matrix/client<adresse_API>` pour découvrir l'URL de l'API. Ce point de terminaison de découverte optionnel doit être associé au domaine de l'identifiant Matrix, et non automatiquement au nom d'hôte du client web Element. Voici un exemple de réponse minimale :

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

Servez-le au format JSON avec les en-têtes CORS requis pour les clients web. La documentation d'installation de Synapse fournit un exemple avec Nginx et précise que public_baseurll'URL doit correspondre à celle utilisée par les clients pour accéder à Synapse. Si votre configuration Element définit directement l'URL correcte du serveur d'accueil et que vos utilisateurs saisissent ce paramètre spécifique au client, la découverte automatique ne sera peut-être pas nécessaire pour cette configuration de base.

Suivez les recommandations de Synapse concernant les clients et testez l'URL finale curlavant d'utiliser la découverte des identifiants utilisateur. Pour des raisons de sécurité, Synapse recommande d'héberger le serveur principal sur un domaine différent de celui des applications web sensibles, lorsque cela est possible ; les sous-domaines offrent une certaine protection, mais un domaine distinct est la solution la plus sûre.

Problèmes courants à éviter

• Nginx affiche une erreur 403 : vérifiez les permissions de lecture des fichiers et des répertoires et assurez-vous que le processus Nginx peut parcourir chaque répertoire parent.
• La page est blanche ou renvoie une erreur 404 pour JavaScript : assurez-vous rootque le chemin pointe vers le contenu du répertoire de la version extraite, et non vers un répertoire parent ou parent. Consultez les journaux d'erreurs et d'accès de Nginx.
• L'élément se charge mais la connexion échoue : vérifiez le base_urlfichier `.py` config.json, le certificat HTTPS du serveur d'hébergement, l'accès au pare-feu et toute configuration CORS ou de proxy inverse côté Synapse. La gestion du CORS est assurée par les navigateurs ; un site statique Nginx ne peut pas modifier à lui seul la politique d'origine du serveur d'hébergement.
• Les modifications récentes n'apparaissent pas : vérifiez les en-têtes du cache pour /, /index.html, /config.json, /version, et /i18n, puis actualisez le navigateur après avoir confirmé que les fichiers déployés ont été remplacés.
• La page de connexion fonctionne uniquement en HTTP : finalisez la configuration TLS et redirigez les utilisateurs HTTP vers HTTPS avant de les inviter à se connecter.

Liste de contrôle finale du déploiement

• Le nom d'hôte Element Web pointe vers le serveur Nginx et possède un certificat HTTPS valide.
• Le répertoire racine contient les index.htmlressources de la version et un fichier valide config.json.
• Les éléments JSON m.homeserver.base_urlpointent vers l'API client HTTPS accessible pour votre serveur Matrix.
• sudo nginx -tNginx gère les requêtes HTTPS et sert à la fois la page d'accueil et la page config.jsonvia HTTPS.
• Le navigateur peut se connecter et effectuer une véritable requête auprès du serveur d'accueil sans erreur de certificat, de CORS ou de fichier manquant.
• Vos règles de cache permettent aux nouveaux fichiers clients et à la configuration de prendre effet après une mise à niveau.

Une fois ces vérifications effectuées, le client Web Element personnalisé est servi par Nginx et peut communiquer avec le serveur Matrix. Veillez à maintenir Element Web à jour, conservez une copie de sauvegarde de la version et de la configuration précédentes, et revérifiez l'URL du serveur et les requêtes réseau du navigateur après chaque mise à jour.

Références officielles

• Documentation d'installation d'Element Web
• Guide de configuration d'Element Web
• Guide d'hébergement Web Element, en-tête de sécurité et mise en cache
• Documentation des URI connues du client Synapse
• Conseils de sécurité Synapse
• Documentation du module principal Nginx