How to Set Up a Matrix Server on Raspberry Pi 4 with Conduit

A Raspberry Pi 4 can make a practical small Matrix homeserver for a household, private group, or lab, and Conduit is designed with lightweight hardware in mind. Matrix is an open protocol for decentralized communication: your users connect to a homeserver, which stores their accounts and room data, while federation lets that homeserver exchange events with other Matrix servers.

This guide uses Conduit in Docker, with NGINX in front of it for HTTPS. That keeps the Matrix service isolated on the Pi while exposing only the public web ports. The instructions were checked against the Conduit, Matrix, Raspberry Pi, Docker, and NGINX documentation available in October 2026. One important limitation comes first: Conduit still describes itself as beta, so it is best suited to users who accept that some Matrix features and older room versions may not work exactly as they do on a mature Synapse deployment. Check the official Conduit project before using it for a critical service.

1. Understand the setup before installing anything

The finished path is straightforward: a Matrix client such as Element connects to https://matrix.example.com; NGINX terminates TLS and forwards the request to Conduit on the Pi; Conduit stores its database in persistent Docker storage. If federation is enabled, other homeservers reach the same public HTTPS endpoint.

You will need a Raspberry Pi 4, a reliable power supply, a microSD card or SSD, and a 64-bit operating system. An SSD is preferable for a server you expect to keep for a long time because Matrix continuously writes database and media data. You will also need a domain name if the server must be reachable from the public Internet.

As of September 15, 2026, the current Raspberry Pi OS 64-bit release is based on Debian 13 “Trixie,” and Raspberry Pi OS Lite is available for the Pi 4. See the official Raspberry Pi OS download page. For this server, Lite is a good fit because it avoids an unnecessary desktop environment.

Choose the Matrix server name carefully

In this guide, the server name is matrix.example.com. A resulting Matrix user ID looks like @alice:matrix.example.com. Treat this name as a long-term identity choice. Matrix IDs and federation references include the server name, so changing it later is not equivalent to simply renaming a web host.

2. Install Raspberry Pi OS and update the Pi

Grabe Raspberry Pi OS Lite de 64 bits en la tarjeta o SSD con Raspberry Pi Imager, habilite SSH durante la creación de la imagen si desea una instalación sin interfaz gráfica y arranque la Pi. Confirme que está en un sistema ARM de 64 bits:

uname -m
cat /etc/os-release

uname -mNormalmente debería informar aarch64. Luego instale las actualizaciones actuales:

sudo apt update
sudo apt full-upgrade -y
sudo reboot

3. Instalar Docker Engine y Compose

La documentación de Docker indica que los usuarios de Raspberry Pi OS de 64 bits deben usar los paquetes Debian ARM64 compatibles en lugar de la ruta anterior de Raspberry Pi OS de 32 bits. El procedimiento oficial se encuentra en la página de Docker Engine para Debian . La siguiente configuración de repositorio sigue ese enfoque:

sudo apt update
sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
sudo curl -fsSL https://download.docker.com/linux/debian/gpg   -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc

echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/debian $(. /etc/os-release && echo "$VERSION_CODENAME") stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null

sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io   docker-buildx-plugin docker-compose-plugin

sudo docker run --rm hello-world

Si el comando final muestra la confirmación "hello-world" de Docker, el entorno de ejecución del contenedor está funcionando. Puede continuar usándolo sudo dockerpara el resto de la guía. Agregar su cuenta al dockergrupo es opcional, pero recuerde que pertenecer a un grupo de Docker otorga, en la práctica, control de nivel raíz del host.

4. Crear una configuración de conducto

Conduit se puede configurar con un archivo TOML o variables de entorno. La referencia de configuración oficial de Conduit enumera server_name, database_backend, y database_pathcomo campos obligatorios y recomienda RocksDB.

Cree un directorio de trabajo:

sudo mkdir -p /opt/conduit
sudo chown "$USER":"$USER" /opt/conduit
cd /opt/conduit
nano conduit.toml

