Cum să găzduiești un client web cu elemente personalizate pe Nginx

Dacă poți deschide serverul tău de acasă Matrix, dar nu dorești ca utilizatorii să se bazeze pe site-ul web public Element, poți găzdui Element Web ca site static pe propriul server Nginx. Fișierele sunt servite de Nginx; serverul de acasă Matrix rămâne un serviciu separat care gestionează conturi, camere, mesaje și federație. Această distincție contează: indicarea clientului web către Synapse nu instalează sau configurează Synapse.

Această ghid pentru începători folosește chat.example.orgatât pentru site-ul Element, cât și matrix.example.orgpentru serverul principal. Înlocuiți ambele cu numele dvs. de gazdă reale. Comenzile presupun un server Linux în stil Debian sau Ubuntu; căile pachetelor și numele serviciilor variază în funcție de distribuție.

Ce ai nevoie înainte de a începe

Înainte de a modifica fișierele serverului, pregătiți aceste elemente:

• Un domeniu sau subdomeniu pentru clientul web, cu DNS care indică gazda Nginx.
• Un server Matrix funcțional, accesibil la o adresă URL HTTPS, cum ar fi https://matrix.example.org.
• Nginx instalat, cu permisiunea de a edita configurația site-ului și de a reîncărca serviciul.
• Un certificat TLS valid pentru numele de gazdă al clientului web. Utilizatorii ar trebui să se conecteze prin HTTPS, deoarece browserul lor trimite acreditări și token-uri de sesiune către site.
• O arhivă stabilă de versiuni Element Web actuale din proiectul oficial. Evitați implementarea unei versiuni de dezvoltare într-un serviciu public, cu excepția cazului în care intenționați în mod specific să rulați software de dezvoltare.

Element Web este o aplicație de browser formată din fișiere statice. Instrucțiunile actuale de instalare ale proiectului recomandă descărcarea unei versiuni, despachetarea acesteia pe server, direcționarea serverului web către fișierele rezultate și configurarea [archive-ului] config.json. Pe Debian și Ubuntu, proiectul documentează și un pachet Element Web care își instalează rădăcina web sub [archive-ul] /usr/share/element-webși configurația sa sub /etc/element-web/config.json[archive-ul]. Pașii de mai jos utilizează arhiva versiunii, astfel încât să puteți alege o rădăcină de documente dedicată.

Consultați instrucțiunile de instalare și versiunile oficiale ale Element Web înainte de a selecta o versiune. Dacă utilizați pachetul Debian în schimb, direcționați Nginx către rădăcina web documentată a pachetului și editați fișierul de configurare a pachetului; nu copiați căile de arhivă de mai jos neschimbate.

1. Descărcați și instalați fișierele Element Web

Un director rădăcină de document este directorul pe care Nginx îl servește atunci când un vizitator deschide site-ul dvs. Creați un director rădăcină dedicat și dezarhivați versiunea acolo. Înlocuiți numele arhivei și directoarelor pe care le-ați descărcat; versiunile versiunii se schimbă în timp.

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

Arhiva se despachetează în mod normal într-un director versionat. Copiați conținutul acelui director, inclusiv index.htmlpachetele JavaScript, fonturile, imaginile și configurația exemplu, în rădăcina documentului Nginx. De exemplu, dacă directorul extras este numit 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

Folosește numele directorului cu versiune reală în comanda de copiere. Nginx are nevoie de acces de citire la aceste fișiere, nu de acces de scriere. Păstrează o copie a versiunii curente și a configurației înainte de actualizări, astfel încât să le poți restaura dacă o implementare eșuează.

2. Configurați clientul să utilizeze serverul dvs. de acasă

Elementul are nevoie de o adresă de server principal înainte de a putea porni. Copiați fișierul exemplu și setați adresa URL implicită a API-ului clientului Matrix. În acest exemplu, Synapse este accesibilă la https://matrix.example.org:

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

Editați /var/www/element/config.jsonși asigurați-vă că conține un obiect JSON valid cu o default_server_configintrare, de exemplu:

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

