Implementar Matrix Synapse con Docker Compose y PostgreSQL

Ejecuta Synapse como un proyecto Docker Compose con un directorio de configuración persistente y una base de datos PostgreSQL. La configuración que se muestra a continuación genera las claves de firma de Synapse homeserver.yaml, lo conecta a PostgreSQL y mantiene el oyente HTTP en localhost para que puedas colocar HTTPS y la federación detrás de un proxy inverso antes de abrir el servidor a Internet.

Synapse es el servidor principal de Matrix: almacena cuentas, salas, eventos y contenido multimedia para un servidor. Docker Compose ejecuta los contenedores de Synapse y PostgreSQL desde un único archivo YAML. Este es un punto de partida para una sola máquina, no una implementación pública completa de Matrix.

Antes de empezar

Instala Docker Engine y el complemento Docker Compose, y luego verifica que docker compose versionfuncione. Docker Desktop incluye Compose en Windows y macOS; los usuarios de Linux pueden instalar el complemento Compose desde el repositorio de paquetes de Docker. Consulta las instrucciones de instalación de Docker Compose .

Elija el nombre permanente del servidor Matrix antes de generar la configuración. Aparece en los ID de usuario, como @alex:matrix.example.org, y cambiarlo posteriormente no es una edición rutinaria del nombre de host. En este ejemplo, matrix.example.orges tanto el nombre del servidor Matrix como el nombre de host público. Para un servidor público, apunte su registro DNS a su host y configure un proxy inverso HTTPS. El oyente HTTP generado por Synapse en el puerto 8008 es adecuado para pruebas locales; su documentación de instalación indica que para su uso práctico se requiere HTTPS.

1. Crea un proyecto y un secreto

En el host de Docker, cree un directorio de trabajo y las carpetas persistentes. La synapsecarpeta contendrá la configuración generada y la clave de firma; data/postgrescontendrá los archivos de la base de datos.

mkdir -p ~/matrix-synapse/synapse ~/matrix-synapse/data/postgres
cd ~/matrix-synapse
umask 077
openssl rand -hex 32

Copia la salida del comando en un nuevo .envarchivo llamado DB_PASSWORD=.... Mantén este archivo privado y haz una copia de seguridad segura. Compose lee .envlas sustituciones en el archivo Compose; Synapse no expande automáticamente esas variables dentro de homeserver.yaml. Ingresarás la misma contraseña en esa configuración en el paso 3.

Vista ilustrativa de la terminal de un directorio de proyecto matrix-synapse que contiene docker-compose.yml, un archivo de entorno, una carpeta de configuración de Synapse y una carpeta de datos.
Una carpeta de proyecto separa los archivos de definición de Compose, configuración de Synapse y base de datos persistente.

2. Defina los dos servicios

Crea el archivo docker-compose.ymlen el directorio del proyecto. Este ejemplo utiliza la imagen oficial de Synapse publicada por Element HQ y PostgreSQL 16. El puerto de Synapse está vinculado a la interfaz de bucle invertido en lugar de a todas las interfaces de red. La comprobación de estado ayuda a Compose a esperar a que PostgreSQL esté listo antes de iniciar Synapse.

services:
  synapse:
    image: ghcr.io/element-hq/synapse:latest
    restart: unless-stopped
    environment:
      SYNAPSE_CONFIG_PATH: /data/homeserver.yaml
    volumes:
      - ./synapse:/data
    ports:
      - "127.0.0.1:8008:8008"
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: synapse
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: synapse
      POSTGRES_INITDB_ARGS: --encoding=UTF-8 --lc-collate=C --lc-ctype=C
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U synapse -d synapse"]
      interval: 10s
      timeout: 5s
      retries: 5

Inserta DB_PASSWORD=your-generated-valueel .envarchivo, usando el valor aleatorio del paso 1. No lo incluyas en el control de versiones. Si posteriormente cambias la versión principal de PostgreSQL, sigue el procedimiento de actualización de PostgreSQL en lugar de simplemente apuntar una imagen más reciente a un directorio de datos existente.

3. Generar la configuración de Synapse y seleccionar PostgreSQL.

Genere la configuración inicial y la clave de firma en el synapsedirectorio montado. Utilice el mismo nombre de servidor que eligió anteriormente. Configure explícitamente la opción de estadísticas; aquí está no.

