Como configurar um servidor Matrix no Raspberry Pi 4 com o Conduit

Um Raspberry Pi 4 pode servir como um pequeno e prático servidor doméstico Matrix para uma residência, um grupo privado ou um laboratório, e o Conduit foi projetado com hardware leve em mente. O Matrix é um protocolo aberto para comunicação descentralizada: seus usuários se conectam a um servidor doméstico , que armazena suas contas e dados de salas, enquanto a federação permite que esse servidor doméstico troque eventos com outros servidores Matrix.

Este guia utiliza o Conduit em um contêiner Docker, com o NGINX à frente para HTTPS. Isso mantém o serviço Matrix isolado no Raspberry Pi, expondo apenas as portas web públicas. As instruções foram verificadas com base na documentação do Conduit, Matrix, Raspberry Pi, Docker e NGINX disponível em outubro de 2026. Uma limitação importante: o Conduit ainda se descreve como beta , portanto, é mais adequado para usuários que aceitam que alguns recursos do Matrix e versões antigas do Room podem não funcionar exatamente como em uma implementação estável do Synapse. Consulte o projeto oficial do Conduit antes de usá-lo para um serviço crítico.

1. Compreenda a configuração antes de instalar qualquer coisa.

O processo final é simples: um cliente Matrix, como o Element, se conecta ao servidor https://matrix.example.com; o NGINX encerra a conexão TLS e encaminha a solicitação para o Conduit no Raspberry Pi; o Conduit armazena seu banco de dados em um armazenamento Docker persistente. Se a federação estiver habilitada, outros servidores domésticos acessam o mesmo endpoint HTTPS público.

Você precisará de um Raspberry Pi 4, uma fonte de alimentação confiável, um cartão microSD ou SSD e um sistema operacional de 64 bits. Um SSD é preferível para um servidor que você pretende manter por um longo período, pois o Matrix grava continuamente dados de banco de dados e mídia. Você também precisará de um nome de domínio caso o servidor precise ser acessível pela internet pública.

A partir de 15 de setembro de 2026, a versão atual do Raspberry Pi OS de 64 bits é baseada no Debian 13 “Trixie”, e o Raspberry Pi OS Lite está disponível para o Pi 4. Consulte a página oficial de downloads do Raspberry Pi OS . Para este servidor, a versão Lite é uma boa opção, pois dispensa um ambiente de desktop desnecessário.

Escolha o nome do servidor Matrix com cuidado.

Neste guia, o nome do servidor é matrix.example.com. Um ID de usuário Matrix resultante tem a seguinte aparência: @alice:matrix.example.com. Considere este nome como uma escolha de identidade a longo prazo. Os IDs Matrix e as referências de federação incluem o nome do servidor, portanto, alterá-lo posteriormente não é equivalente a simplesmente renomear um host web.

2. Instale o Raspberry Pi OS e atualize o Pi.

Grave o Raspberry Pi OS Lite de 64 bits no cartão ou SSD usando o Raspberry Pi Imager, habilite o SSH durante a gravação se desejar uma instalação sem monitor e inicialize o Raspberry Pi. Confirme se você está em um sistema ARM de 64 bits.

uname -m
cat /etc/os-release

uname -mDeveria normalmente reportar aarch64. Em seguida, instale as atualizações mais recentes:

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

3. Instale o Docker Engine e o Compose.

A documentação do Docker indica que usuários do Raspberry Pi OS de 64 bits devem usar os pacotes Debian ARM64 compatíveis, em vez do caminho mais antigo para Raspberry Pi OS de 32 bits. O procedimento oficial está na página do Docker Engine para Debian . A configuração do repositório a seguir segue essa abordagem:

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

Se o comando final imprimir a confirmação "hello-world" do Docker, o ambiente de execução do contêiner está funcionando. Você pode continuar usando-o sudo dockerpara o restante do guia. Adicionar sua conta ao dockergrupo é opcional, mas lembre-se de que a associação ao grupo do Docker concede, na prática, controle de nível root do host.

4. Criar uma configuração de Conduit

O Conduit pode ser configurado com um arquivo TOML ou variáveis ​​de ambiente. A referência oficial de configuração do Conduit lista `conduit_file` server_name, database_backend`conduit_file` e database_path`conduit_file_name` como campos obrigatórios e recomenda o uso do RocksDB.

Crie um diretório de trabalho:

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

Utilize esta configuração inicial e substitua o nome do host e o 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 que 0.0.0.0aqui? Dentro de um contêiner, o Conduit precisa escutar na interface do contêiner para que o Docker possa acessá-lo. A porta do lado do host continuará vinculada apenas à 127.0.0.1porta 6167, portanto, ela não será exposta diretamente à Internet.

5. Execute o Conduit com o Docker Compose.

Criar /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:

A imagem estável do GitLab Registry é a imagem recomendada pela documentação oficial do Conduit Docker . Evite copiar uma tag de imagem antiga de um tutorial aleatório; use o registro oficial e revise as notas de versão antes de atualizar.

Inicie o serviço e verifique-o:

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

Você deseja que o contêiner permaneça em Upestado de execução sem reinicializações repetidas. Antes de configurar o NGINX, verifique a API local:

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

6. Direcione o DNS para o Raspberry Pi e coloque o NGINX na frente do Conduit.

