Instalación y configuración de un

1. Qué estamos configurando y por qué: la filosofía de Matrix

Matrix no es solo otro mensajero, es un protocolo abierto para la comunicación descentralizada en tiempo real. A diferencia de los sistemas cerrados como Telegram, WhatsApp o Slack, Matrix permite que los usuarios de diferentes servidores se comuniquen entre sí con la misma facilidad con la que intercambiamos correos electrónicos. Este concepto se llama federación.

Synapse es la implementación más madura y popular de un servidor doméstico (homeserver) de Matrix, escrita en Python. Sirve como el nodo central que almacena el historial de mensajes, gestiona las cuentas de usuario y sincroniza los datos entre los clientes y otros servidores en la red.

¿Por qué elegir una solución autoalojada (self-hosted) en un VPS en lugar de usar servidores públicos como matrix.org?

• Privacidad: Los metadatos de sus conversaciones no salen de su servidor (si no utiliza la federación).
• Rendimiento: Los servidores públicos suelen estar sobrecargados, lo que provoca retrasos en la entrega de mensajes. Su propio VPS garantiza una respuesta instantánea.
• Flexibilidad: Usted decide qué volumen de archivos multimedia almacenar, qué puentes (bridges) instalar y a quién registrar en el servidor.

En esta guía, nos enfocamos en las versiones actuales de software de 2026, utilizando la contenerización, lo que hace que el proceso de instalación sea reproducible y limpio.

2. Qué configuración de VPS se necesita para esta tarea

Históricamente, Matrix Synapse se consideraba un servicio que consumía muchos recursos, especialmente en términos de memoria RAM. Sin embargo, con las optimizaciones de los últimos años y el uso de PostgreSQL, los requisitos se han vuelto más democráticos. No obstante, para el funcionamiento cómodo de un grupo de usuarios y el uso de puentes (por ejemplo, hacia WhatsApp o Telegram), no conviene escatimar en recursos.

Es importante tener en cuenta el tipo de subsistema de disco. Matrix trabaja intensamente con la base de datos al buscar y sincronizar salas, por lo que las unidades NVMe aumentan significativamente la capacidad de respuesta de la interfaz en el cliente Element. Para un funcionamiento estable y rápido del mensajero, puede alquilar un VPS con las características indicadas, lo que proporcionará el margen de rendimiento necesario para la base de datos PostgreSQL y el almacenamiento en caché de archivos multimedia.

¿Cuándo debería considerar un servidor dedicado? Si planea desplegar un mensajero corporativo para más de 100 empleados con almacenamiento de terabytes de archivos o si requiere el máximo aislamiento de recursos para garantizar la seguridad. Para la mayoría de las tareas privadas y pequeñas empresas, un VPS potente será más que suficiente.

Ubicación del servidor: Elija una ubicación lo más cercana posible a la masa principal de usuarios. Esto minimizará la latencia al establecer conexiones WebRTC durante las llamadas.

3. Preparación del servidor: seguridad y base

Antes de instalar Synapse, es necesario preparar el sistema operativo. Utilizaremos Ubuntu 24.04 LTS o 26.04 LTS, ya que tienen el mejor soporte para paquetes Docker y núcleos recientes.

En primer lugar, actualizaremos el sistema y crearemos un usuario limitado con privilegios sudo para no trabajar como root:

# Обновление индекса пакетов и системы
sudo apt update && sudo apt upgrade -y

# Создание пользователя (замените 'adminuser' на свое имя)
sudo adduser adminuser
sudo usermod -aG sudo adminuser

# Переключение на нового пользователя
su - adminuser

La configuración de un cortafuegos básico (UFW) es crítica. Matrix requiere la apertura de varios puertos:

• 80/TCP — para la verificación de Let's Encrypt (HTTP).
• 443/TCP — tráfico principal del cliente (HTTPS).
• 8448/TCP — federación (interacción entre servidores Matrix).
• 3478, 5349 (UDP/TCP) — para el funcionamiento de STUN/TURN (llamadas).

