Como hospedar um cliente web personalizado do Element no Nginx

Se você consegue abrir seu servidor Matrix, mas não quer que os usuários dependam do site público do Element, você pode hospedar o Element Web como um site estático em seu próprio servidor Nginx. Os arquivos são servidos pelo Nginx; o servidor Matrix permanece um serviço separado que gerencia contas, salas, mensagens e federação. Essa distinção é importante: apontar o cliente web para o Synapse não instala nem configura o Synapse.

Este guia para iniciantes usa `<nome_do_servidor>` chat.example.orgpara o site do Element e ` matrix.example.org<nome_do_servidor>` para o servidor doméstico. Substitua ambos pelos seus nomes de host reais. Os comandos pressupõem um servidor Linux no estilo Debian ou Ubuntu; os caminhos dos pacotes e os nomes dos serviços variam de acordo com a distribuição.

O que você precisa antes de começar

Tenha estes itens em mãos antes de alterar os arquivos do servidor:

• Um domínio ou subdomínio para o cliente web, com DNS apontando para o host Nginx.
• Um servidor doméstico Matrix em funcionamento, acessível por um URL HTTPS, como por exemplo https://matrix.example.org: .
• Nginx instalado, com permissão para editar a configuração do site e recarregar o serviço.
• É necessário um certificado TLS válido para o nome do host do cliente web. Os usuários devem fazer login via HTTPS, pois seus navegadores enviam credenciais e tokens de sessão para o site.
• Arquivo da versão estável atual do Element Web, proveniente do projeto oficial. Evite implantar uma versão de desenvolvimento em um serviço público, a menos que você pretenda executar software em desenvolvimento.

O Element Web é um aplicativo de navegador composto por arquivos estáticos. As instruções de instalação atuais do projeto recomendam baixar uma versão, descompactá-la no servidor, configurar o servidor web para usar os arquivos resultantes e realizar a configuração config.json. No Debian e Ubuntu, o projeto também documenta um pacote do Element Web que instala seu diretório raiz em `/usr/local/web` /usr/share/element-webe sua configuração em `/etc/elementweb` /etc/element-web/config.json. Os passos a seguir utilizam o arquivo da versão, permitindo que você escolha um diretório raiz dedicado.

Antes de selecionar uma versão do Element Web, consulte as instruções de instalação e os lançamentos oficiais . Se optar por usar o pacote Debian, configure o Nginx para apontar para o diretório raiz do pacote, conforme documentado, e edite o arquivo de configuração do pacote; não copie os caminhos dos arquivos compactados abaixo sem alterações.

1. Baixe e instale os arquivos do Element Web.

O diretório raiz é o diretório que o Nginx serve quando um visitante acessa seu site. Crie um diretório raiz dedicado e descompacte o arquivo lá. Substitua os nomes reais do arquivo e do diretório que você baixou; as versões mudam com o tempo.

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

O arquivo normalmente é descompactado em um diretório versionado. Copie o conteúdo desse diretório, incluindo index.htmlos pacotes JavaScript, fontes, imagens e a configuração de exemplo, para o diretório raiz do Nginx. Por exemplo, se o diretório extraído se chamar 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

Use o nome real do diretório com a versão correta no comando de cópia. O Nginx precisa de acesso de leitura a esses arquivos, não de acesso de gravação. Mantenha uma cópia da versão e configuração atuais antes das atualizações para que você possa restaurá-las caso uma implantação falhe.

2. Configure o cliente para usar seu servidor doméstico.

O Element precisa de um endereço de servidor doméstico para iniciar. Copie o arquivo de exemplo e defina a URL padrão da API do cliente Matrix. Neste exemplo, o Synapse está acessível em https://matrix.example.org:

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

Edite /var/www/element/config.jsone certifique-se de que ele contenha um objeto JSON válido com uma default_server_configentrada, por exemplo:

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

