Como instalar o servidor Synapse Matrix com o Docker Compose

Exemplo ilustrativo: Imagine um pequeno grupo de voluntários que deseja seu próprio servidor Matrix em chat.example.com. Esta é uma configuração hipotética, não um relato de um servidor que foi testado. Os mesmos passos podem ser adaptados a um domínio real, mas escolha o nome do servidor Matrix com cuidado: o Synapse o utiliza nos IDs de usuário e ele não poderá ser alterado posteriormente.

Este guia cria um serviço Synapse e um banco de dados PostgreSQL com o Docker Compose. A imagem oficial do Docker do Synapse inicia com o SQLite por padrão, o que é conveniente para um teste rápido; a documentação do Docker do Synapse recomenda o PostgreSQL para produção. Portanto, o exemplo gera primeiro a configuração do Synapse, altera suas configurações de banco de dados para PostgreSQL e, em seguida, inicia ambos os contêineres. A imagem oficial é [imagem oficial] ghcr.io/element-hq/synapse. As instruções e os detalhes da imagem foram verificados com a documentação oficial atual em 6 de outubro de 2026; as tags da imagem e as versões de software suportadas podem mudar, portanto, revise a documentação vinculada antes de uma implantação de longa duração.

O que você precisa antes da instalação

• Um servidor Linux ou outro host compatível com Docker, com o Docker Engine e o plugin Docker Compose instalados. Confirme se o Compose está disponível com `docker-compose up` docker compose version. Siga as instruções oficiais de instalação do Docker para o seu sistema operacional.
• Um domínio ou subdomínio que aponta para o servidor. Neste exemplo, ` chat.example.com<synapse-server>` é o nome do servidor Synapse, portanto, os IDs de usuário locais terão a aparência de `<synapse-server>` @alex:chat.example.com. Substitua-o por um domínio que você controla antes de gerar a configuração.
• Um proxy reverso ou outro método de terminação TLS para uso público. O listener HTTP padrão do Synapse na porta 8008não é um endpoint HTTPS voltado para a Internet. Este exemplo do Compose vincula essa porta à interface de loopback do host para que um proxy reverso na mesma máquina possa acessá-la.

O nome em `in` SYNAPSE_SERVER_NAMEnão é necessariamente a URL de todas as conexões de clientes. Se você deseja IDs mais curtos, como `<nome_do_domínio>`, @alex:example.comao atender clientes a partir de ` chat.example.com<endereço_do_domínio>`, isso requer uma configuração de domínio e descoberta deliberada. Decida isso antes de criar as contas.

1. Crie um diretório de trabalho e uma senha para o banco de dados.

No servidor, crie um diretório para o projeto Compose e para os arquivos persistentes do Synapse:

mkdir -p ~/matrix-synapse/data
cd ~/matrix-synapse

