Cómo alojar un cliente web de elementos personalizados en Nginx

Si puede acceder a su servidor Matrix pero no desea que los usuarios dependan del sitio web público de Element, puede alojar Element Web como un sitio estático en su propio servidor Nginx. Los archivos se sirven mediante Nginx; el servidor Matrix permanece como un servicio independiente que gestiona las cuentas, las salas, los mensajes y la federación. Esta distinción es importante: configurar el cliente web para que apunte a Synapse no instala ni configura Synapse.

Este tutorial para principiantes utiliza chat.example.orgpara el sitio Element y matrix.example.orgpara el servidor doméstico. Reemplace ambos con sus nombres de host reales. Los comandos asumen un servidor Linux de estilo Debian o Ubuntu; las rutas de los paquetes y los nombres de los servicios varían según la distribución.

Lo que necesitas antes de empezar

Tenga listos estos elementos antes de modificar los archivos del servidor:

• Un dominio o subdominio para el cliente web, con DNS que apunte al host Nginx.
• Un servidor doméstico Matrix en funcionamiento accesible mediante una URL HTTPS, como por ejemplo https://matrix.example.org.
• Nginx está instalado, con permiso para editar la configuración del sitio y recargar el servicio.
• Se requiere un certificado TLS válido para el nombre de host del cliente web. Los usuarios deben iniciar sesión mediante HTTPS, ya que su navegador envía las credenciales y los tokens de sesión al sitio.
• Archivo de la versión estable actual de Element Web del proyecto oficial. Evite implementar una versión de desarrollo en un servicio público a menos que tenga la intención específica de ejecutar software de desarrollo.

Element Web es una aplicación de navegador compuesta por archivos estáticos. Las instrucciones de instalación actuales del proyecto recomiendan descargar una versión, descomprimirla en el servidor, configurar el servidor web para que apunte a los archivos resultantes y realizar la configuración config.json. En Debian y Ubuntu, el proyecto también documenta un paquete de Element Web que instala su directorio raíz web en /usr/share/element-weby su configuración en /etc/element-web/config.json. Los pasos que se describen a continuación utilizan el archivo de la versión para que pueda elegir un directorio raíz de documentos específico.

Antes de seleccionar una versión , revise las instrucciones de instalación y las versiones oficiales de Element Web . Si utiliza el paquete Debian, configure Nginx para que apunte al directorio raíz web documentado del paquete y edite el archivo de configuración; no copie las rutas de archivo que aparecen a continuación sin modificarlas.

1. Descarga e instala los archivos de Element Web.

El directorio raíz es el directorio que Nginx sirve cuando un visitante accede a tu sitio web. Crea un directorio raíz dedicado y descomprime la versión allí. Sustituye los nombres de archivo y directorio que descargaste; las versiones cambian con el tiempo.

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

El archivo normalmente se descomprime en un directorio versionado. Copie el contenido de ese directorio, incluidos index.htmllos paquetes JavaScript, las fuentes, las imágenes y la configuración de ejemplo, en la raíz del documento de Nginx. Por ejemplo, si el directorio extraído se llama 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

Utilice el nombre real del directorio versionado en el comando de copia. Nginx necesita acceso de lectura a estos archivos, no de escritura. Conserve una copia de la versión y la configuración actuales antes de las actualizaciones para poder restaurarlas en caso de que falle la implementación.

2. Configure el cliente para que utilice su servidor doméstico.

Element necesita una dirección de servidor principal antes de poder iniciarse. Copie el archivo de ejemplo y configure la URL de la API del cliente Matrix predeterminada. En este ejemplo, Synapse es accesible en https://matrix.example.org:

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

Edítalo /var/www/element/config.jsony asegúrate de que contenga un objeto JSON válido con una default_server_configentrada, por ejemplo:

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