sudo ufw allow 22/tcp
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 8448/tcp
sudo ufw allow 3478/udp
sudo ufw enable

También se recomienda instalar Fail2Ban para proteger el SSH contra ataques de fuerza bruta:

sudo apt install fail2ban -y
sudo systemctl enable fail2ban
sudo systemctl start fail2ban

4. Instalación de Docker y utilidades auxiliares

En 2026, Docker es el estándar de facto para el despliegue de aplicaciones complejas. Esto aísla las dependencias de Synapse (que están ligadas a Python) de las bibliotecas del sistema y simplifica el proceso de actualización.

# Установка необходимых утилит
sudo apt install -y curl gnupg lsb-release

# Добавление официального репозитория Docker
sudo mkdir -p /etc/apt/keyrings
curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu $(lsb_release -cs) stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

# Установка Docker Engine и Docker Compose
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-compose-plugin

# Проверка установки
docker --version && docker compose version

Añada su usuario al grupo docker para ejecutar contenedores sin sudo:

sudo usermod -aG docker $USER
# Перелогиньтесь, чтобы изменения вступили в силу

5. Instalación paso a paso de Matrix Synapse

Utilizaremos una estructura de directorios en /opt/matrix para almacenar todas las configuraciones y datos. Esto simplifica la creación de copias de seguridad.

sudo mkdir -p /opt/matrix/synapse/data
sudo chown -R $USER:$USER /opt/matrix
cd /opt/matrix

Primero, necesitamos generar el archivo de configuración inicial. Para ello, utilizaremos la imagen oficial de Synapse:

docker run -it --rm \
    -v /opt/matrix/synapse/data:/data \
    -e SYNAPSE_SERVER_NAME=example.com \
    -e SYNAPSE_REPORT_STATS=yes \
    matrixdotorg/synapse:latest generate

Importante: Reemplace example.com con su dominio o subdominio real (por ejemplo, matrix.example.com). Este parámetro no se podrá cambiar fácilmente más adelante, ya que se convierte en parte de sus User ID (por ejemplo, @user:example.com).

Ahora crearemos el archivo docker-compose.yml en el directorio /opt/matrix, que unirá Synapse y la base de datos PostgreSQL:

cat < docker-compose.yml
services:
  db:
    image: postgres:16-alpine
    restart: always
    environment:
      POSTGRES_USER: synapse
      POSTGRES_PASSWORD: your_strong_password
      POSTGRES_DB: synapse
      POSTGRES_INITDB_ARGS: "--encoding=UTF-8 --lc-collate=C --lc-ctype=C"
    volumes:
      - ./postgresdata:/var/lib/postgresql/data

  synapse:
    image: matrixdotorg/synapse:latest
    restart: always
    depends_on:
      - db
    ports:
      - "8008:8008"
    volumes:
      - ./synapse/data:/data
    environment:
      - SYNAPSE_CONFIG_PATH=/data/homeserver.yaml
EOF

6. Configuración profunda: homeserver.yaml y PostgreSQL

6. Configuración profunda: homeserver.yaml y PostgreSQL

Por defecto, Synapse genera una configuración para SQLite, pero para producción en un VPS es obligatorio PostgreSQL. Editaremos /opt/matrix/synapse/data/homeserver.yaml.

Busque la sección database y reemplácela por la siguiente:

database:
  name: psycopg2
  args:
    user: synapse
    password: your_strong_password
    database: synapse
    host: db
    cp_min: 5
    cp_max: 10

Configuración del registro: Por defecto, el registro de nuevos usuarios está cerrado. Si desea crear la primera cuenta, actívelo temporalmente o use la línea de comandos. Por seguridad, es mejor dejar enable_registration: false y crear los usuarios manualmente.

