Pular para conteúdo

Fase 5 — PowerSync: compose, volumes e operação segura

Status: Aprovado · Responsável: Gustavo Madruga · Atualizado em: 2026-07-06

Objetivo: documentar o stack PowerSync self-hosted (Docker Compose no servidor) de forma operacional: o que cada volume guarda, como reiniciar sem perder dados, e por que docker compose down -v é um anti-padrão em produção.

Este passo é independente da Fase 4 — Coolify / integrador: o integrador (Micronaut) deploya por subdomínio e porta 8080; o PowerSync é um projeto Compose por cliente (esta pasta no Git = um deploy), tipicamente exposto em HTTPS como ps.<cliente>.xadm.biz (ou sufixo DNS equivalente), com MongoDB dedicado ao bucket daquele cliente.

Modelo: um docker-compose por cliente

Cada cliente tem a sua pasta com dois ficheiros versionáveis em conjunto:

Pasta no repo Conteúdo
powersync/sulplata/ docker-compose.yaml + config.yaml
powersync/onpetrotrading/ idem
powersync/vantroba/ idem
powersync/onpetro/ idem

No Compose, o serviço PowerSync chama-se sempre powersync e o Mongo mongo (hostname interno estável). O config.yaml usa mongodb://mongo:27017/....

Fluxo Git: alterar config.yaml (sync rules, etc.) ou o próprio Compose → commit → push → deploy no servidor (pull ou cópia da pasta) → docker compose up -d ou docker compose restart powersync dentro dessa pasta.

Domínio HTTPS (proxy)

O contrato público é o host, não a porta no edge:

Cliente (prod/) Subdomínio PowerSync sugerido
sulplata ps.sulplata.xadm.biz
onpetrotrading ps.onpetrotrading.xadm.biz
vantroba ps.vantroba.xadm.biz
onpetro ps.onpetro.xadm.biz

O proxy (Traefik / Caddy / Coolify) termina TLS e encaminha para o container PowerSync na porta interna 8080. O docker-compose.yaml publica 8080:8080. Se várias stacks partilharem o mesmo host Docker e precisarem de portas TCP distintas no host, ajusta manualmente o mapeamento no Compose desse cliente (ou usa um override Compose local não versionado).

Credenciais no config.yaml

No repositório, a URI Postgres usa placeholders (REPLACE_USER, REPLACE_PASSWORD, REPLACE_HOST, REPLACE_PORT, REPLACE_DATABASE). No servidor, preenche com valores reais (ou gere o ficheiro por secret store) e não commits com segredos. O JWKS em modelo aponta para https://auth.xadm.biz/.well-known/jwks.json — confirma o path com o teu serviço de auth.

Volumes nomeados (MongoDB) — o que não se apaga à toa

Em cada pasta de cliente, o Compose declara um volume mongo_storage (nome lógico; no Docker fica prefixado com o nome do projeto Compose, por pasta).

Apagar esse volume (down -v) remove o estado do bucket PowerSync naquele cliente → possível resync completo e impacto em apps/Postgres.

Bind mount (config.yaml)

  • Montagem: ./config.yaml:/config/config.yaml:ro (relativo à pasta do cliente).
  • Alterar sync rules: editar config.yaml no repo, deploy, depois docker compose restart powersync nessa pasta (Mongo pode ficar de pé).

Restart seguro (recomendado)

  1. Só mudou config.yaml: docker compose restart powersync (na pasta do cliente).
  2. Mudou docker-compose.yaml: docker compose up -d ou up -d --force-recreate conforme necessidade.
  3. Imagens: docker compose pull + docker compose up -d — sem -v salvo intenção explícita.
  4. Diagnóstico: docker compose ps, docker compose logs -f powersync.

Guia rápido: docs/servidor/update-syncrules.md.

Anti-padrão: docker compose down -v

Comando Efeito típico
docker compose down Para containers e rede; mantém volumes (dados Mongo persistem).
docker compose down -v Remove volumes declarados → apaga dados do Mongo do PowerSync nessa stack.

Em produção: evitar -v sem plano de resync/backup.

Auth (JWT / JWKS)

O integrador não expõe JWKS para o PowerSync. Ajustar client_auth.jwks_uri no config.yaml — ver pabast-removal-phase1.md.

Referências