Utilice esta configuración inicial y reemplace el nombre de host y el token de registro:

[global]
server_name = "matrix.example.com"
database_backend = "rocksdb"
database_path = "/var/lib/matrix-conduit/"
address = "0.0.0.0"
port = 6167

allow_registration = true
registration_token = "replace-with-a-long-random-secret"
allow_federation = true
trusted_servers = ["matrix.org"]

¿Por qué 0.0.0.0aquí? Dentro de un contenedor, Conduit debe escuchar en la interfaz del contenedor para que Docker pueda acceder a él. El puerto del lado del host seguirá vinculado solo a 127.0.0.1, por lo que el puerto 6167 no está expuesto directamente a Internet.

5. Ejecuta Conduit con Docker Compose

Crear /opt/conduit/docker-compose.yml:

services:
  conduit:
    image: registry.gitlab.com/famedly/conduit/matrix-conduit:latest
    container_name: matrix-conduit
    restart: unless-stopped
    ports:
      - "127.0.0.1:6167:6167"
    volumes:
      - ./conduit.toml:/etc/conduit.toml:ro
      - conduit-data:/var/lib/matrix-conduit/
    environment:
      CONDUIT_CONFIG: /etc/conduit.toml

volumes:
  conduit-data:

La imagen estable del registro de GitLab es la recomendada por la documentación oficial de Conduit Docker . Evite copiar una etiqueta de imagen antigua de un tutorial cualquiera; utilice el registro oficial y revise las notas de la versión antes de actualizar.

Inicie el servicio y compruébelo:

cd /opt/conduit
sudo docker compose pull
sudo docker compose up -d
sudo docker compose ps
sudo docker compose logs --tail=100 conduit

Desea que el contenedor permanezca en un Upestado de ejecución sin bucles de reinicio repetidos. Antes de configurar NGINX, verifique la API local:

curl http://127.0.0.1:6167/_matrix/client/versions

6. Apunta el DNS a la Raspberry Pi y coloca NGINX delante de Conduit.

Crea un Aregistro que matrix.example.comapunte a tu dirección IPv4 pública. Si publicas un AAAAregistro, asegúrate de que la IPv6 llegue correctamente a la Raspberry Pi; un registro IPv6 defectuoso puede provocar fallos en los clientes incluso cuando la IPv4 funciona.

En un router doméstico típico, redirija los puertos TCP 80 y 443 a la Raspberry Pi. Si su proveedor de servicios de Internet (ISP) utiliza NAT de nivel de operador (CGNAT), es posible que la redirección de puertos entrantes convencional no funcione; en ese caso, necesitará una dirección IP pública, un VPS/túnel inverso u otro tipo de alojamiento web.

Instalar NGINX:

sudo apt install -y nginx

Crear /etc/nginx/sites-available/matrix:

