Как разместить веб-клиент с пользовательскими элементами на Nginx

Если вы можете открыть свой домашний сервер Matrix, но не хотите, чтобы пользователи полагались на общедоступный веб-сайт Element, вы можете разместить Element Web как статический сайт на собственном сервере Nginx. Файлы обслуживаются Nginx; домашний сервер Matrix остается отдельной службой, которая обрабатывает учетные записи, комнаты, сообщения и федерацию. Это различие важно: перенаправление веб-клиента на Synapse не приводит к установке или настройке Synapse.

В этом пошаговом руководстве для начинающих используются имена хостов chat.example.orgдля сайта Element и matrix.example.orgдля домашнего сервера. Замените оба имени на ваши реальные имена хостов. Команды предполагают сервер Linux в стиле Debian или Ubuntu; пути к пакетам и имена служб различаются в зависимости от дистрибутива.

Что вам понадобится перед началом работы

Перед внесением изменений в серверные файлы подготовьте следующие элементы:

• Домен или поддомен для веб-клиента, DNS-запросы которого указывают на хост Nginx.
• Рабочий домашний сервер Matrix, доступный по HTTPS-адресу, например https://matrix.example.org, .
• Установлен Nginx с разрешением на редактирование конфигурации сайта и перезагрузку сервиса.
• Действительный TLS-сертификат для имени хоста веб-клиента. Пользователям следует входить в систему по протоколу HTTPS, поскольку их браузер отправляет учетные данные и токены сессии на сайт.
• Архив текущей стабильной версии Element Web из официального проекта. Избегайте развертывания отладочной сборки на общедоступном сервисе, если вы специально не собираетесь запускать там программное обеспечение для разработки.

Element Web — это браузерное приложение, состоящее из статических файлов. Текущие инструкции по установке проекта рекомендуют загрузить релиз, распаковать его на сервере, указать веб-серверу путь к полученным файлам и настроить его config.json. В Debian и Ubuntu проект также документирует пакет Element Web, который устанавливает корневой каталог веб-сервера в каталог `/etc/web` /usr/share/element-web, а его конфигурацию — в каталог `/etc/web` /etc/element-web/config.json. В описанных ниже шагах используется архив релиза, поэтому вы можете выбрать выделенный корневой каталог документов.

Перед выбором версии ознакомьтесь с инструкциями по установке Element Web и официальными релизами . Если вы используете пакет Debian, укажите Nginx путь к указанному в документации корневому каталогу веб-сервера и отредактируйте файл конфигурации пакета; не копируйте пути к архивам, указанные ниже, без изменений.

1. Загрузите и установите веб-файлы Element.

Корневой каталог — это директория, которую Nginx предоставляет посетителю при открытии вашего сайта. Создайте выделенный корневой каталог и распакуйте релиз туда. Замените фактические имена архива и директории, которые вы скачали; версии релизов со временем меняются.

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

Архив обычно распаковывается в каталог с указанием версии. Скопируйте содержимое этого каталога, включая index.htmlпакеты JavaScript, шрифты, изображения и пример конфигурации, в корневой каталог Nginx. Например, если извлеченный каталог называется 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

В команде копирования используйте реальное имя каталога с указанием версии. Nginx требуется доступ на чтение к этим файлам, а не на запись. Сохраняйте копию текущей версии и конфигурации перед обновлениями, чтобы иметь возможность восстановить их в случае сбоя развертывания.

2. Настройте клиент для использования вашего домашнего сервера.

Для запуска Element требуется адрес домашнего сервера. Скопируйте пример файла и установите URL-адрес API клиента Matrix по умолчанию. В этом примере Synapse доступен по адресу https://matrix.example.org:

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

Отредактируйте /var/www/element/config.jsonи убедитесь, что он содержит действительный JSON-объект с default_server_configзаписью, например:

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

Эта настройка определяет сервер, предлагаемый Element по умолчанию. Она не создает учетную запись Synapse и не обязывает каждого пользователя выбирать этот сервер. В текущем руководстве по настройке Element указано, default_server_configчто это предпочтительный способ предоставления информации о подключении к домашнему серверу. Более старый default_hs_urlвариант устарел. Если вы планируете ограничить пользователей одним сервером, Element описывает отдельную disable_custom_urlsнастройку; прежде чем включать ее, решите, подходит ли она для вашего сообщества.