Esto establece el servidor que Element ofrece por defecto. No crea una cuenta de Synapse ni obliga a todos los usuarios a seleccionar este servidor. La guía de configuración actual de Element documenta esta opción default_server_configcomo la forma preferida de proporcionar la información de conexión al servidor principal. La opción anterior default_hs_urlestá obsoleta. Si desea restringir a los usuarios a un solo servidor, Element documenta una disable_custom_urlsconfiguración independiente; decida si es apropiada para su comunidad antes de habilitarla.

También puedes configurar una personalización limitada, como un tema predeterminado o ciertos detalles de marca, mediante las opciones documentadas de Element. Esto no equivale a una sustitución completa de marca blanca: el proyecto documenta la configuración de personalización seleccionada, en lugar de un cambio de marca sin restricciones. Consulta la guía de configuración para ver las opciones compatibles con la versión exacta que instales; no copies la configuración de una versión diferente sin antes verificarla.

Consulte la referencia de configuración actual de Element Web . La developdocumentación puede cambiar a medida que el proyecto evoluciona, así que confirme cualquier clave opcional con la versión que implemente.

3. Agregue un sitio Nginx para el cliente web.

Cree una configuración de sitio para el nombre de host de su cliente. Este ejemplo asume que ya dispone de un certificado chat.example.orgen las rutas indicadas. La emisión del certificado no se incluye, ya que el método adecuado depende de su host, proveedor de DNS y configuración 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;
    }
}

Coloca el bloque en el archivo de sitio apropiado para tu distribución, habilita ese sitio si es necesario y verifica que la configuración global de Nginx cargue el mime.typesarchivo estándar. Nginx utiliza tipos MIME para indicar a los navegadores si una respuesta es JavaScript, CSS, JSON u otro tipo de archivo. rootDebe apuntar al directorio que contiene directamente index.html.

El encabezado sin caché anterior es una configuración básica sencilla y fácil de implementar: los navegadores revalidan los archivos después de una actualización en lugar de seguir usando código de cliente obsoleto. Las notas de alojamiento de Element requieren específicamente que /config.*.json, /i18n, /version, y /index.htmlno se almacenen en caché, y recomiendan la revalidación para la raíz del sitio. Si posteriormente agrega un almacenamiento en caché de mayor duración para recursos estáticos grandes, mantenga esas rutas actualizadas y verifique la nomenclatura de los recursos de la versión antes de crear reglas de caché.

El archivo README web de Element recomienda el uso de encabezados anti-framing y content-type para sitios autohospedados. Si ya ha configurado una Política de Seguridad de Contenido (CSP) en otro lugar, agréguela frame-ancestors 'self'a la política existente en lugar de enviar un segundo encabezado CSP. Una CSP restrictiva puede bloquear scripts de aplicación necesarios, por lo que no copie una política general sin probarla en el cliente implementado.

Lea los requisitos de alojamiento y almacenamiento en caché de Element Web y la documentación oficial del módulo principal de Nginx para conocer el comportamiento de root, try_files, y el manejo de archivos estáticos.

4. Validar la configuración y reiniciar Nginx.

Pruebe la configuración antes de aplicarla. Si Nginx informa de un error, mantenga el proceso actual en ejecución mientras corrige el archivo y la línea indicados; no recargue una configuración defectuosa.

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

La prueba debería indicar que la sintaxis es correcta y que la prueba de configuración se realizó correctamente. Las solicitudes HTTPS deberían llegar al host previsto y devolver una respuesta satisfactoria. Confirme también que el archivo de configuración sea un JSON válido.

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

Luego, ábrelo https://chat.example.orgen un navegador. Deberías ver la pantalla de inicio de sesión o de bienvenida de Element con tu servidor Matrix como predeterminado. Prueba con una cuenta de prueba, revisa las herramientas para desarrolladores del navegador para detectar solicitudes de red fallidas y confirma que el inicio de sesión, la carga de la lista de salas y el envío de mensajes funcionan correctamente. Que la página se cargue correctamente solo demuestra que Nginx atendió al cliente web; no demuestra que el servidor sea accesible ni que esté configurado correctamente.