docker compose run --rm --no-deps \
  -e SYNAPSE_SERVER_NAME=matrix.example.org \
  -e SYNAPSE_REPORT_STATS=no \
  synapse generate

El modo del contenedor oficial generatecrea homeserver.yamly la clave de firma requerida. Abra synapse/homeserver.yamly reemplace su sección de base de datos SQLite con lo siguiente. Reemplace PASTE_THE_SAME_DB_PASSWORD_HEREcon el valor exacto almacenado en .env. Este campo es un valor de configuración literal de Synapse, no una interpolación de Compose.

database:
  name: psycopg2
  args:
    user: synapse
    password: PASTE_THE_SAME_DB_PASSWORD_HERE
    dbname: synapse
    host: db
    port: 5432
    cp_min: 5
    cp_max: 10
Vista ilustrativa del editor homeserver.yaml con PostgreSQL configurado a través de psycopg2, base de datos synapse, host db, puerto 5432 y un grupo de conexiones.
La sección de base de datos de Synapse apunta al nombre del servicio Compose, db, en el puerto interno de PostgreSQL.

Mantén la información generada registration_shared_secretprivada. Synapse la utiliza para la herramienta de registro de usuarios por línea de comandos; cualquiera que la obtenga puede crear cuentas, incluidos los administradores. Deja el registro público desactivado a menos que tengas la intención de ofrecerlo y hayas revisado los controles de abuso correspondientes.

4. Inicie Synapse e inspeccione los registros.

Desde el directorio que contiene docker-compose.yml, valide el archivo Compose e inicie los servicios:

docker compose config
docker compose up -d
docker compose ps
docker compose logs --tail=100 synapse db

El primer comando verifica que Compose pueda analizar el archivo y resolverlo DB_PASSWORD. El siguiente inicia la base de datos y el servidor principal en segundo plano. Revise los registros para detectar errores de conexión a la base de datos o la falta de un archivo de configuración. Dado que esta configuración monta las carpetas locales, la configuración de la base de datos y de Synapse se conserva al recrear los contenedores.

Ejemplo de la línea de comandos del terminal con el comando docker compose up -d introducido para iniciar la pila Synapse.
Inicie los servicios de Synapse y PostgreSQL después de generar y revisar la configuración.

5. Verifica el punto final local y crea una cuenta.

Ejecute la solicitud de versiones del cliente Matrix desde el host de Docker. Una respuesta JSON significa que la API del cliente está respondiendo; una respuesta vacía, un rechazo de conexión o un error HTTP indican que debe revisar los registros de Synapse y confirmar que el puerto 8008 está a la escucha.

curl -fsS http://127.0.0.1:8008/_matrix/client/versions

Una vez que responda, cree un usuario inicial de forma interactiva. Este comando le pedirá un nombre de usuario y una contraseña; seleccione "no" para administrador a menos que necesite específicamente una cuenta de administrador.

docker compose exec synapse register_new_matrix_user \
  -c /data/homeserver.yaml http://localhost:8008
Ejemplo de terminal con una solicitud curl al punto final de versiones del cliente Matrix de Synapse en el puerto 8008 de localhost.
Una respuesta exitosa del punto final de versiones confirma que Synapse está respondiendo localmente; este mensaje de ejemplo muestra la verificación, no el resultado de una prueba.

Hazlo accesible de forma segura.

El mapeo de puerto solo para localhost es intencional: evita el acceso público directo al oyente HTTP no cifrado. Para clientes remotos, configure un proxy inverso con un certificado TLS válido y reenvíe las rutas de Matrix a Synapse. El proxy debe pasar los encabezados X-Forwarded-Fory X-Forwarded-Proto; en la configuración del oyente generada, habilite x_forwarded: truepara el puerto 8008. No configure un oyente de Synapse en contenedor para que se enlace solo a 127.0.0.1, porque eso impide que un contenedor proxy lo alcance. Si el proxy inverso también está en contenedor, colóquelo junto con Synapse en una red Docker compartida y haga proxy al nombre del servicio synapse:8008.