Aceasta setare setează serverul oferit de Element în mod implicit. Nu creează un cont Synapse și nu obligă fiecare utilizator să selecteze acest server. Ghidul de configurare actual al Element documentează default_server_configmodul preferat de furnizare a informațiilor de conectare la serverul de domiciliu. default_hs_urlOpțiunea mai veche este depreciată. Dacă intenționați să restricționați utilizatorii la un singur server, Element documentează o disable_custom_urlssetare separată; decideți dacă aceasta este potrivită pentru comunitatea dvs. înainte de a o activa.

De asemenea, puteți configura personalizare limitată, cum ar fi o temă implicită sau anumite detalii de branding, utilizând opțiunile documentate ale Elementului. Aceasta nu este același lucru cu o înlocuire completă white-label: proiectul documentează setările de personalizare selectate, în loc de un rebranding nerestricționat. Consultați ghidul de configurare pentru opțiunile acceptate de versiunea exactă pe care o instalați; nu copiați setările dintr-o versiune diferită fără a le verifica.

Consultați referința de configurare curentă a Element Web . developDocumentația se poate modifica pe măsură ce proiectul evoluează, așadar confirmați orice cheie opțională în raport cu versiunea pe care o implementați.

3. Adăugați un site Nginx pentru clientul web

Creați o configurație de site pentru numele de gazdă al clientului dvs. Acest exemplu presupune că aveți deja un certificat pentru chat.example.orgcăile de certificat afișate. Emiterea certificatelor nu este inclusă deoarece metoda corectă depinde de gazda dvs., furnizorul DNS și configurația TLS existentă.

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

Plasați blocul în fișierul site-ului corespunzător pentru distribuția dvs., activați site-ul respectiv dacă este necesar și verificați dacă configurația globală Nginx încarcă mime.typesfișierul standard. Nginx folosește tipuri MIME pentru a indica browserelor dacă un răspuns este JavaScript, CSS, JSON sau alt tip de fișier. Acesta roottrebuie să indice directorul care conține direct index.html.

Antetul fără memorare în memoria cache de mai sus este o linie de bază simplă și ușor de implementat: browserele revalidează fișierele după o actualizare, în loc să continue să utilizeze cod client învechit. Notele de găzduire ale elementului impun în mod specific ca /config.*.json, /i18n, /version, și /index.htmlsă nu fie memorate în memoria cache și recomandă revalidarea pentru rădăcina site-ului. Dacă ulterior adăugați memorare în memoria cache cu durată mai lungă pentru resurse statice mari, păstrați acele căi actuale și verificați denumirea resurselor versiunii înainte de a crea reguli de cache.

Fișierul web README al Element recomandă anteturi anti-framing și de tip conținut pentru site-urile auto-găzduite. Dacă ați setat deja o Politică de securitate a conținutului (CSP) în altă parte, adăugați-o frame-ancestors 'self'la politica existentă în loc să trimiteți un al doilea antet CSP. Un CSP restrictiv poate bloca scripturile de aplicație necesare, așadar nu copiați o politică generală fără a o testa pe clientul implementat.

Citiți cerințele de găzduire și memorare în cache ale Element Web și documentația oficială a modulului principal Nginx pentru comportamentul root, try_filesși gestionării fișierelor statice.

4. Validați configurația și reîncărcați Nginx

Testați configurația înainte de a o aplica. Dacă Nginx raportează o eroare, mențineți procesul curent în funcțiune în timp ce remediați fișierul și linia raportate; nu reîncărcați o configurație defectă.

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

Testul ar trebui să raporteze că sintaxa este corectă și că testul de configurare a reușit. Cererile HTTPS ar trebui să ajungă la gazda dorită și să returneze un răspuns reușit. Confirmați că fișierul de configurare în sine este, de asemenea, un JSON valid:

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

Apoi deschideți https://chat.example.orgîntr-un browser. Ar trebui să vedeți ecranul de conectare sau de bun venit la Element cu serverul dvs. de acasă Matrix ca implicit. Încercați un cont de testare, verificați instrumentele de dezvoltare ale browserului pentru solicitări de rețea eșuate și confirmați că autentificarea, încărcarea listei de camere și trimiterea mesajelor funcționează. Încărcarea cu succes a paginii dovedește doar că Nginx a deservit clientul web; nu dovedește că serverul de acasă este accesibil sau configurat corect.