Вы также можете настроить ограниченные параметры персонализации, такие как тему по умолчанию или определенные детали фирменного стиля, используя документированные параметры Element. Это не то же самое, что полная замена под чужой бренд: в проекте документируются выбранные параметры персонализации, а не неограниченный ребрендинг. Проверьте руководство по настройке, чтобы узнать, какие параметры поддерживаются именно той версией, которую вы устанавливаете; не копируйте настройки из другой версии, не проверив их.

См. текущий справочник по конфигурации Element Web . developДокументация может меняться по мере развития проекта, поэтому сверяйте любой необязательный ключ с версией, которую вы развертываете.

3. Добавьте сайт Nginx для веб-клиента.

Создайте конфигурацию сайта для имени хоста вашего клиента. В этом примере предполагается, что у вас уже есть сертификат по chat.example.orgуказанным путям к сертификатам. Выдача сертификата не включена, поскольку правильный метод зависит от вашего хоста, поставщика DNS и существующей настройки 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;
    }
}

Разместите блок в соответствующем файле конфигурации сайта для вашего дистрибутива, включите этот сайт при необходимости и убедитесь, что глобальная конфигурация Nginx загружает стандартный mime.typesфайл. Nginx использует MIME-типы, чтобы сообщить браузерам, является ли ответ файлом JavaScript, CSS, JSON или другим типом файла. Необходимо rootуказать на каталог, непосредственно содержащий файл index.html.

Указанный выше заголовок no-cache — это простая, удобная для развертывания базовая инструкция: браузеры повторно проверяют файлы после обновления, а не продолжают использовать устаревший клиентский код. В рекомендациях Element по хостингу прямо указано, что файлы /config.*.json, /i18n, /version, и /index.htmlне должны кэшироваться, и рекомендуется повторная проверка для корневого каталога сайта. Если вы позже добавите кэширование с более длительным сроком действия для больших статических ресурсов, поддерживайте актуальность этих путей и проверяйте именование ресурсов в релизе перед созданием правил кэширования.

В файле README веб-интерфейса Element рекомендуется использовать заголовки, запрещающие фрейминг, и заголовки, указывающие на тип контента, для сайтов, размещенных на собственном сервере. Если у вас уже настроена политика безопасности контента (CSP) в другом месте, добавьте frame-ancestors 'self'к ней новую политику вместо отправки второго заголовка CSP. Ограничительная политика CSP может блокировать необходимые скрипты приложения, поэтому не копируйте общую политику, не протестировав ее на развернутом клиенте.

Ознакомьтесь с требованиями Element Web к хостингу и кэшированию, а также с официальной документацией основного модуля Nginx для получения информации о поведении root, try_files, и обработке статических файлов.

4. Проверьте конфигурацию и перезагрузите Nginx.

Проверьте конфигурацию перед её применением. Если Nginx сообщит об ошибке, оставьте текущий процесс запущенным, пока вы исправляете указанный файл и строку; не перезагружайте неисправную конфигурацию.

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

Тест должен показать, что синтаксис корректен и проверка конфигурации прошла успешно. HTTPS-запросы должны достигать целевого хоста и возвращать успешный ответ. Также убедитесь, что сам файл конфигурации является допустимым JSON-файлом:

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

Затем откройте страницу https://chat.example.orgв браузере. Вы должны увидеть экран входа в Element или приветственный экран с вашим домашним сервером Matrix в качестве сервера по умолчанию. Попробуйте использовать тестовую учетную запись, проверьте инструменты разработчика браузера на наличие неудачных сетевых запросов и убедитесь, что вход в систему, загрузка списка комнат и отправка сообщений работают. Успешная загрузка страницы доказывает только то, что Nginx обслуживал веб-клиент; это не доказывает, что домашний сервер доступен или правильно настроен.

5. Обеспечьте корректное обнаружение домашнего сервера при необходимости.