Crie um Aregistro matrix.example.comque aponte para o seu endereço IPv4 público. Se você publicar um AAAAregistro, certifique-se de que o IPv6 realmente chegue ao Raspberry Pi; um registro IPv6 corrompido pode fazer com que os clientes falhem mesmo quando o IPv4 estiver funcionando.

Em um roteador doméstico típico, encaminhe as portas TCP 80 e 443 para o Raspberry Pi. Se o seu provedor de internet utiliza NAT de nível de operadora (CGNAT), o encaminhamento de portas de entrada comum pode não funcionar; nesse caso, você precisará de um endereço IP público, um VPS/túnel reverso ou outra solução de hospedagem.

Instalar o NGINX:

sudo apt install -y nginx

Criar /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;
    }
}

Consulte os documentos oficiais do guia de proxy reverso do NGINX proxy_passe os cabeçalhos encaminhados usados ​​aqui.

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

7. Ative o HTTPS e a descoberta do Matrix.

O Matrix requer HTTPS válido para uma implantação pública normal. Obtenha um certificado somente depois que o DNS resolver para o Raspberry Pi e a porta 80 estiver acessível. O Debian Trixie fornece pacotes do Certbot, e o projeto Certbot também publica instruções específicas para cada plataforma em certbot.eff.org .

Uma abordagem comum em Debian/NGINX é:

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

Após o Certbot atualizar o host virtual do NGINX, teste a configuração novamente:

sudo nginx -t
sudo systemctl reload nginx

Como este guia usa o mesmo nome de host para o nome do servidor Matrix e o endpoint público, o Conduit pode responder aos /.well-knowncaminhos de descoberta do Matrix por meio do proxy reverso. A especificação do Matrix define esses endpoints para que clientes e outros servidores possam descobrir a URL correta do servidor principal. Consulte a especificação Cliente-Servidor do Matrix .

8. Crie a primeira conta e, em seguida, verifique o servidor.

A documentação do Docker da Conduit afirma que a primeira conta criada em um novo servidor doméstico se torna a administradora. Abra um cliente Matrix que suporte tokens de registro, escolha um servidor doméstico personalizado e digite:

https://matrix.example.com

Registre a primeira conta usando o token fornecido conduit.toml. Faça isso logo após colocar o serviço online. Se não desejar mais registros, edite a configuração para definir allow_registration = falsee reinicie o contêiner.

cd /opt/conduit
sudo docker compose restart conduit

Agora execute três verificações a partir de qualquer máquina que consiga acessar o domínio:

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

A primeira requisição deve retornar um JSON descrevendo as versões da API do cliente Matrix suportadas. As requisições subsequentes devem retornar informações de descoberta em JSON válidas. Para federação, utilize também o Matrix Federation Tester e tente entrar em uma sala federada a partir da nova conta.

Erros comuns que impedem o funcionamento de um servidor Raspberry Pi Matrix

• Usar um sistema operacional de 32 bits desnecessariamente: para um Raspberry Pi 4, use o Raspberry Pi OS de 64 bits e os pacotes Debian ARM64 compatíveis com o Docker.
• Expondo o Conduit diretamente: mantenha a porta 6167 vinculada 127.0.0.1ao host e exponha o HTTPS através do NGINX.
• Deixar o cadastro aberto sem proteção: use um token de cadastro forte durante a configuração inicial e, em seguida, desative o cadastro se não precisar mais dele.
• Publicação de DNS incorreto: ambos os registros IPv4 e IPv6 devem apontar para um endpoint funcional se você publicar ambos.
• Esquecer as regras do roteador ou do firewall: um contêiner correto não pode compensar o bloqueio de portas TCP 80/443 de entrada.
• Considerando que mensagens e chamadas de voz sejam iguais: o sistema de mensagens Matrix pode funcionar mesmo se as chamadas falharem. A documentação do Conduit afirma que a comunicação de voz precisa de um servidor TURN, como o Coturn.
• Ignorando backups: As perguntas frequentes do Conduit recomendam interromper o Conduit antes de fazer uma cópia normal do banco de dados no sistema de arquivos, a menos que você use um snapshot adequado do sistema de arquivos. Faça backup do volume do Docker e da sua configuração antes de atualizações.

Como é uma instalação bem-sucedida?

O teste estará concluído quando todas as seguintes condições forem atendidas: o contêiner Conduit permanecer em execução após uma reinicialização; https://matrix.example.com/_matrix/client/versionsretornar JSON; um cliente Matrix puder se registrar ou fazer login no seu servidor doméstico personalizado; a conta puder criar uma sala e enviar uma mensagem; e, se a federação estiver habilitada, o testador de federação puder acessar o servidor e o usuário puder se comunicar com contas em outro servidor doméstico.

Para uma pequena implementação com Raspberry Pi, esta é uma configuração básica e eficiente, e não o fim da administração. Monitore o espaço de armazenamento livre, mantenha o sistema operacional do Raspberry Pi e o Docker atualizados, faça backup do banco de dados e leia a documentação oficial do Conduit antes de habilitar recursos adicionais. O Conduit continua sendo uma opção leve e atraente para hardware do tipo Raspberry Pi, mas seu status beta é uma consideração operacional real, e não apenas um detalhe.