Esta opção define o servidor que o Element oferece por padrão. Ela não cria uma conta Synapse nem força todos os usuários a selecionarem este servidor. O guia de configuração atual do Element documenta esta opção default_server_configcomo a maneira preferencial de fornecer informações de conexão com o servidor doméstico. A opção anterior default_hs_urlestá obsoleta. Se você pretende restringir os usuários a um único servidor, o Element documenta uma disable_custom_urlsconfiguração separada; avalie se ela é adequada para sua comunidade antes de habilitá-la.

Você também pode configurar personalizações limitadas, como um tema padrão ou certos detalhes de marca, usando as opções documentadas do Elemento. Isso não equivale a uma substituição completa por uma marca totalmente personalizada: o projeto documenta configurações de personalização selecionadas, e não uma repaginação irrestrita. Consulte o guia de configuração para verificar as opções compatíveis com a versão específica que você está instalando; não copie configurações de uma versão diferente sem verificá-las.

Consulte a documentação de configuração atual do Element Web . A developdocumentação pode mudar conforme o projeto evolui, portanto, confirme qualquer chave opcional na versão que você implantar.

3. Adicione um site Nginx para o cliente web.

Crie uma configuração de site para o nome de host do seu cliente. Este exemplo pressupõe que você já tenha um certificado chat.example.orgnos caminhos de certificado mostrados. A emissão de certificados não está incluída, pois o método correto depende do seu host, provedor de DNS e configuração TLS existente.

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

Coloque o bloco no arquivo de site apropriado para sua distribuição, habilite esse site, se necessário, e verifique se a configuração global do Nginx carrega o mime.typesarquivo padrão. O Nginx usa tipos MIME para informar aos navegadores se uma resposta é JavaScript, CSS, JSON ou outro tipo de arquivo. O caminho rootdeve apontar para o diretório que contém diretamente o arquivo index.html.

O cabeçalho `no-cache` acima é uma configuração básica simples e amigável para implantação: os navegadores revalidam os arquivos após uma atualização, em vez de continuarem usando código de cliente desatualizado. As notas de hospedagem do Element exigem especificamente que /config.*.json` <script>` /i18n, ` /version<script>`, `<script>` e /index.html`<script>` não sejam armazenados em cache e recomendam a revalidação para a raiz do site. Se você adicionar posteriormente um cache de longa duração para arquivos estáticos grandes, mantenha esses caminhos atualizados e verifique a nomenclatura dos arquivos da versão antes de criar regras de cache.

O arquivo README da Element recomenda o uso de cabeçalhos anti-framing e content-type para sites auto-hospedados. Se você já configurou uma Política de Segurança de Conteúdo (CSP) em outro lugar, adicione- frame-ancestors 'self'a à política existente em vez de enviar um segundo cabeçalho CSP. Uma CSP restritiva pode bloquear scripts de aplicativos necessários; portanto, não copie uma política ampla sem testá-la no cliente implantado.

Leia os requisitos de hospedagem e cache do Element Web e a documentação oficial do módulo principal do Nginx para obter informações sobre o comportamento de root`nginx.h`, try_files`nginx.css` e o tratamento de arquivos estáticos.

4. Valide a configuração e recarregue o Nginx.

Teste a configuração antes de aplicá-la. Se o Nginx reportar um erro, mantenha o processo atual em execução enquanto corrige o arquivo e a linha reportados; não recarregue uma configuração corrompida.

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

O teste deve indicar que a sintaxe está correta e que o teste de configuração foi bem-sucedido. As requisições HTTPS devem alcançar o host pretendido e retornar uma resposta positiva. Confirme também se o próprio arquivo de configuração é um JSON válido.

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

Em seguida, abra https://chat.example.orgem um navegador. Você deverá ver a tela de login ou de boas-vindas do Element com o seu servidor Matrix como padrão. Experimente com uma conta de teste, verifique as ferramentas de desenvolvedor do navegador em busca de falhas nas requisições de rede e confirme se o login, o carregamento da lista de salas e o envio de mensagens funcionam. O carregamento bem-sucedido de uma página apenas comprova que o Nginx serviu o cliente web; não comprova que o servidor está acessível ou configurado corretamente.