5. Faceți ca descoperirea serverelor de acasă să funcționeze atunci când este nevoie

Dacă ID-urile Matrix utilizează un nume de server, cum ar fi „ example.orgîn timp ce API-ul Synapse este la” matrix.example.org, clienții Matrix pot utiliza un răspuns bine-cunoscut al clientului la adresa https://example.org/.well-known/matrix/clientpentru a descoperi adresa URL a API-ului. Acest punct final de descoperire opțional aparține domeniului din ID-ul Matrix, nu automat numelui de gazdă al clientului web Element. Un răspuns minimal arată astfel:

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

Serviți-l ca JSON cu anteturile CORS necesare pentru clienții bazați pe browser. Documentația de instalare Synapse oferă un exemplu Nginx și spune că public_baseurlar trebui să se potrivească cu adresa URL utilizată de clienți pentru a accesa Synapse. Dacă configurația Element setează direct adresa URL corectă a serverului de bază și utilizatorii introduc acea setare specifică clientului, este posibil ca descoperirea să nu fie necesară pentru această configurare de bază.

Urmați instrucțiunile binecunoscute pentru clienți de la Synapse și testați adresa URL finală curlînainte de a vă aștepta ca descoperirea ID-ului utilizatorului să funcționeze. Pentru izolarea securității, instrucțiunile de securitate de la Synapse recomandă găzduirea serverului de domiciliu pe un domeniu înregistrat diferit de aplicațiile web sensibile, acolo unde este posibil; subdomeniile separate oferă o oarecare protecție, dar un domeniu înregistrat separat este recomandarea mai puternică.

Probleme comune de evitat

• Nginx afișează o eroare 403: verifică permisiunile de citire a fișierelor și directorului și confirmă că worker-ul Nginx poate traversa fiecare director părinte.
• Pagina este goală sau returnează eroarea 404 pentru JavaScript: asigurați-vă rootcă indică conținutul directorului de versiune extras, nu un director deasupra sau dedesubtul acestuia. Verificați jurnalele de erori și acces Nginx.
• Elementul se încarcă, dar nu se poate conecta sau autentifica: verificați base_urlin config.json, certificatul HTTPS al serverului de acasă, accesul la firewall și orice configurație CORS sau reverse-proxy pe partea Synapse. CORS este impus de browsere; un site static Nginx nu poate remedia singur o politică de origine a serverului de acasă.
• Modificările recente nu apar: verificați anteturile din memoria cache pentru /, /index.html, /config.json, /version, și /i18n, apoi actualizați complet browserul după confirmarea înlocuirii fișierelor implementate.
• Pagina de conectare funcționează doar pe HTTP: finalizați configurarea TLS și redirecționați HTTP către HTTPS înainte de a invita utilizatorii să se conecteze.

Lista de verificare finală a implementării

• Numele de gazdă Element Web se rezolvă pe serverul Nginx și are un certificat HTTPS valid.
• Rădăcina documentului conține fișierele index.html, assets-urile versiunii și un fișier valid config.json.
• Fișierele JSON m.homeserver.base_urlindică API-ul clientului HTTPS accesibil pentru serverul tău de acasă Matrix.
• sudo nginx -ttrece, iar Nginx servește atât pagina principală, cât și config.jsonprin HTTPS.
• Browserul se poate conecta și face o cerere reală către serverul principal fără erori de certificat, CORS sau fișiere lipsă.
• Regulile dvs. de cache permit ca noile fișiere și configurații client să aibă efect după o actualizare.

După ce aceste verificări trec, clientul personalizat Element Web este deservit de Nginx și poate comunica cu serverul de acasă Matrix. Mențineți Element Web actualizat, păstrați o copie de revenire la versiunea anterioară și a configurației și verificați din nou adresa URL a serverului de acasă și solicitările de rețea ale browserului după fiecare actualizare.

Referințe oficiale

• Documentația de instalare Element Web
• Ghid de configurare Element Web
• Găzduire web Element, antet de securitate și îndrumări privind memoria cache
• Documentație URI binecunoscută pentru clientul Synapse
• Îndrumări privind securitatea sinapselor
• Documentația modulului principal Nginx