server {
    listen 80;
    server_name matrix.example.com;

    client_max_body_size 20M;

    location / {
        proxy_pass http://127.0.0.1:6167;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

La guía oficial de proxy inverso de NGINX documenta proxy_passlos encabezados reenviados que se utilizan aquí.

sudo ln -s /etc/nginx/sites-available/matrix /etc/nginx/sites-enabled/matrix
sudo nginx -t
sudo systemctl reload nginx

7. Habilitar HTTPS y descubrimiento de matriz

Matrix requiere HTTPS válido para una implementación pública normal. Obtenga un certificado solo después de que el DNS se resuelva a la Raspberry Pi y el puerto 80 sea accesible. Debian Trixie proporciona paquetes de Certbot, y el proyecto Certbot también publica instrucciones específicas para la plataforma en certbot.eff.org .

Una ruta común en Debian/NGINX es:

sudo apt install -y certbot python3-certbot-nginx
sudo certbot --nginx -d matrix.example.com

Después de que Certbot actualice el host virtual NGINX, vuelva a probar la configuración:

sudo nginx -t
sudo systemctl reload nginx

Dado que esta guía utiliza el mismo nombre de host para el servidor Matrix y el punto final público, Conduit puede responder a las /.well-knownrutas de descubrimiento de Matrix a través del proxy inverso. La especificación de Matrix define estos puntos finales para que los clientes y otros servidores puedan descubrir la URL correcta del servidor principal. Consulte la especificación Cliente-Servidor de Matrix .

8. Crea la primera cuenta y luego verifica el servidor.

La documentación de Docker de Conduit indica que la primera cuenta creada en un nuevo servidor principal se convierte en la de administrador. Abra un cliente Matrix que admita tokens de registro, elija un servidor principal personalizado e ingrese:

https://matrix.example.com

Registre la primera cuenta utilizando el token de conduit.toml. Hágalo poco después de poner el servicio en línea. Si no desea más registros, edite la configuración para establecer allow_registration = falsey reinicie el contenedor:

cd /opt/conduit
sudo docker compose restart conduit

Ahora, ejecute tres comprobaciones desde cualquier máquina que pueda acceder al dominio:

curl https://matrix.example.com/_matrix/client/versions

curl https://matrix.example.com/.well-known/matrix/client

curl https://matrix.example.com/.well-known/matrix/server

La primera solicitud debería devolver un JSON que describa las versiones compatibles de la API del cliente Matrix. Las solicitudes habituales deberían devolver información de descubrimiento en formato JSON válida. Para la federación, utilice también el Probador de federación de Matrix e intente unirse a una sala federada desde la nueva cuenta.

Errores comunes que impiden el funcionamiento de un servidor Raspberry Pi Matrix

• Evita usar un sistema operativo de 32 bits innecesariamente: para una Pi 4, usa Raspberry Pi OS de 64 bits y los paquetes Debian ARM64 compatibles con Docker.
• Exponer Conduit directamente: mantenga el puerto 6167 vinculado 127.0.0.1en el host y exponga HTTPS a través de NGINX.
• Dejar el registro abierto sin protección: utilice un token de registro seguro durante la configuración inicial y, si no lo necesita, desactive el registro.
• Publicar DNS incorrectos: si publica ambos, tanto los registros IPv4 como los IPv6 deben conducir a un punto final que funcione.
• Olvidar las reglas del enrutador o del cortafuegos: un contenedor correcto no puede compensar el bloqueo del tráfico TCP entrante en los puertos 80/443.
• Suponiendo que la mensajería y las llamadas de voz sean lo mismo: la mensajería Matrix puede funcionar aunque las llamadas fallen. La documentación de Conduit indica que la comunicación de voz requiere un servidor TURN como Coturn.
• Omitir copias de seguridad: Las preguntas frecuentes de Conduit recomiendan detener Conduit antes de realizar una copia normal del sistema de archivos de su base de datos, a menos que utilice una instantánea del sistema de archivos adecuada. Realice una copia de seguridad del volumen de Docker y de su configuración antes de las actualizaciones.

Así es como luce una instalación exitosa.

Habrás terminado cuando se cumplan todas estas condiciones: el contenedor Conduit siga funcionando después de un reinicio; https://matrix.example.com/_matrix/client/versionsdevuelva JSON; un cliente Matrix pueda registrarse o iniciar sesión en tu servidor doméstico personalizado; la cuenta pueda crear una sala y enviar un mensaje; y, si la federación está habilitada, el probador de federación pueda acceder al servidor y el usuario pueda comunicarse con cuentas en otro servidor doméstico.

Para una implementación pequeña de Raspberry Pi, esto representa una base limpia, no el fin de la administración. Supervise el almacenamiento disponible, mantenga actualizados Raspberry Pi OS y Docker, realice copias de seguridad de la base de datos y consulte la documentación oficial de Conduit antes de habilitar funciones adicionales. Conduit sigue siendo una opción ligera y atractiva para hardware de la clase Pi, pero su estado beta es una consideración operativa real, no una simple nota a pie de página.