Jak hostować klienta internetowego elementu niestandardowego na serwerze Nginx

Jeśli możesz otworzyć swój serwer domowy Matrix, ale nie chcesz, aby użytkownicy polegali na publicznej witrynie Element, możesz hostować Element Web jako witrynę statyczną na własnym serwerze Nginx. Pliki są obsługiwane przez Nginx; serwer domowy Matrix pozostaje oddzielną usługą, która obsługuje konta, pokoje, wiadomości i federację. To rozróżnienie ma znaczenie: skierowanie klienta internetowego na Synapse nie powoduje instalacji ani konfiguracji Synapse.

Ten przewodnik chat.example.orgdla początkujących dotyczy witryny Element i matrix.example.orgserwera domowego. Zastąp obie prawdziwymi nazwami hostów. Polecenia zakładają serwer Linux w stylu Debian lub Ubuntu; ścieżki pakietów i nazwy usług różnią się w zależności od dystrybucji.

Czego potrzebujesz przed rozpoczęciem

Przed zmianą plików serwera przygotuj następujące elementy:

• Domena lub subdomena dla klienta internetowego, z serwerem DNS wskazującym na hosta Nginx.
• Działający serwer domowy Matrix, do którego można uzyskać dostęp za pomocą adresu URL HTTPS, takiego jak https://matrix.example.org.
• Zainstalowano Nginx, z pozwoleniem na edycję konfiguracji witryny i ponowne załadowanie usługi.
• Ważny certyfikat TLS dla nazwy hosta klienta internetowego. Użytkownicy powinni logować się przez HTTPS, ponieważ ich przeglądarka wysyła dane uwierzytelniające i tokeny sesji do witryny.
• Aktualne, stabilne archiwum wersji Element Web z oficjalnego projektu. Unikaj wdrażania kompilacji rozwojowej w usłudze publicznej, chyba że zamierzasz uruchamiać oprogramowanie deweloperskie.

Element Web to aplikacja przeglądarkowa zbudowana ze statycznych plików. Aktualne instrukcje instalacji projektu zalecają pobranie wydania, rozpakowanie go na serwerze, wskazanie serwera WWW wynikowym plikom i skonfigurowanie config.json. W systemach Debian i Ubuntu projekt dokumentuje również pakiet Element Web, który instaluje swój katalog główny w wersji web /usr/share/element-web, a swoją konfigurację w /etc/element-web/config.json. Poniższe kroki korzystają z archiwum wydań, dzięki czemu można wybrać dedykowany katalog główny dokumentów.

Przed wyborem wersji zapoznaj się z instrukcjami instalacji Element Web i oficjalnymi wydaniami . Jeśli używasz pakietu Debian, wskaż Nginx udokumentowany katalog główny pakietu i edytuj plik konfiguracyjny pakietu; nie kopiuj poniższych ścieżek archiwów bez zmian.

1. Pobierz i zainstaluj pliki Element Web

Katalog główny dokumentów to katalog, który Nginx wyświetla, gdy użytkownik otwiera Twoją witrynę. Utwórz dedykowany katalog główny i rozpakuj tam wydanie. Zastąp go rzeczywistymi nazwami pobranego archiwum i katalogu; wersje wydań zmieniają się z czasem.

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

Archiwum zazwyczaj rozpakowuje się do katalogu z wersjonowaną wersją. Skopiuj zawartość tego katalogu, w tym index.htmlpakiety JavaScript, czcionki, obrazy i przykładową konfigurację, do katalogu głównego dokumentów Nginx. Na przykład, jeśli rozpakowany katalog ma nazwę 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

Użyj prawdziwej nazwy katalogu z wersjonowaną wersją w poleceniu copy. Nginx potrzebuje dostępu do odczytu tych plików, a nie do zapisu. Zachowaj kopię aktualnej wersji i konfiguracji przed aktualizacjami, aby móc je przywrócić w przypadku niepowodzenia wdrożenia.

2. Skonfiguruj klienta do korzystania z serwera domowego

Element potrzebuje adresu serwera domowego, aby mógł się uruchomić. Skopiuj przykładowy plik i ustaw domyślny adres URL API klienta Matrix. W tym przykładzie Synapse jest dostępny pod adresem https://matrix.example.org:

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

Edytuj /var/www/element/config.jsoni upewnij się, że zawiera prawidłowy obiekt JSON z default_server_configwpisem, na przykład:

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

