Implante o Matrix Synapse com Docker Compose e PostgreSQL.

Execute o Synapse como um projeto Docker Compose com um diretório de configuração persistente e um banco de dados PostgreSQL. A configuração abaixo gera as chaves de assinatura do Synapse homeserver.yaml, conecta-o ao PostgreSQL e mantém o listener HTTP no localhost para que você possa colocar HTTPS e federação atrás de um proxy reverso antes de abrir o servidor para a internet.

O Synapse é o servidor doméstico do Matrix: ele armazena contas, salas, eventos e mídia para um servidor. O Docker Compose executa os contêineres do Synapse e do PostgreSQL a partir de um único arquivo YAML. Este é um ponto de partida para uma única máquina, não uma implantação pública completa do Matrix.

Antes de começar

Instale o Docker Engine e o plugin Docker Compose e confirme se tudo docker compose versionfunciona corretamente. O Docker Desktop inclui o Compose no Windows e no macOS; usuários de Linux podem instalar o plugin Compose a partir do repositório de pacotes do Docker. Consulte as instruções de instalação do Docker Compose .

Escolha o nome permanente do servidor Matrix antes de gerar a configuração. Ele aparece nos IDs de usuário, como `<username>` @alex:matrix.example.org, e alterá-lo posteriormente não é uma simples edição de nome de host. Neste exemplo, ` matrix.example.org<username>` é tanto o nome do servidor Matrix quanto o nome de host público. Para um servidor público, aponte o registro DNS para o seu host e planeje um proxy reverso HTTPS. O listener HTTP gerado pelo Synapse na porta 8008 é adequado para testes locais; a documentação de instalação indica que o uso prático requer HTTPS.

1. Crie um projeto e um segredo

No host Docker, crie um diretório de trabalho e as pastas persistentes. A synapsepasta `work` conterá a configuração gerada e a chave de assinatura; a pasta data/postgres`persistent` conterá os arquivos do banco de dados.

mkdir -p ~/matrix-synapse/synapse ~/matrix-synapse/data/postgres
cd ~/matrix-synapse
umask 077
openssl rand -hex 32

Copie a saída do comando para um novo .envarquivo com o nome DB_PASSWORD=.... Mantenha este arquivo privado e faça um backup seguro dele. O Compose lê .envas substituições no arquivo Compose; o Synapse não expande automaticamente essas variáveis ​​dentro de homeserver.yaml. Você deverá inserir a mesma senha nesse arquivo de configuração na etapa 3.

Visão ilustrativa do terminal de um diretório de projeto matrix-synapse contendo o arquivo docker-compose.yml, um arquivo de ambiente, uma pasta de configuração do Synapse e uma pasta de dados.
Uma pasta de projeto separa a definição do Compose, a configuração do Synapse e os arquivos de banco de dados persistentes.

2. Defina os dois serviços.

Crie docker-compose.ymlo arquivo no diretório do projeto. Este exemplo usa a imagem oficial do Synapse publicada pela Element HQ e o PostgreSQL 16. A porta do Synapse está vinculada ao loopback, em vez de a todas as interfaces de rede. A verificação de integridade ajuda o Compose a aguardar o PostgreSQL antes de iniciar o Synapse.

services:
  synapse:
    image: ghcr.io/element-hq/synapse:latest
    restart: unless-stopped
    environment:
      SYNAPSE_CONFIG_PATH: /data/homeserver.yaml
    volumes:
      - ./synapse:/data
    ports:
      - "127.0.0.1:8008:8008"
    depends_on:
      db:
        condition: service_healthy

  db:
    image: postgres:16-alpine
    restart: unless-stopped
    environment:
      POSTGRES_USER: synapse
      POSTGRES_PASSWORD: ${DB_PASSWORD}
      POSTGRES_DB: synapse
      POSTGRES_INITDB_ARGS: --encoding=UTF-8 --lc-collate=C --lc-ctype=C
    volumes:
      - ./data/postgres:/var/lib/postgresql/data
    healthcheck:
      test: ["CMD-SHELL", "pg_isready -U synapse -d synapse"]
      interval: 10s
      timeout: 5s
      retries: 5

Insira o valor aleatório DB_PASSWORD=your-generated-valueobtido .envna etapa 1. Não inclua este arquivo no controle de versão. Se você alterar a versão principal do PostgreSQL posteriormente, siga o procedimento de atualização do PostgreSQL em vez de simplesmente apontar uma imagem mais recente para um diretório de dados existente.