Claves secretas: Asegúrese de que registration_shared_secret esté completado con una cadena aleatoria larga. Esto permitirá que las herramientas administrativas interactúen con la API.

Inicio del servidor:

docker compose up -d

Creación del primer usuario (administrador):

docker exec -it matrix-synapse-1 register_new_matrix_user \
    -c /data/homeserver.yaml http://localhost:8008

Siga las instrucciones: ingrese el nombre de usuario, la contraseña y responda "yes" a la pregunta sobre los derechos de administrador.

7. Configuración de TLS/HTTPS a través de Caddy y delegación de dominio

Los clientes de Matrix y otros servidores se comunican a través de HTTPS. Utilizaremos Caddy, ya que gestiona automáticamente los certificados y tiene una sintaxis extremadamente sencilla.

Añada Caddy a su docker-compose.yml:

  caddy:
    image: caddy:latest
    restart: always
    ports:
      - "80:80"
      - "443:443"
      - "8448:8448"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile
      - ./caddy_data:/data
      - ./caddy_config:/config

Cree el archivo Caddyfile en /opt/matrix:

example.com:443, example.com:8448 {
    reverse_proxy synapse:8008
    
    header {
        Access-Control-Allow-Origin *
        Access-Control-Allow-Methods "GET, POST, PUT, DELETE, OPTIONS"
        Access-Control-Allow-Headers "Origin, X-Requested-With, Content-Type, Accept, Authorization"
    }
}

Delegación (Well-known): Para que otros servidores puedan encontrar su servidor Matrix, es necesario configurar los archivos .well-known. Esto permite utilizar el dominio example.com, incluso si el propio Synapse se está ejecutando en el subdominio matrix.example.com.

Añada al Caddyfile un bloque para servir JSON:

example.com {
    handle_path /.well-known/matrix/server {
        header Content-Type application/json
        respond {"m.server": "example.com:443"}
    }
    handle_path /.well-known/matrix/client {
        header Content-Type application/json
        header Access-Control-Allow-Origin *
        respond {"m.homeserver": {"base_url": "https://example.com"}}
    }
}

8. Configuración de llamadas: instalación de Coturn (STUN/TURN)

Para que las llamadas de audio y video funcionen a través de Element (especialmente cuando los usuarios están detrás de un NAT), es necesario un servidor TURN. Instalaremos Coturn.

Añada el servicio al docker-compose.yml:

  coturn:
    image: coturn/coturn:latest
    restart: always
    net: host
    volumes:
      - ./coturn.conf:/etc/coturn/turnserver.conf

Ejemplo de un coturn.conf básico:

use-auth-secret
static-auth-secret=TU_SECRETO_MUY_FUERTE
realm=example.com
listening-port=3478
tls-listening-port=5349
min-port=49152
max-port=65535

En homeserver.yaml especifique los datos del servidor TURN:

turn_uris: ["turn:example.com:3478?transport=udp", "turn:example.com:3478?transport=tcp"]
turn_shared_secret: "TU_SECRETO_MUY_FUERTE"
turn_user_lifetime: 86400000

9. Copias de seguridad, actualización y mantenimiento

La administración de un servidor Matrix requiere atención regular a dos cosas: el tamaño de la base de datos y la actualización de las versiones del software.

Estrategia de copia de seguridad

Es necesario realizar copias de seguridad de tres componentes:

1. Base de datos: Volcado (dump) de PostgreSQL.
2. Archivos de configuración: homeserver.yaml, Caddyfile, claves de firma (signing keys).
3. Almacenamiento de medios: Carpeta media_store (la parte más voluminosa).

Ejemplo de un script de copia de seguridad sencillo (backup.sh):

#!/bin/bash
BACKUP_DIR="/opt/backups/$(date +%Y-%m-%d)"
mkdir -p $BACKUP_DIR

# Volcado de BD
docker exec matrix-db-1 pg_dump -U synapse synapse > $BACKUP_DIR/db.sql