Ustawia serwer oferowany domyślnie przez Element. Nie tworzy konta Synapse ani nie zmusza każdego użytkownika do wyboru tego serwera. Aktualny przewodnik konfiguracji Element opisuje default_server_configpreferowany sposób dostarczania informacji o połączeniu z serwerem domowym. Starsza default_hs_urlopcja jest przestarzała. Jeśli zamierzasz ograniczyć użytkowników do jednego serwera, Element opisuje osobne disable_custom_urlsustawienie; przed jego włączeniem zdecyduj, czy jest ono odpowiednie dla Twojej społeczności.

Możesz również skonfigurować ograniczone opcje personalizacji, takie jak domyślny motyw lub określone szczegóły brandingu, korzystając z udokumentowanych opcji Element. Nie jest to to samo, co pełna wymiana white-label: projekt dokumentuje wybrane ustawienia personalizacji, a nie nieograniczony rebranding. Sprawdź w przewodniku konfiguracji, jakie opcje są obsługiwane przez konkretną wersję, którą instalujesz; nie kopiuj ustawień z innej wersji bez ich sprawdzenia.

Zapoznaj się z aktualnymi informacjami dotyczącymi konfiguracji Element Web . developDokumentacja może ulec zmianie w miarę rozwoju projektu, dlatego należy potwierdzić każdy opcjonalny klucz z wersją, którą wdrażasz.

3. Dodaj witrynę Nginx dla klienta internetowego

Utwórz konfigurację witryny dla nazwy hosta klienta. W tym przykładzie założono, że posiadasz już certyfikat dla chat.example.orgwskazanych ścieżek certyfikatów. Wydanie certyfikatu nie jest uwzględnione, ponieważ właściwa metoda zależy od hosta, dostawcy DNS i istniejącej konfiguracji TLS.

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

Umieść blok w odpowiednim pliku witryny dla swojej dystrybucji, włącz tę witrynę, jeśli to konieczne, i sprawdź, czy globalna konfiguracja Nginx ładuje mime.typesplik standardowy. Nginx używa typów MIME, aby poinformować przeglądarkę, czy odpowiedź to JavaScript, CSS, JSON, czy inny rodzaj pliku. rootMusi wskazywać na katalog, który bezpośrednio zawiera index.html.

Powyższy nagłówek „no-cache” to prosta, przyjazna dla wdrożenia podstawa: przeglądarki ponownie walidują pliki po aktualizacji, zamiast nadal używać nieaktualnego kodu klienta. Uwagi dotyczące hostingu Element wyraźnie wymagają, aby /config.*.json, /i18n, /versioni /index.htmlnie były buforowane, i zalecają ponowną walidację katalogu głównego witryny. Jeśli później dodasz buforowanie o dłuższym czasie działania dla dużych zasobów statycznych, zachowaj aktualność tych ścieżek i zweryfikuj nazewnictwo zasobów w wydaniu przed utworzeniem reguł buforowania.

W pliku README firmy Element zaleca się stosowanie nagłówków antyframingowych i typu zawartości dla witryn hostowanych samodzielnie. Jeśli polityka bezpieczeństwa treści (CSP) została już skonfigurowana gdzie indziej, należy frame-ancestors 'self'ją uzupełnić, zamiast wysyłać kolejny nagłówek CSP. Restrykcyjny CSP może blokować wymagane skrypty aplikacji, dlatego nie należy kopiować ogólnej polityki bez przetestowania jej na wdrożonym kliencie.

Przeczytaj wymagania Element Web dotyczące hostingu i buforowania oraz oficjalną dokumentację głównego modułu Nginx dotyczącą zachowania root, try_files, oraz obsługi plików statycznych.

4. Sprawdź konfigurację i przeładuj Nginx

Przetestuj konfigurację przed jej zastosowaniem. Jeśli Nginx zgłosi błąd, kontynuuj działanie bieżącego procesu, naprawiając zgłoszony plik i wiersz; nie przeładowuj uszkodzonej konfiguracji.

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

Test powinien zgłosić, że składnia jest poprawna, a test konfiguracji zakończył się powodzeniem. Żądania HTTPS powinny dotrzeć do docelowego hosta i zwrócić pomyślną odpowiedź. Sprawdź również, czy sam plik konfiguracyjny jest prawidłowym plikiem JSON:

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

Następnie otwórz https://chat.example.orgw przeglądarce. Powinieneś zobaczyć ekran logowania lub powitalny Element z domyślnym serwerem domowym Matrix. Wypróbuj konto testowe, sprawdź narzędzia programistyczne przeglądarki pod kątem nieudanych żądań sieciowych i upewnij się, że logowanie, ładowanie listy pokoi i wysyłanie wiadomości działają. Pomyślne załadowanie strony dowodzi jedynie, że Nginx obsłużył klienta webowego; nie dowodzi to jednak, że serwer domowy jest dostępny lub poprawnie skonfigurowany.

5. Włącz funkcję wykrywania serwera domowego, gdy jest to potrzebne

