Pour héberger un client Element Web personnalisé sur Nginx, téléchargez une version précompilée officielle d'Element Web, placez ses fichiers statiques sur votre serveur web, configurez-le config.jsonavec votre serveur Matrix et servez le site via HTTPS. Nginx n'exécute pas Element lui-même : il sert les fichiers de l'application navigateur, tandis que l'application se connecte séparément à votre serveur Matrix. Utilisez un nom d'hôte différent pour le client et le serveur, par exemple `client.web` et ` chat.example.comserver.web` matrix.example.com.
Ce guide suppose l'utilisation de Debian ou Ubuntu, d'un serveur Nginx avec un nom DNS public et d'un serveur d'hébergement Matrix existant accessible via HTTPS. Il utilise la version officielle et non une version de développement. La documentation actuelle du projet Element décrit l'application web déployée comme un contenu statique et requiert une configuration spécifique ainsi que des URL de point d'entrée pour éviter la mise en cache. Consultez les notes de version et la documentation de configuration actuelle lors du choix d'une version ou de la modification des options.
1. Préparez le nom d'hôte et le serveur
Créez un enregistrement A chat.example.compointant vers l'adresse IPv4 publique du serveur Nginx. Ajoutez un enregistrement AAAA uniquement si le serveur est accessible via IPv6. Autorisez les ports TCP entrants 80 et 443 à travers le pare-feu hôte et le pare-feu cloud. Vérifiez que ces ports ne sont pas déjà utilisés par un autre serveur web.
Installez Nginx et créez un répertoire pour l'application web :
sudo apt update
sudo apt install nginx
sudo mkdir -p /var/www/element
Sur une autre machine, ouvrez la page officielle des versions d'Element Web et choisissez une version stable publiée. Téléchargez son archive web précompilée, puis transférez-la sur le serveur. Évitez d'utiliser la developbranche de développement ou une version de développement nocturne pour un service public, sauf si vous prévoyez d'exécuter un logiciel en version préliminaire.
2. Installez les fichiers statiques et configurez le serveur d'accueil.
Commencez par extraire l'archive de la version dans un répertoire temporaire. Examinez la structure de l'archive à la racine, puis copiez ses fichiers web en /var/www/elementconservant l'arborescence d'origine. La structure des paquets pouvant changer, assurez-vous que index.htmlles fichiers `package.json`, `bundles`, `package.json` i18net le fichier de configuration soient placés dans le répertoire racine de Nginx.
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
Utilisez le répertoire contenant index.htmlle fichier comme source lors de la copie du contenu de la version /var/www/element. Si l'archive ne comporte qu'un seul répertoire racine versionné, copiez son contenu plutôt que de créer un niveau supplémentaire. Ne remplacez pas un déploiement en production tant que les nouveaux fichiers ne sont pas complets ; une copie incomplète peut entraîner l'absence de certains modules JavaScript pour les utilisateurs.
Copiez le fichier de version config.sample.jsonsi config.jsonl'archive le fournit, puis modifiez-le. Element nécessite une configuration de connexion au serveur d'accueil par défaut pour démarrer. La forme recommandée est `<URL_de_base>` default_server_config, utilisant l'URL de base de l'API client. L'exemple ci-dessous est illustratif ; remplacez l'URL par l'URL réelle fournie par votre serveur d'accueil Matrix :
{
"default_server_config": {
"m.homeserver": {
"base_url": "https://matrix.example.com"
}
},
"brand": "Example Chat"
}
La documentation de configuration d'Element prend également en charge cette fonctionnalité , qui repose sur la découverte default_server_nameMatrix . Utilisez-la lorsque vous souhaitez spécifier directement l'URL du serveur d'accueil. Ne stockez aucun mot de passe, jeton d'accès, clé de signature ou autre information confidentielle dans ce fichier JSON public. Cette option modifie certaines étiquettes de l'application ; il ne s'agit pas d'une personnalisation complète..well-knowndefault_server_configbrand
3. Configurer Nginx pour l'application
Créez un bloc serveur Nginx comme celui-ci : `<nom_du_serveur>` /etc/nginx/sites-available/element. Remplacez le domaine si nécessaire. Cette configuration simple sert Element sous forme de fichiers statiques et envoie les chemins manquants à `<nom_du_serveur>` index.html, tout en marquant toutes les réponses pour revalidation. Cette politique de cache prudente évite aux utilisateurs de recevoir une application ou une configuration obsolète après une mise à jour ; vous pouvez ajuster la mise en cache des ressources ultérieurement si votre processus de déploiement conserve les chemins hors cache requis par Element.
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;
}
}
Les notes d'hébergement web d'Element indiquent de ne pas mettre en cache les balises <img> /config.*.json, /i18n<img>, /version<img> ou /index.html<img>, et recommandent la revalidation du navigateur au chargement de la page. L'exemple fourni constitue no-cacheun point de départ simple et applicable à tous les cas. Il inclut également les en-têtes de sécurité recommandés par Element, notamment une politique de gestion des cadres et une protection contre l'analyse MIME. Si vous avez déjà défini une politique de sécurité du contenu (CSP), fusionnez-la frame-ancestors 'self'avec celle-ci afin d'éviter d'envoyer des politiques contradictoires.
Activez le site et validez Nginx avant de le recharger :
sudo ln -s /etc/nginx/sites-available/element /etc/nginx/sites-enabled/element
sudo nginx -t
sudo systemctl reload nginx
4. Ajoutez HTTPS et testez le client
L'élément doit être servi via HTTPS. Une fois que le DNS pointe vers ce serveur et que le port 80 est accessible, installez Certbot en suivant les instructions correspondant à votre distribution, puis demandez et installez un certificat via son intégration Nginx. Le projet Certbot documente la certbot --nginxprocédure et les vérifications de renouvellement ; l'installation du paquet diffère selon le système d'exploitation, veuillez donc utiliser les instructions Nginx correspondant à votre version. Si Certbot modifie la configuration du serveur, relancez la commande sudo nginx -tet vérifiez que le renouvellement est bien programmé.
Ouvrez https://chat.example.comune fenêtre de navigation privée. L'écran de connexion Element devrait se charger sans scripts ni styles manquants, afficher votre serveur d'accueil et présenter une icône de cadenas valide dans la barre d'adresse. Connectez-vous avec un compte de test et vérifiez que le navigateur peut accéder au serveur d'accueil. En cas d'échec de la connexion, consultez la console de développement et le panneau réseau du navigateur pour détecter les requêtes bloquées, les erreurs de certificat ou une adresse IP incorrecte base_url.
Problèmes de déploiement courants
- Page blanche ou partiellement chargée : vérifiez que Nginx
rootpointe bien vers le répertoire contenant index.html, et que les bundles et i18nle répertoire ont été copiés avec celui-ci. - Le serveur d'accueil incorrect apparaît : vérifiez la syntaxe JSON
config.jsonet assurez-vous que le fichier se trouve à la racine du site web. Si vous configurez un serveur spécifique au domaine config.chat.example.com.json, Element essaie d'abord ce fichierconfig.json ; les fichiers ne sont pas fusionnés. - Après une mise à jour, les utilisateurs voient les anciens paramètres : assurez-vous que les fichiers `<configuration>`
index.html, version` i18n<configuration>`, `<configuration>` et `<configuration>` de configuration ne sont pas mis en cache. Videz ou revalidez le cache du navigateur après avoir modifié la politique Nginx. - La connexion réussit, mais les requêtes API échouent : vérifiez que l’URL du serveur principal est correcte, utilise le protocole HTTPS et est configurée pour l’accès par navigateur, y compris le comportement CORS approprié le cas échéant. L’élément d’hébergement sur Nginx ne sert pas de proxy et ne remplace pas le serveur principal Matrix.
Pour un déploiement réussi, le client se charge sur le domaine personnalisé via HTTPS, sa configuration pointe vers le serveur d'accueil prévu et un compte de test peut se connecter sans erreur de requête réseau. Les notes d'hébergement web d'Element et la documentation Nginx constituent les principales références pour le déploiement statique et le comportement des blocs serveur décrits ici.