5. Faça com que a descoberta do servidor doméstico funcione quando necessário.

Se seus IDs do Matrix usarem um nome de servidor como `<nome_do_servidor>` example.orgenquanto a API do Synapse estiver em `<endereço_da_API>` matrix.example.org, os clientes do Matrix podem usar uma resposta de cliente bem conhecido em ` https://example.org/.well-known/matrix/client<endereço_da_API>` para descobrir a URL da API. Este endpoint de descoberta opcional pertence ao domínio no ID do Matrix, e não automaticamente ao nome do host do cliente web do Element. Uma resposta mínima seria semelhante a esta:

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

Sirva-o como JSON com os cabeçalhos CORS necessários para clientes baseados em navegador. A documentação de instalação do Synapse fornece um exemplo com Nginx e afirma que a public_baseurlURL deve corresponder à URL usada pelos clientes para acessar o Synapse. Se a sua configuração do Element definir diretamente a URL correta do servidor e seus usuários inserirem essa configuração específica do cliente, a descoberta pode não ser necessária para esta configuração básica.

Siga as orientações de segurança do cliente Synapse e teste a URL final curlantes de esperar que a descoberta de IDs de usuário funcione. Para isolamento de segurança, as diretrizes de segurança do Synapse recomendam hospedar o servidor doméstico em um domínio registrado diferente dos aplicativos web sensíveis, sempre que possível; subdomínios separados oferecem alguma proteção, mas um domínio registrado separado é a recomendação mais forte.

Problemas comuns a evitar

• O Nginx está retornando um erro 403: verifique as permissões de leitura de arquivos e diretórios e confirme se o processo Nginx consegue acessar cada diretório pai.
• A página está em branco ou retorna erro 404 para JavaScript: certifique-se de rootque o caminho aponta para o conteúdo do diretório de lançamento extraído, e não para um diretório acima ou abaixo dele. Verifique os logs de erro e de acesso do Nginx.
• O elemento carrega, mas não é possível conectar ou fazer login: verifique o base_urlarquivo `/etc config.json/localhost`, o certificado HTTPS do servidor, o acesso ao firewall e qualquer configuração de CORS ou proxy reverso no Synapse. O CORS é imposto pelos navegadores; um site estático Nginx não pode corrigir a política de origem do servidor por si só.
• As alterações recentes não aparecem: verifique os cabeçalhos do cache para /, /index.html, /config.json, /version, e /i18n, e atualize a página completamente após confirmar que os arquivos implantados foram substituídos.
• A página de login funciona apenas em HTTP: conclua a configuração TLS e redirecione o HTTP para HTTPS antes de convidar os usuários a fazerem login.

Lista de verificação final para implantação

• O nome de host do Element Web resolve para o servidor Nginx e possui um certificado HTTPS válido.
• O diretório raiz do documento contém o arquivo .htaccess da versão index.html, seus recursos e um arquivo .htaccess válido config.json.
• O JSON m.homeserver.base_urlaponta para a API do cliente HTTPS acessível para o seu servidor doméstico Matrix.
• sudo nginx -tO Nginx serve tanto a página inicial quanto a página config.jsonvia HTTPS.
• O navegador consegue fazer login e enviar uma solicitação real ao servidor doméstico sem erros de certificado, CORS ou arquivos ausentes.
• Suas regras de cache permitem que novos arquivos e configurações do cliente entrem em vigor após uma atualização.

Após a aprovação nessas verificações, o cliente Element Web personalizado estará sendo servido pelo Nginx e poderá se comunicar com o servidor Matrix. Mantenha o Element Web atualizado, guarde uma cópia de segurança da versão e configuração anteriores e verifique novamente o URL do servidor e as solicitações de rede do navegador após cada atualização.

Referências oficiais

• Documentação de instalação do Element Web
• Guia de configuração do Element Web
• Orientações sobre hospedagem web, cabeçalho de segurança e cache da Element
• Documentação de URIs bem conhecidas do cliente Synapse
• Diretrizes de segurança do Synapse
• Documentação do módulo principal do Nginx