3. Gere a configuração do Synapse e selecione PostgreSQL.

Gere a configuração inicial e a chave de assinatura no synapsediretório montado. Use o mesmo nome de servidor que você escolheu acima. Defina a opção de estatísticas explicitamente; aqui está ela no.

docker compose run --rm --no-deps \
  -e SYNAPSE_SERVER_NAME=matrix.example.org \
  -e SYNAPSE_REPORT_STATS=no \
  synapse generate

O modo oficial do contêiner generatecria homeserver.yamla chave de assinatura necessária. Abra o arquivo synapse/homeserver.yamle substitua a seção do banco de dados SQLite pelo seguinte. Substitua ` PASTE_THE_SAME_DB_PASSWORD_HERE<valor>` pelo valor exato armazenado em ` .env<valor>`. Este campo é um valor de configuração literal do Synapse, não uma interpolação do Compose.

database:
  name: psycopg2
  args:
    user: synapse
    password: PASTE_THE_SAME_DB_PASSWORD_HERE
    dbname: synapse
    host: db
    port: 5432
    cp_min: 5
    cp_max: 10
Visualização ilustrativa do editor homeserver.yaml com PostgreSQL configurado através do psycopg2, banco de dados synapse, host db, porta 5432 e um pool de conexões.
A seção de banco de dados do Synapse aponta para o nome do serviço Compose, db, na porta interna do PostgreSQL.

Mantenha o registration_shared_secretID gerado em sigilo. O Synapse o utiliza para a ferramenta de registro de usuários via linha de comando; qualquer pessoa que o obtenha pode criar contas, incluindo administradores. Deixe o registro público desativado, a menos que você pretenda oferecê-lo deliberadamente e tenha revisado os controles de abuso associados.

4. Inicie o Synapse e examine os registros.

A partir do diretório que contém o arquivo docker-compose.yml, valide o arquivo Compose e inicie os serviços:

docker compose config
docker compose up -d
docker compose ps
docker compose logs --tail=100 synapse db

O primeiro comando verifica se o Compose consegue analisar o arquivo e resolvê-lo DB_PASSWORD. O próximo inicia o banco de dados e o servidor doméstico em segundo plano. Verifique os logs em busca de erros de conexão com o banco de dados ou de um arquivo de configuração ausente. Como essa configuração monta as pastas locais, a configuração do banco de dados e do Synapse persiste quando os contêineres são recriados.

Exemplo de prompt de terminal com o comando `docker compose up -d` inserido para iniciar o Synapse Stack.
Após gerar e revisar a configuração, inicie os serviços Synapse e PostgreSQL.

5. Verifique o endpoint local e crie uma conta.

Execute a solicitação de versões do cliente Matrix a partir do host Docker. Uma resposta JSON significa que a API do cliente está respondendo; uma resposta vazia, recusa de conexão ou erro HTTP significa que você deve inspecionar os logs do Synapse e confirmar se a porta 8008 está em escuta.

curl -fsS http://127.0.0.1:8008/_matrix/client/versions

Após a resposta, crie um usuário inicial interativamente. Este comando solicitará um nome de usuário e uma senha; escolha "não" para administrador, a menos que você precise especificamente de uma conta de administrador.

docker compose exec synapse register_new_matrix_user \
  -c /data/homeserver.yaml http://localhost:8008
Exemplo de prompt de terminal com uma solicitação curl para o endpoint de versões do cliente Matrix do Synapse no localhost, porta 8008.
Uma resposta bem-sucedida do endpoint de versões confirma que o Synapse está respondendo localmente; este exemplo de prompt mostra a verificação, não um resultado de teste.

Torne-o acessível com segurança.

O mapeamento de porta somente para localhost é intencional: ele impede o acesso público direto ao listener HTTP não criptografado. Para clientes remotos, configure um proxy reverso com um certificado TLS válido e encaminhe os caminhos do Matrix para o Synapse. O proxy deve repassar os cabeçalhos X-Forwarded-For`<nome_do_serviço>` e X-Forwarded-Proto`<nome_do_serviço>`; na configuração do listener gerada, habilite x_forwarded: truea porta 8008. Não configure um listener do Synapse em contêiner para se vincular somente a ` 127.0.0.1<nome_do_serviço>`, pois isso impede que um contêiner de proxy o alcance. Se o proxy reverso também estiver em contêiner, coloque-o junto com o Synapse em uma rede Docker compartilhada e configure o proxy para o nome do serviço `<nome_do_serviço>` synapse:8008.