Crie um arquivo local .envque o Docker Compose possa ler. Gere uma senha longa e aleatória usando um gerenciador de senhas ou um gerador local seguro e coloque-a após ` POSTGRES_PASSWORD=. Use letras e números neste exemplo para evitar problemas de aspas no YAML posteriormente. Não envie este arquivo para um repositório público e restrinja suas permissões:

umask 077
nano .env

O arquivo deve conter uma linha, por exemplo POSTGRES_PASSWORD=replace-with-a-long-random-value. O texto é um marcador de posição, não uma senha para reutilizar. Mantenha a senha disponível para a configuração do banco de dados Synapse na etapa 3.

2. Defina os serviços Synapse e PostgreSQL.

Criar compose.yamlno diretório do projeto:

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

  synapse:
    image: ghcr.io/element-hq/synapse:latest
    restart: unless-stopped
    depends_on:
      postgres:
        condition: service_healthy
    environment:
      SYNAPSE_SERVER_NAME: chat.example.com
      SYNAPSE_REPORT_STATS: "no"
    volumes:
      - ./data:/data
    ports:
      - "127.0.0.1:8008:8008"

volumes:
  postgres_data:

Substitua chat.example.compelo nome final do servidor que você escolheu. A verificação de integridade do PostgreSQL permite que o Compose aguarde até que o banco de dados reporte estar pronto antes de iniciar o Synapse. O volume de banco de dados nomeado e o ./datadiretório montado no host permanecem após a substituição do contêiner; remover os contêineres por si só não os apaga. Evite essa opção, docker compose down -va menos que você queira excluir o volume do banco de dados intencionalmente.

O exemplo visa :latestsimplificar o primeiro pull. Para um servidor com manutenção, selecione e registre uma tag de versão específica do Synapse ou um resumo da imagem e, em seguida, atualize-a por meio de um processo de atualização planejado após revisar as notas de versão. Não presuma que a latesttag mutável manterá a mesma versão.

3. Gere a configuração do Synapse e aponte-a para o PostgreSQL.

Execute a imagem oficial uma vez no modo de geração de configuração. Como o Compose monta ./dataem /data, a configuração gerada e a chave de assinatura permanecem no host:

docker compose run --rm synapse generate

Este comando utiliza o nome do servidor e a opção de estatísticas anônimas do ambiente Compose. O Synapse também cria uma chave de assinatura; mantenha-a no diretório de dados e inclua-a em backups protegidos. Não a regenere nem a descarte durante uma atualização normal do contêiner.

Abra data/homeserver.yamle substitua a database:seção gerada pelas seguintes configurações. Use a senha exata .envno lugar do marcador de posição:

database:
  name: psycopg2
  args:
    user: synapse
    password: 'replace-with-the-same-random-value'
    dbname: synapse
    host: postgres
    port: 5432
    cp_min: 5
    cp_max: 10

Mantenha a indentação YAML ao redor e certifique-se de que haja apenas uma database:seção ativa. O nome do host postgresé o nome do serviço Compose, que os contêineres podem resolver em sua rede padrão compartilhada. A configuração usa o nome do mecanismo PostgreSQL documentado pelo Synapse, psycopg2, e nomes de argumentos de banco de dados, incluindo dbname.

Neste pequeno exemplo, a senha do banco de dados aparece tanto na configuração do Synapse quanto no .envarquivo protegido. Trate ambos os arquivos como segredos, limite o acesso do host e utilize uma abordagem dedicada para gerenciamento de segredos, caso seu ambiente de implantação exija. Não cole a senha real em logs, capturas de tela ou solicitações de suporte.

4. Inicie o Synapse com o Docker Compose.

Inicie a pilha em segundo plano:

docker compose up -d

Verifique o estado do serviço e leia os registros de inicialização:

docker compose ps
docker compose logs --tail=100 synapse

Aguarde até que o Synapse conclua a configuração inicial do banco de dados. Um contêiner em execução significa apenas que seu processo está ativo; verifique os logs em busca de erros de configuração, banco de dados ou permissões antes de prosseguir. Para acompanhar os logs à medida que chegam, use a tecla Ctrl docker compose logs -f synapsee pressione Enter Ctrl+Cpara interromper o acompanhamento sem interromper o contêiner.

5. Verifique a API local e configure o acesso público.

A partir do host Docker, solicite o endpoint de versões da API do cliente Synapse:

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

Uma resposta bem-sucedida é um JSON que descreve as versões da API do cliente Matrix compatíveis. Isso confirma que o listener HTTP está respondendo localmente; não comprova que o DNS, HTTPS ou a federação estejam configurados corretamente.

Configure o proxy reverso do host para encaminhar as solicitações do domínio escolhido http://127.0.0.1:8008e obter um certificado TLS válido. Preserve o caminho da solicitação do Matrix ao usar o proxy. Em seguida, verifique o endpoint público:

curl -fsS https://chat.example.com/_matrix/client/versions

Substitua o nome de host de exemplo pelo seu nome real. Se os clientes precisarem descobrir o servidor doméstico a partir de um domínio de ID de usuário separado, publique os registros de descoberta conhecidos do Matrix apropriados para esse projeto. A federação também requer roteamento público e DNS corretos; abrir 8008apenas a porta local não garante uma implantação pública completa. Consulte as diretrizes de proxy reverso e federação do Synapse antes de expor o serviço.

6. Crie a primeira conta de administrador.

Por padrão, o Synapse desativa o registro público. Para um servidor privado, mantenha essa configuração padrão e crie contas pela linha de comando. Adicione temporariamente um registration_shared_secretvalor forte ao parâmetro data/homeserver.yaml`--username`, e reinicie o Synapse para que a alteração seja aplicada.

docker compose restart synapse

Execute a ferramenta de registro dentro do contêiner. Ela solicitará um nome de usuário e uma senha; essa configuração --admincria o primeiro administrador:

docker compose exec synapse register_new_matrix_user \
  http://localhost:8008 \
  -c /data/homeserver.yaml \
  --admin

Após a criação da conta, remova-a registration_shared_secretda configuração e reinicie o Synapse. Deixar a chave secreta configurada permite que qualquer pessoa que a obtenha registre contas padrão ou de administrador por meio da interface de registro. Faça login por meio de um cliente Matrix que suporte servidores domésticos personalizados, usando a URL do servidor fornecida pelo seu proxy reverso.

Cópias de segurança, atualizações e correções comuns

• Faça backup dos dados corretos: pare o servidor ou crie snapshots regulares dos dados do PostgreSQL e faça backup de todos eles ./data, incluindo configuração, mídia e chave de assinatura. Uma cópia compose.yamlsozinha não é suficiente para restaurar o servidor doméstico. Armazene os backups em um local separado do servidor e verifique periodicamente se você consegue lê-los.
• O Synapse não consegue gravar em /data: verifique a propriedade e as permissões do host em ./data. O usuário de tempo de execução da imagem oficial precisa de permissão para ler a configuração e gravar dados. Ajuste a propriedade do host com cuidado, em vez de tornar o diretório gravável por todos.
• Falha na conexão com o banco de dados: verifique se a configuração do banco de dados está correta host: postgres, se a senha corresponde .enve se docker compose logs postgreso banco de dados está íntegro. A condição de prontidão do Compose depends_onreduz as condições de corrida na inicialização, mas não corrige credenciais incorretas.
• A API local funciona, mas os clientes não conseguem se conectar: ​​verifique o registro DNS, o certificado TLS, o proxy reverso upstream e os registros de descoberta para o domínio escolhido. O mapeamento de porta somente para loopback é intencional para um proxy no mesmo host; um proxy em outro contêiner precisa de uma rede Docker compartilhada e um roteamento diferente.
• Atualização: faça um backup primeiro, revise as notas de versão do Synapse, atualize a tag da imagem fixada e recrie o serviço com `synapse docker compose pullupdate` seguido de docker compose up -d`synapse update`. Mantenha o mesmo diretório de dados, volume do banco de dados, nome do servidor e chave de assinatura.

Na configuração ilustrativa de grupo de voluntários, a instalação só é concluída quando o endpoint das versões locais responde, o endpoint HTTPS responde através do proxy e o administrador consegue fazer login usando o domínio Matrix ID pretendido. Essas verificações são indicadores práticos de uma primeira implantação bem-sucedida; elas não substituem a revisão dos requisitos de segurança, backups, federação e operacionais antes de convidar uma comunidade mais ampla.

Referências oficiais

• Instruções de instalação do Synapse e orientações sobre o nome do servidor.
• README da imagem Docker oficial do Synapse
• Referência de configuração do Synapse
• orientação de proxy reverso Synapse
• Instalação do Docker Engine
• Ordem de inicialização e verificações de integridade do Docker Compose