Если ваши идентификаторы Matrix используют имя сервера, например, example.orgв то время как API Synapse находится по адресу matrix.example.org, клиенты Matrix могут использовать общеизвестный ответ по адресу https://example.org/.well-known/matrix/clientдля определения URL-адреса API. Эта необязательная конечная точка обнаружения должна находиться в домене, указанном в идентификаторе Matrix, а не автоматически в имени хоста веб-клиента Element. Минимальный ответ выглядит следующим образом:

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

Отправляйте данные в формате JSON с заголовками CORS, необходимыми для клиентов, работающих в браузере. В документации по установке Synapse приводится пример с Nginx, и указано, что он public_baseurlдолжен соответствовать URL-адресу, который клиенты используют для доступа к Synapse. Если в конфигурации вашего элемента напрямую указан правильный URL-адрес домашнего сервера, и ваши пользователи вводят эту специфичную для клиента настройку, обнаружение может не потребоваться для этой базовой конфигурации.

Следуйте общеизвестным рекомендациям клиента Synapse и протестируйте конечный URL-адрес, curlпрежде чем ожидать корректной работы обнаружения идентификатора пользователя. Для обеспечения изоляции в целях безопасности, согласно рекомендациям Synapse, рекомендуется размещать домашний сервер на отдельном зарегистрированном домене от важных веб-приложений, если это практически возможно; отдельные поддомены обеспечивают некоторую защиту, но отдельный зарегистрированный домен является более надежной рекомендацией.

Распространенные проблемы, которых следует избегать

• Nginx выдает ошибку 403: проверьте права на чтение файлов и каталогов и убедитесь, что рабочий процесс Nginx может перемещаться по каждому родительскому каталогу.
• Страница пустая или возвращает ошибку 404 для JavaScript: убедитесь, rootчто ссылка указывает на содержимое извлеченного каталога релиза, а не на каталог выше или ниже него. Проверьте журналы ошибок и доступа Nginx.
• base_urlЭлемент загружается, но не удается подключиться или войти в систему: проверьте config.jsonсертификат HTTPS домашнего сервера, доступ к брандмауэру и любую конфигурацию CORS или обратного прокси на стороне Synapse. CORS обеспечивается браузерами; статический сайт Nginx не может самостоятельно исправить политику источника домашнего сервера.
• Последние изменения не отображаются: проверьте заголовки кэша для /, /index.html, /config.json, /version, и /i18n, затем выполните принудительное обновление браузера после подтверждения замены развернутых файлов.
• Страница входа работает только по протоколу HTTP: завершите настройку TLS и перенаправьте HTTP на HTTPS, прежде чем предлагать пользователям войти в систему.

Контрольный список для окончательного развертывания

• Имя хоста Element Web разрешается в сервер Nginx и имеет действительный HTTPS-сертификат.
• Корневой каталог документа содержит файлы релиза index.html, ресурсы и действительный файл config.json.
• JSON-объект m.homeserver.base_urlуказывает на доступный HTTPS-клиентский API для вашего домашнего сервера Matrix.
• sudo nginx -tВсе проходит успешно, и Nginx обслуживает как главную страницу, так и страницу config.jsonпо протоколу HTTPS.
• Браузер может выполнить вход в систему и отправить реальный запрос на домашний сервер без ошибок, связанных с сертификатом, CORS или отсутствующими файлами.
• Ваши правила кэширования позволяют новым клиентским файлам и конфигурациям вступать в силу после обновления.

После успешного прохождения этих проверок пользовательский веб-клиент Element будет обслуживаться Nginx и сможет взаимодействовать с домашним сервером Matrix. Необходимо регулярно обновлять Element Web, сохранять резервную копию предыдущей версии и конфигурации, а также повторно проверять URL-адрес домашнего сервера и сетевые запросы браузера после каждого обновления.

Официальные ссылки

• Документация по установке Element Web
• Руководство по настройке Element Web
• Рекомендации по веб-хостингу, заголовкам безопасности и кэшированию Element
• Документация по общеизвестным URI клиента Synapse
• Рекомендации по безопасности Synapse
• Документация по основным модулям Nginx