A federação é independente da inicialização local. Outros servidores Matrix precisam descobrir e alcançar o seu servidor, geralmente na porta 8448 ou por meio de descoberta HTTPS delegada. O DNS, o roteamento do proxy reverso e quaisquer .well-knownregistros necessários devem corresponder ao nome do servidor escolhido. Siga a documentação e as orientações de instalação do proxy reverso do Synapse antes de anunciar um servidor doméstico público. Chamadas de voz e vídeo também precisam de um servidor TURN para conectividade de mídia confiável.

Se o Synapse não conseguir se conectar ao PostgreSQL, verifique se o nome do serviço Compose hostestá dbcorreto, se ambas as senhas correspondem exatamente e se o contêiner do banco de dados está íntegro. Se o endpoint não puder ser acessado, verifique docker compose psos logs do Synapse e se outro serviço já está usando a porta 8008 do host. Faça backup do diretório de dados do PostgreSQL, da configuração do Synapse e da chave de assinatura; a chave de assinatura é essencial para a identidade do servidor.

Para detalhes sobre a configuração do PostgreSQL, consulte o guia do PostgreSQL da Synapse . Para opções de contêiner e criação de usuários, utilize a documentação oficial do Docker da Synapse .

Deixar um comentário

Configure um alias personalizado para a sala Matrix em seu próprio domínio.

Atribua um endereço fácil de compartilhar a uma sala do Matrix em seu domínio usando o Element ou a API do Matrix, com verificações de permissões, nomenclatura Synapse e federação.

Configure o Coturn para chamadas de voz e vídeo confiáveis ​​no Remake Matrix.

Configure o coturn e o Synapse com credenciais TURN correspondentes, abra as portas de retransmissão necessárias e verifique se os clientes Matrix conseguem obter candidatos de retransmissão.

Implante o Matrix Synapse com Docker Compose e PostgreSQL.

Implante o Matrix Synapse com Docker Compose e PostgreSQL.

Configure um servidor doméstico Synapse persistente com Docker Compose, PostgreSQL, uma configuração privada e verificações antes de expô-lo via HTTPS.

Personalize o tema e a identidade visual do Element Web.

Defina um nome de marca, cores personalizadas e recursos de login para sua implementação do Element Web, entendendo quais partes permanecerão com a marca Element.

Aumente o limite de arquivos do Systemd do Synapse sem complicações.

Aumente o limite de arquivos do Systemd do Synapse sem complicações.

Diagnostique se o Synapse atingiu seu limite de arquivos abertos por processo, configure um comando systemd para o serviço ou worker correto e verifique o limite em tempo real.

O Element exibe a mensagem “Falha ao descriptografar”? Restaure a chave da sala perdida.

O Element exibe a mensagem “Falha ao descriptografar”? Restaure a chave da sala perdida.

Descubra se o erro está limitado a um navegador ou a um evento específico e, em seguida, use a chave de recuperação do Element ou um dispositivo confiável sem arriscar seu histórico criptografado restante.

Limpe mensagens e arquivos de mídia antigos do Synapse sem perder dados.

Utilize as APIs de limpeza de histórico e mídia do Synapse ou as configurações de retenção para remover dados obsoletos com segurança e, em seguida, verifique a conclusão e a recuperação do espaço em disco.

Crie um bot de eco do Matrix em Python com a biblioteca Simple-Matrix-Bot-Lib.

Crie um bot de eco do Matrix em Python com a biblioteca Simple-Matrix-Bot-Lib.

Instale a biblioteca atual, conecte uma conta Matrix dedicada e execute um pequeno bot !echo com gerenciamento de credenciais mais seguro e um teste claro.

Conecte o Matrix ao WhatsApp, Telegram e Discord com pontes separadas.

Conecte o Matrix ao WhatsApp, Telegram e Discord com pontes separadas.

Configure três bridges Mautrix com registros, logins e testes separados — e evite surpresas com a rede Docker, políticas de conta e sincronização.

Recupere espaço em disco do Synapse Media sem afetar os arquivos compartilhados.

Descubra o que está ocupando espaço no armazenamento do Synapse, defina um período seguro de retenção de mídia e limpe o cache remoto sem excluir arquivos diretamente do disco.