# Copia de configuraciones
cp /opt/matrix/synapse/data/homeserver.yaml $BACKUP_DIR/
cp /opt/matrix/synapse/data/*.signing.key $BACKUP_DIR/

# Archivado (sin medios para ahorrar espacio, es mejor respaldarlos por separado con rsync)
tar -czf $BACKUP_DIR/configs.tar.gz -C /opt/matrix/synapse/data .

Limpieza de la caché de medios

Matrix almacena copias de todos los archivos multimedia de las salas federadas. Para evitar que el disco se llene, configure la limpieza automática en homeserver.yaml:

media_retention_rules:
  - type: remote
    max_lifetime: 30d

Actualización

La actualización se realiza cambiando la etiqueta de la imagen o simplemente reiniciando con latest:

docker compose pull
docker compose up -d

10. Solución de problemas + FAQ

Error: "Federation failed" al intentar entrar en salas públicas

Compruebe el puerto 8448. Debe estar abierto en UFW y redirigido en Caddy. Utilice el servicio Matrix Federation Tester para asegurarse de que su certificado sea válido y que los registros SRV o los archivos well-known estén configurados correctamente.

¿Por qué Synapse consume tanta RAM?

Synapse está escrito en Python y almacena muchos datos en caché en la memoria para acelerar el acceso. Si la memoria es escasa, asegúrese de estar utilizando PostgreSQL y de haber configurado los límites de caché en homeserver.yaml (parámetro caches.global_factor).

¿Qué configuración de VPS es la mínima adecuada?

Para un solo usuario, 2 GB de RAM y 1 vCPU son suficientes, pero el sistema funcionará lento al entrar en salas grandes (por ejemplo, Matrix HQ). Para un funcionamiento estable, recomendamos 4 GB de RAM.

¿Qué elegir: VPS o servidor dedicado para esta tarea?

Para un mensajero personal y comunidades pequeñas, un VPS es la elección ideal debido a su flexibilidad y la posibilidad de realizar copias de seguridad rápidas mediante instantáneas (snapshots). Un servidor dedicado solo es necesario en caso de volúmenes enormes de tráfico multimedia o requisitos específicos de seguridad de datos.

¿Cómo conectar Element X?

Element X requiere soporte para el protocolo Sliding Sync. En 2026, este ya viene integrado en Synapse, pero puede requerir una activación por separado en la configuración. Asegúrese de que su cliente sea compatible con la versión 1.4 o superior del protocolo Matrix.

¿Se puede migrar el servidor a otro dominio?

Prácticamente no. server_name está incrustado en el ID de todos los mensajes y salas en la base de datos. Cambiar el dominio equivale a crear un nuevo servidor desde cero.

Problema con el envío de notificaciones a dispositivos móviles

Matrix utiliza un Push Gateway. Para Element se utiliza el servidor push de matrix.org. Asegúrese de que su servidor tenga acceso a Internet y no bloquee las solicitudes salientes a los puertos 443.

11. Conclusiones y próximos pasos

¡Felicidades! Ha desplegado su propio servidor Matrix Synapse completo. Ahora cuenta con una plataforma de comunicación segura que no depende de las políticas de terceras empresas y ofrece un control total sobre la privacidad.

Como siguientes pasos, le recomendamos explorar:

• Instalación de puentes (Bridges): Conecte sus cuentas de Telegram, WhatsApp y Signal a Matrix a través de los puentes mautrix, para usar Element como un cliente único para todos los mensajeros.
• Integración con LDAP/OIDC: Si está configurando el servidor para una empresa, conecte su base de usuarios existente.
• Monitoreo: Instale el conjunto Prometheus + Grafana para realizar un seguimiento de la carga del servidor y el consumo de recursos de Synapse.

Matrix es una herramienta poderosa, y poseer su propio nodo en esta red lo convierte en parte del ecosistema global de comunicación libre.