Jeśli identyfikatory Matrix korzystają z nazwy serwera, takiej jak example.orgw przypadku API Synapse matrix.example.org, klienci Matrix mogą użyć znanej odpowiedzi klienta w https://example.org/.well-known/matrix/clientcelu odnalezienia adresu URL API. Ten opcjonalny punkt końcowy odnajdywania należy do domeny w identyfikatorze Matrix, a nie automatycznie do nazwy hosta klienta internetowego Element. Minimalna odpowiedź wygląda następująco:

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

Podaj go w formacie JSON z nagłówkami CORS wymaganymi dla klientów przeglądarkowych. Dokumentacja instalacyjna Synapse zawiera przykład Nginx i informuje, że public_baseurlpowinien on odpowiadać adresowi URL, którego klienci używają do połączenia z Synapse. Jeśli konfiguracja Element bezpośrednio ustawia poprawny adres URL serwera domowego, a użytkownicy wprowadzą to ustawienie specyficzne dla klienta, wykrywanie może nie być potrzebne w tej podstawowej konfiguracji.

Postępuj zgodnie ze znanymi wskazówkami klienta Synapse i przetestuj końcowy adres URL, curlzanim założysz, że wykrywanie identyfikatora użytkownika zadziała. Aby zapewnić izolację bezpieczeństwa, wskazówki bezpieczeństwa Synapse zalecają, aby w miarę możliwości hostować serwer domowy w innej zarejestrowanej domenie niż wrażliwe aplikacje internetowe; oddzielne subdomeny zapewniają pewną ochronę, ale oddzielna zarejestrowana domena jest silniejszą rekomendacją.

Typowe problemy, których należy unikać

• Nginx wyświetla błąd 403: sprawdź uprawnienia odczytu plików i katalogów i upewnij się, że proces roboczy Nginx może przejść przez każdy katalog nadrzędny.
• Strona jest pusta lub zwraca błąd 404 dla JavaScript: upewnij się, rootże wskazuje na wyodrębnioną zawartość katalogu release, a nie na katalog nad lub pod nią. Sprawdź logi błędów i dostępu Nginx.
• Element ładuje się, ale nie może się połączyć ani zalogować: sprawdź base_urlwejście config.json, certyfikat HTTPS serwera domowego, dostęp do zapory sieciowej oraz konfigurację CORS lub odwrotnego proxy po stronie Synapse. CORS jest wymuszany przez przeglądarki; statyczna witryna Nginx nie jest w stanie samodzielnie ustalić polityki pochodzenia serwera domowego.
• Ostatnie zmiany nie są widoczne: sprawdź nagłówki pamięci podręcznej pod kątem /, /index.html, /config.json, /versioni /i18n, a następnie odśwież przeglądarkę po potwierdzeniu, że wdrożone pliki zostały zastąpione.
• Strona logowania działa tylko w protokole HTTP: przed zaproszeniem użytkowników do logowania należy zakończyć konfigurację protokołu TLS i przekierować protokół HTTP na protokół HTTPS.

Ostateczna lista kontrolna wdrożenia

• Nazwa hosta Element Web wskazuje na serwer Nginx i posiada ważny certyfikat HTTPS.
• Katalog główny dokumentu zawiera wersję index.html, zasoby i prawidłowy plik config.json.
• JSON m.homeserver.base_urlwskazuje na dostępny interfejs API klienta HTTPS dla serwera domowego Matrix.
• sudo nginx -tprzechodzi, a Nginx obsługuje zarówno stronę główną, jak i config.jsonprotokół HTTPS.
• Przeglądarka może się zalogować i wysłać rzeczywiste żądanie do serwera domowego bez konieczności podawania certyfikatu, CORS lub błędów związanych z brakującymi plikami.
• Reguły pamięci podręcznej umożliwiają wprowadzenie nowych plików klienta i konfiguracji po uaktualnieniu.

Po pomyślnym przejściu tych kontroli, niestandardowy klient Element Web jest obsługiwany przez Nginx i może komunikować się z serwerem domowym Matrix. Aktualizuj Element Web, zachowaj kopię zapasową poprzedniej wersji i konfiguracji oraz ponownie sprawdzaj adres URL serwera domowego i żądania sieciowe przeglądarki po każdej aktualizacji.

Oficjalne referencje

• Dokumentacja instalacji Element Web
• Przewodnik po konfiguracji Element Web
• Hosting stron internetowych Element Web, nagłówek bezpieczeństwa i wskazówki dotyczące buforowania
• Dokumentacja znanego URI klienta Synapse
• Wskazówki dotyczące bezpieczeństwa Synapse
• Dokumentacja modułu rdzenia Nginx