Chat propio con Matrix: Synapse + Element en Docker con HTTPS propio

1. Introduccion

Matrix es un protocolo abierto y descentralizado de mensajeria en tiempo real. Synapse es la implementacion de referencia del homeserver (el servidor que aloja las cuentas, las salas y los mensajes), y Element es el cliente mas usado para hablar con el. Esta guia levanta Synapse, su base de datos PostgreSQL, Element Web y un proxy inverso Nginx con Docker, todo autoalojado, sin federar con el resto de la red Matrix y sin depender de ningun proveedor externo.

2. Variables de esta guia

Todos los bloques de configuracion usan los siguientes marcadores en MAYUSCULAS. Sustituyelos por los valores reales del entorno donde se aplique esta guia.

3. Arquitectura y flujo

Todo el trafico del navegador pasa por un unico punto de entrada, el proxy inverso, que reparte segun la ruta: la interfaz de Element por un lado, la API de Synapse por otro, ambas bajo el mismo origen HTTPS — asi no hay ni contenido mixto ni problemas de CORS entre las dos piezas.

[Windows / cualquier navegador o Element Desktop]
      |
      |  https://IP_HOST_DOCKER:8443  (certificado autofirmado)
      v
[proxy] :8443 (Nginx, proxy inverso HTTPS)
      |         \
      |          \ /_matrix/*, /_synapse/*
      v            v
[element] :80   [synapse] :8008
                     |
                     v
               [synapse-db]  (PostgreSQL)

4. Requisitos

• Un host Linux con Docker Engine y el plugin Docker Compose (docker compose, sin guion) ya instalados.
• No hace falta salida a Internet desde ese host: todo el flujo de login vive dentro de la red local, sin necesidad de contactar servidores externos.
• Un navegador cualquiera (Chrome, Firefox, Edge...) en cualquier equipo de la misma red, o la app Element Desktop si se prefiere esa via (seccion 11).

5. Levantar Postgres, Synapse y Element con Docker

Misma organizacion de siempre: cada stack en su carpeta dentro de /docker, credenciales en un .env aparte.

sudo mkdir -p /docker/synapse && cd /docker/synapse
sudo mkdir -p synapse-data

sudo nano .env

POSTGRES_USER=synapse
POSTGRES_PASSWORD=synapse_pwd
POSTGRES_DB=synapse

Ahora crea el archivo de Element:

sudo nano element-config.json

{
  "default_server_config": {
    "m.homeserver": {
      "base_url": "https://IP_HOST_DOCKER:8443",
      "server_name": "SERVER_NAME_MATRIX"
    }
  },
  "brand": "Clockwork Computer Chat"
}

Y ahora el docker-compose.yml:

sudo nano docker-compose.yml

services:
  synapse-db:
    image: postgres:16-alpine
    container_name: synapse-db
    environment:
      POSTGRES_USER: ${POSTGRES_USER}
      POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
      POSTGRES_DB: ${POSTGRES_DB}
      POSTGRES_INITDB_ARGS: "--encoding=UTF8 --locale=C"
    volumes:
      - synapse-db-data:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U $$POSTGRES_USER -d $$POSTGRES_DB"]
      interval: 5s
      timeout: 5s
      retries: 20
      start_period: 20s
    restart: unless-stopped

  synapse:
    image: matrixdotorg/synapse:latest
    container_name: synapse
    volumes:
      - ./synapse-data:/data
    ports:
      - "8008:8008"
    depends_on:
      synapse-db:
        condition: service_healthy
    restart: unless-stopped

  element:
    image: vectorim/element-web:latest
    container_name: element
    volumes:
      - ./element-config.json:/app/config.json:ro
    depends_on:
      - synapse
    restart: unless-stopped

  proxy:
    image: nginx:alpine
    container_name: proxy
    volumes:
      - ./nginx.conf:/etc/nginx/conf.d/default.conf:ro
      - ./proxy-selfsigned.crt:/etc/nginx/certs/proxy-selfsigned.crt:ro
      - ./proxy-selfsigned.key:/etc/nginx/certs/proxy-selfsigned.key:ro
    ports:
      - "8443:8443"
    depends_on:
      - synapse
      - element
    restart: unless-stopped

volumes:
  synapse-db-data:

6. Generar la configuracion de Synapse

Synapse necesita un homeserver.yaml antes de arrancar de verdad. Se genera con un comando de un solo uso, usando el propio servicio ya definido en el docker-compose.yml:

cd /docker/synapse
docker compose run --rm -e SYNAPSE_SERVER_NAME=SERVER_NAME_MATRIX -e SYNAPSE_REPORT_STATS=no synapse generate

Esto crea ./synapse-data/homeserver.yaml y una clave de firma, ya con un registration_shared_secret aleatorio incluido — no hay que generarlo ni copiarlo a mano, el comando de alta de usuarios del paso 9 lo lee directamente del propio archivo.

Edita el archivo generado:

sudo nano ./synapse-data/homeserver.yaml

Busca el bloque database: (por defecto viene configurado para SQLite) y sustituyelo entero por este, apuntando a Postgres:

database:
  name: psycopg2
  args:
    user: synapse
    password: synapse_pwd
    database: synapse
    host: synapse-db
    port: 5432
    cp_min: 5
    cp_max: 10

7. Configurar el proxy inverso con HTTPS propio

Primero, genera un certificado autofirmado con clave EC (curva eliptica), valido para la IP del host Docker:

cd /docker/synapse
sudo openssl ecparam -name prime256v1 -genkey -noout -out proxy-selfsigned.key
sudo openssl req -new -x509 -key proxy-selfsigned.key -out proxy-selfsigned.crt -days 825 \
  -subj "/CN=IP_HOST_DOCKER" \
  -addext "subjectAltName=IP:IP_HOST_DOCKER"

Ahora crea la configuracion de Nginx:

sudo nano nginx.conf

resolver 127.0.0.11 valid=10s;

server {
    listen 8443 ssl;
    server_name IP_HOST_DOCKER;

    ssl_certificate     /etc/nginx/certs/proxy-selfsigned.crt;
    ssl_certificate_key /etc/nginx/certs/proxy-selfsigned.key;

    location ~ ^/(_matrix|_synapse) {
        set $upstream_synapse http://synapse:8008;
        proxy_pass $upstream_synapse;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
    }

    location / {
        set $upstream_element http://element:80;
        proxy_pass $upstream_element;
        proxy_set_header Host $host;
        proxy_set_header X-Forwarded-For $remote_addr;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

8. Arrancar el stack y verificar Synapse

cd /docker/synapse
docker compose up -d
docker compose ps

Sigue el log del homeserver:

docker logs -f synapse

Busca una linea similar a "Synapse now listening on TCP port 8008", sin errores de collation ni excepciones de Python por el camino. Sal con Ctrl+C.

Comprueba tambien que el proxy responde correctamente antes de pasar al navegador:

curl -kv https://IP_HOST_DOCKER:8443/_matrix/client/versions

9. Crear los usuarios

Las cuentas en Synapse se crean con un comando de administracion, ejecutado dentro del propio contenedor:

docker exec -it synapse register_new_matrix_user \
  http://localhost:8008 \
  -c /data/homeserver.yaml \
  -u USUARIO_MATRIX \
  -p PASSWORD_MATRIX \
  -a

El flag -a marca la cuenta como administradora del homeserver.

Para crear una segunda cuenta (por ejemplo, una que no sea administradora), se repite el mismo comando cambiando el usuario y la contraseña, sustituyendo -a por --no-admin:

docker exec -it synapse register_new_matrix_user \
  http://localhost:8008 \
  -c /data/homeserver.yaml \
  -u USUARIO2_MATRIX \
  -p PASSWORD2_MATRIX \
  --no-admin

10. Acceder desde el navegador

Abre cualquier navegador y entra en:

https://IP_HOST_DOCKER:8443

11. Alternativa: Element Desktop

Si se prefiere no lidiar con el aviso de certificado, tambien se puede instalar Element Desktop (element.io/download) y conectarla directamente al puerto de Synapse sin pasar por el proxy, ya que al ser una aplicacion nativa no esta sujeta al requisito de contexto seguro del navegador:

http://IP_HOST_DOCKER:8008

Ambas vias llevan al mismo homeserver y a las mismas cuentas; son formas distintas de conectarse, no montajes separados.

12. Tabla de puertos y componentes

13. Errores comunes y como resolverlos

14. Notas de ampliacion

El montaje de esta guia cubre lo minimo necesario para tener un chat propio funcionando con cuentas locales, cifrado con HTTPS y acceso directo por IP. Para un entorno de uso continuado, conviene ampliar con:

• Importar el certificado en el almacen de confianza de cada equipo cliente (Windows, Mac, Linux), para que el aviso de "certificado no confiable" desaparezca de forma permanente en esos equipos, sin tener que aceptarlo cada vez.
• Dominio propio + Let's Encrypt en vez de certificado autofirmado, necesario si en algun momento se quiere activar la federacion con otros homeservers Matrix, que exige un certificado valido reconocido publicamente.
• Apps moviles (Element para Android e iOS), que pueden apuntar al mismo homeserver desde fuera de la red local una vez este detras de un dominio con HTTPS valido.
• Puentes (bridges) hacia otras plataformas como Slack, Discord o Telegram, para centralizar conversaciones de varias herramientas en el mismo cliente.
• Copias de seguridad del volumen de PostgreSQL y de la carpeta synapse-data (incluye las claves de firma del servidor, necesarias para que el homeserver mantenga su identidad).