Inicio
» Cómo
»
Implementar Matrix Synapse con Docker Compose y PostgreSQL
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.
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.
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.
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.
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.
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.
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.
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.
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.