Come ospitare un client Web personalizzato di Element su Nginx

Se puoi rendere pubblico il tuo homeserver Matrix ma non vuoi che gli utenti dipendano dal sito web pubblico di Element, puoi ospitare Element Web come sito statico sul tuo server Nginx. I file vengono serviti da Nginx; l'homeserver Matrix rimane un servizio separato che gestisce account, stanze, messaggi e federazione. Questa distinzione è importante: indirizzare il client web a Synapse non installa né configura Synapse.

Questa guida per principianti utilizza i nomi host chat.example.orgper il sito Element e matrix.example.orgper l'homeserver. Sostituiscili entrambi con i tuoi hostname reali. I comandi presuppongono un server Linux in stile Debian o Ubuntu; i percorsi dei pacchetti e i nomi dei servizi variano a seconda della distribuzione.

Cosa ti serve prima di iniziare

Prima di modificare i file del server, assicurati di avere a disposizione i seguenti elementi:

• Un dominio o sottodominio per il client web, con DNS che punta all'host Nginx.
• Un homeserver Matrix funzionante raggiungibile tramite un URL HTTPS, come ad esempio https://matrix.example.org.
• Nginx è installato, con autorizzazione a modificare la configurazione del sito e a ricaricare il servizio.
• È necessario un certificato TLS valido per il nome host del client web. Gli utenti devono accedere tramite HTTPS perché il loro browser invia le credenziali e i token di sessione al sito.
• Un archivio della versione stabile corrente di Element Web dal progetto ufficiale. Evita di distribuire una build di sviluppo su un servizio pubblico a meno che tu non intenda specificamente eseguire software di sviluppo.

Element Web è un'applicazione browser composta da file statici. Le istruzioni di installazione attuali del progetto raccomandano di scaricare una release, decomprimerla sul server, configurare il server web in modo che punti ai file risultanti e configurarlo config.json. Su Debian e Ubuntu, il progetto documenta anche un pacchetto Element Web che installa la sua directory principale in /usr/share/element-webe la sua configurazione in /etc/element-web/config.json. I passaggi seguenti utilizzano l'archivio della release in modo da poter scegliere una directory principale dedicata.

Prima di selezionare una versione di Element Web, consulta le istruzioni di installazione e le release ufficiali . Se utilizzi il pacchetto Debian, configura Nginx in modo che punti alla directory principale del pacchetto e modifica il file di configurazione; non copiare i percorsi degli archivi riportati di seguito senza modifiche.

1. Scarica e installa i file di Element Web

La directory principale dei documenti è la directory che Nginx serve quando un visitatore apre il tuo sito. Crea una directory principale dedicata ed estrai il file di rilascio al suo interno. Sostituisci i nomi effettivi dell'archivio e della directory che hai scaricato; le versioni dei rilasci cambiano nel tempo.

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

L'archivio viene normalmente decompresso in una directory con versione. Copia il contenuto di tale directory, inclusi index.htmli bundle JavaScript, i font, le immagini e la configurazione di esempio, nella directory principale di Nginx. Ad esempio, se la directory estratta si chiama 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

Utilizza il nome effettivo della directory con la versione corretta nel comando di copia. Nginx necessita dell'accesso in lettura a questi file, non in scrittura. Conserva una copia della versione e della configurazione correnti prima degli aggiornamenti, in modo da poterle ripristinare in caso di errore durante l'implementazione.

2. Configura il client per utilizzare il tuo homeserver

Element necessita di un indirizzo homeserver prima di poter essere avviato. Copia il file di esempio e imposta l'URL predefinito dell'API client di Matrix. In questo esempio, Synapse è raggiungibile all'indirizzo https://matrix.example.org:

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

Modificalo /var/www/element/config.jsone assicurati che contenga un oggetto JSON valido con una default_server_configvoce, ad esempio:

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