5. Hacer que la detección del servidor doméstico funcione cuando sea necesario.

Si sus ID de Matrix usan un nombre de servidor como example.orgmientras que la API de Synapse está en matrix.example.org, los clientes de Matrix pueden usar una respuesta conocida del cliente en https://example.org/.well-known/matrix/clientpara descubrir la URL de la API. Este punto final de descubrimiento opcional pertenece al dominio en el ID de Matrix, no automáticamente al nombre de host del cliente web de Element. Una respuesta mínima se ve así:

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

Sírvelo como JSON con los encabezados CORS necesarios para los clientes basados ​​en navegador. La documentación de instalación de Synapse proporciona un ejemplo con Nginx e indica que public_baseurldebe coincidir con la URL que los clientes usan para acceder a Synapse. Si la configuración de Element establece directamente la URL correcta del servidor principal y tus usuarios introducen esa configuración específica del cliente, es posible que no sea necesario el descubrimiento para esta configuración básica.

Siga las recomendaciones de Synapse para clientes conocidos y pruebe la URL final curlantes de esperar que funcione la detección de ID de usuario. Para garantizar el aislamiento de seguridad, las recomendaciones de seguridad de Synapse aconsejan alojar el servidor principal en un dominio registrado diferente al de las aplicaciones web sensibles, siempre que sea posible; los subdominios separados ofrecen cierta protección, pero un dominio registrado independiente es la recomendación más sólida.

Problemas comunes que se deben evitar

• Nginx muestra un error 403: compruebe los permisos de lectura de archivos y directorios y confirme que el proceso de Nginx puede recorrer cada directorio padre.
• La página aparece en blanco o devuelve un error 404 para JavaScript: asegúrese de que rootapunta al contenido del directorio de la versión extraída, no a un directorio superior o inferior. Revise los registros de errores y acceso de Nginx.
• El elemento se carga pero no puede conectarse ni iniciar sesión: verifique el certificado HTTPS del servidor principal, el acceso al firewall y cualquier configuración base_urlde config.jsonCORS o proxy inverso del lado de Synapse. Los navegadores aplican CORS; un sitio estático de Nginx no puede solucionar por sí solo la política de origen del servidor principal.
• Los cambios recientes no aparecen: compruebe los encabezados de caché para /, /index.html, /config.json, /version, y /i18n, y luego actualice el navegador después de confirmar que los archivos implementados fueron reemplazados.
• La página de inicio de sesión solo funciona con HTTP: finalice la configuración TLS y redirija HTTP a HTTPS antes de invitar a los usuarios a iniciar sesión.

Lista de verificación de despliegue final

• El nombre de host de Element Web se resuelve en el servidor Nginx y tiene un certificado HTTPS válido.
• La raíz del documento contiene los index.htmlrecursos de la versión y un archivo válido config.json.
• El JSON m.homeserver.base_urlapunta a la API de cliente HTTPS accesible para su servidor doméstico Matrix.
• sudo nginx -tpasan las pruebas y Nginx sirve tanto la página de inicio como config.jsona través de HTTPS.
• El navegador puede iniciar sesión y realizar una solicitud real al servidor de origen sin errores de certificado, CORS o archivos faltantes.
• Las reglas de caché permiten que los nuevos archivos de cliente y la configuración surtan efecto después de una actualización.

Una vez superadas estas comprobaciones, el cliente web personalizado de Element Web será servido por Nginx y podrá comunicarse con el servidor principal de Matrix. Mantenga Element Web actualizado, conserve una copia de la versión y configuración anteriores y vuelva a comprobar la URL del servidor principal y las solicitudes de red del navegador después de cada actualización.

Referencias oficiales

• Documentación de instalación de Element Web
• Guía de configuración de Element Web
• Guía de Element Web hosting, security-header y caching
• Documentación de URI conocidas del cliente Synapse
• Guía de seguridad de Synapse
• Documentación del módulo principal de Nginx