La federación es independiente del inicio local. Otros servidores Matrix necesitan descubrir y acceder a su servidor, generalmente a través del puerto 8448 o mediante descubrimiento HTTPS delegado. El DNS, el enrutamiento del proxy inverso y cualquier registro necesario deben coincidir con el nombre del servidor elegido. Siga la documentación y las instrucciones de instalación del proxy inverso.well-known de Synapse antes de anunciar un servidor público. Las llamadas de voz y vídeo también requieren un servidor TURN para una conectividad multimedia fiable.

Si Synapse no puede conectarse a PostgreSQL, verifique que el nombre del servicio Compose hostsea dbcorrecto, que ambas contraseñas coincidan exactamente y que el contenedor de la base de datos esté en buen estado. Si no se puede acceder al punto final, revise docker compose pslos registros de Synapse y compruebe si otro servicio ya está utilizando el puerto 8008. Realice una copia de seguridad del directorio de datos de PostgreSQL, así como de la configuración de Synapse y la clave de firma; la clave de firma es esencial para la identidad del servidor.

Para obtener detalles sobre la configuración de PostgreSQL, consulte la guía de PostgreSQL de Synapse . Para conocer las opciones de contenedores y la creación de usuarios, utilice la documentación oficial de Synapse Docker .

Dejar un comentario

Configurar la función de devolución conjunta para llamadas de voz y vídeo fiables de Matrix.

Configure coturn y Synapse con las credenciales TURN correspondientes, abra los puertos de retransmisión necesarios y verifique que los clientes de Matrix puedan obtener candidatos de retransmisión.

Implementar Matrix Synapse con Docker Compose y PostgreSQL

Implementar Matrix Synapse con Docker Compose y PostgreSQL

Configura un servidor Synapse persistente con Docker Compose, PostgreSQL, una configuración privada y comprobaciones antes de exponerlo a través de HTTPS.

Personaliza el tema y la imagen de marca de Element Web.

Define un nombre de marca, colores personalizados y elementos de inicio de sesión para tu implementación de Element Web, teniendo en cuenta qué partes conservarán la marca Element.

Aumenta el límite de archivos de Systemd de Synapse sin tener que adivinar.

Aumenta el límite de archivos de Systemd de Synapse sin tener que adivinar.

Diagnostique si Synapse alcanzó su límite de archivos abiertos por proceso, configure un archivo de configuración de systemd para el servicio o trabajador adecuado y verifique el límite en tiempo real.

¿El elemento muestra "Error al descifrar"? Recupere la llave de la habitación que falta.

¿El elemento muestra "Error al descifrar"? Recupere la llave de la habitación que falta.

Averigua si el error se limita a un navegador o a un evento específico y, a continuación, utiliza la clave de recuperación de Element o un dispositivo de confianza sin poner en riesgo el historial cifrado restante.

Limpia los mensajes y archivos multimedia antiguos de Synapse sin perder datos.

Utilice las API de historial y eliminación de medios de Synapse o la configuración de retención para eliminar datos obsoletos de forma segura y, a continuación, verifique que el proceso se haya completado y que se haya recuperado el espacio en disco.

Crea un bot de eco de matriz en Python con Simple-Matrix-Bot-Lib.

Crea un bot de eco de matriz en Python con Simple-Matrix-Bot-Lib.

Instala la biblioteca actual, conecta una cuenta Matrix dedicada y ejecuta un pequeño bot !echo con un manejo de credenciales más seguro y una prueba clara.

Conecta Matrix con WhatsApp, Telegram y Discord mediante puentes separados.

Conecta Matrix con WhatsApp, Telegram y Discord mediante puentes separados.

Configure tres puentes mautrix con registros, inicios de sesión y pruebas independientes, y evite sorpresas con la red, la política de cuentas y la sincronización de Docker.

Recupera espacio en disco de Synapse Media sin dañar los archivos compartidos.

Descubre qué está llenando el almacenamiento de Synapse, configura la retención segura de medios y purga la caché remota sin eliminar archivos directamente del disco.

Desactivar usuarios inactivos de Matrix sin borrar el historial de la sala.

Desactivar usuarios inactivos de Matrix sin borrar el historial de la sala.

Revise la actividad del dispositivo, desactive las cuentas de Synapse inactivas confirmadas a través de la API de administración y descubra qué elimina realmente la opción de borrado.