Questa impostazione definisce il server predefinito offerto da Element. Non crea un account Synapse né obbliga ogni utente a selezionare questo server. La guida di configurazione di Element attualmente in vigore descrive questo default_server_configcome il metodo preferenziale per fornire le informazioni di connessione al server principale. La vecchia default_hs_urlopzione è obsoleta. Se si intende limitare gli utenti a un solo server, Element descrive disable_custom_urlsun'impostazione separata; valutare se questa opzione è appropriata per la propria community prima di abilitarla.

È inoltre possibile configurare personalizzazioni limitate, come un tema predefinito o determinati dettagli di branding, utilizzando le opzioni documentate di Element. Questo non equivale a una sostituzione completa con marchio personalizzato: il progetto documenta le impostazioni di personalizzazione selezionate, non un rebranding illimitato. Consultare la guida alla configurazione per verificare le opzioni supportate dalla versione specifica che si sta installando; non copiare le impostazioni da una versione diversa senza averle prima controllate.

Consulta la documentazione di configurazione corrente di Element Web . La developdocumentazione può subire modifiche con l'evoluzione del progetto, pertanto verifica la compatibilità di qualsiasi chiave opzionale con la versione che stai implementando.

3. Aggiungere un sito Nginx per il client web

Crea una configurazione del sito per il nome host del tuo client. Questo esempio presuppone che tu abbia già un certificato per chat.example.orgi percorsi di certificato indicati. L'emissione del certificato non è inclusa perché il metodo corretto dipende dal tuo host, dal provider DNS e dalla configurazione TLS esistente.

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

Inserisci il blocco nel file del sito appropriato per la tua distribuzione, abilita quel sito se necessario e verifica che la configurazione globale di Nginx carichi il mime.typesfile standard. Nginx utilizza i tipi MIME per comunicare ai browser se una risposta è JavaScript, CSS, JSON o un altro tipo di file. Il percorso rootdeve puntare alla directory che contiene direttamente index.html.

L'intestazione no-cache sopra riportata è una semplice base di partenza per la distribuzione: i browser convalidano nuovamente i file dopo un aggiornamento anziché continuare a utilizzare codice client obsoleto. Le note di hosting di Element richiedono specificamente che /config.*.json, /i18n, /version, e /index.htmlnon vengano memorizzati nella cache e raccomandano la convalida per la directory principale del sito. Se in seguito si aggiunge una cache di durata maggiore per risorse statiche di grandi dimensioni, è necessario mantenere aggiornati tali percorsi e verificare la denominazione delle risorse della release prima di creare le regole della cache.

Il file README di Element consiglia di utilizzare le intestazioni anti-framing e content-type per i siti self-hosted. Se hai già impostato una Content Security Policy (CSP) altrove, aggiungila frame-ancestors 'self'a quella esistente invece di inviare una seconda intestazione CSP. Una CSP restrittiva può bloccare gli script dell'applicazione necessari, quindi non copiare una policy generica senza prima testarla sul client distribuito.

Consulta i requisiti di hosting e caching di Element Web e la documentazione ufficiale del modulo principale di Nginx per il comportamento di root, try_files, e la gestione dei file statici.

4. Convalida la configurazione e ricarica Nginx

Prima di applicare la configurazione, verificala. Se Nginx segnala un errore, mantieni il processo corrente in esecuzione mentre correggi il file e la riga segnalati; non ricaricare una configurazione errata.

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

Il test dovrebbe segnalare che la sintassi è corretta e che il test di configurazione è andato a buon fine. Le richieste HTTPS dovrebbero raggiungere l'host previsto e restituire una risposta positiva. Verificare inoltre che il file di configurazione stesso sia un JSON valido.

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

Apri quindi https://chat.example.orgil browser. Dovresti visualizzare la schermata di accesso o di benvenuto di Element con il tuo homeserver Matrix come predefinito. Prova un account di prova, controlla gli strumenti per sviluppatori del browser per eventuali richieste di rete non riuscite e verifica che l'accesso, il caricamento dell'elenco delle stanze e l'invio dei messaggi funzionino correttamente. Il caricamento corretto della pagina dimostra solo che Nginx ha servito il client web; non dimostra che l'homeserver sia raggiungibile o configurato correttamente.

5. Assicurarsi che il rilevamento del server domestico funzioni quando necessario

Se i tuoi ID Matrix utilizzano un nome server come example.orgmentre l'API Synapse si trova all'indirizzo matrix.example.org, i client Matrix possono utilizzare una risposta nota al client all'indirizzo https://example.org/.well-known/matrix/clientper scoprire l'URL dell'API. Questo endpoint di scoperta opzionale si trova sul dominio nell'ID Matrix, non automaticamente sul nome host del client web Element. Una risposta minima ha questo aspetto:

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

Servitelo come JSON con le intestazioni CORS necessarie per i client basati su browser. La documentazione di installazione di Synapse fornisce un esempio con Nginx e afferma che l' public_baseurlURL dovrebbe corrispondere a quello utilizzato dai client per raggiungere Synapse. Se la configurazione di Element imposta direttamente l'URL corretto del server principale e gli utenti inseriscono tale impostazione specifica del client, la fase di rilevamento potrebbe non essere necessaria per questa configurazione di base.

Segui le note linee guida di Synapse e testa l'URL finale curlprima di aspettarti che il rilevamento dell'ID utente funzioni. Per garantire l'isolamento della sicurezza, le linee guida di Synapse raccomandano, ove possibile, di ospitare il server domestico su un dominio registrato diverso da quello delle applicazioni web sensibili; i sottodomini separati offrono una certa protezione, ma un dominio registrato separato è la soluzione più consigliata.

Problemi comuni da evitare

• Se Nginx restituisce un errore 403, verificare i permessi di lettura di file e directory e accertarsi che il worker di Nginx possa accedere a ciascuna directory padre.
• La pagina è vuota o restituisce un errore 404 per JavaScript: assicurati che rootpunti al contenuto della directory di rilascio estratta, non a una directory sopra o sotto di essa. Controlla i log degli errori e degli accessi di Nginx.
• L'elemento si carica ma non riesce a connettersi o ad accedere: verificare il base_urlcertificato config.jsonHTTPS del server di origine, l'accesso al firewall e qualsiasi configurazione CORS o reverse proxy lato Synapse. Il CORS è imposto dai browser; un sito statico Nginx non può risolvere da solo i problemi relativi alla policy di origine del server di origine.
• Le modifiche recenti non vengono visualizzate: controlla le intestazioni della cache per /, /index.html, /config.json, /version, e /i18n, quindi aggiorna forzatamente il browser dopo aver confermato che i file distribuiti sono stati sostituiti.
• La pagina di accesso funziona solo tramite HTTP: completa la configurazione TLS e reindirizza da HTTP a HTTPS prima di invitare gli utenti ad accedere.

Lista di controllo per l'implementazione finale

• Il nome host di Element Web si risolve nel server Nginx e possiede un certificato HTTPS valido.
• La directory principale del documento contiene le risorse della release index.htmle un file di configurazione valido config.json.
• Il file JSON m.homeserver.base_urlpunta all'API client HTTPS raggiungibile per il tuo homeserver Matrix.
• sudo nginx -tI passaggi vengono eseguiti e Nginx serve sia la home page che la config.jsonpagina tramite HTTPS.
• Il browser può accedere ed effettuare una richiesta reale al server domestico senza errori relativi a certificati, CORS o file mancanti.
• Le regole della cache consentono che i nuovi file client e la configurazione abbiano effetto dopo un aggiornamento.

Una volta superati questi controlli, il client Element Web personalizzato viene gestito da Nginx e può comunicare con il server principale di Matrix. Mantieni Element Web aggiornato, conserva una copia di ripristino della versione e della configurazione precedenti e ricontrolla l'URL del server principale e le richieste di rete del browser dopo ogni aggiornamento.

Riferimenti ufficiali

• Documentazione di installazione di Element Web
• Guida alla configurazione di Element Web
• Guida di Element Web hosting, security-header e caching
• Documentazione relativa agli URI ben noti del client Synapse
• Linee guida sulla sicurezza di Synapse
• Documentazione del modulo principale di Nginx