Deploy no Dokploy

O arquivo docker-compose.dokploy.yml sobe o sistema inteiro num projeto do Dokploy. O Traefik do Dokploy cuida do DNS e do certificado HTTPS: o compose não tem labels de roteamento, os domínios são cadastrados na interface.

A API e o executor usam a mesma imagem (docker/Dockerfile.api). O executor só começa depois que as migrations terminam; painel e docs, depois que a API responde. crawlers-docs é a mesma imagem do painel com CRAWLERS_UI_MODO=docs: serve só /documentacao e manda qualquer outra rota para lá.

Pré-requisitos no servidor

• Rede postgres-internal com o Postgres (o compose a usa como externa) e um banco vazio para o sistema; as migrations criam o resto.
• Um bucket no MinIO acessível do servidor (opcional, mas recomendado: sem ele os PDFs ficam só no volume jobs).
• DNS dos domínios do painel e da documentação apontando para o servidor do Dokploy.

1. Criar o serviço

1. No projeto do Dokploy: Create Service → Compose.
2. Provider: o repositório Git, branch main.
3. Compose Path: ./docker-compose.dokploy.yml.

2. Variáveis (aba Environment)

O Dokploy grava o conteúdo da aba como .env ao lado do compose. Use o .env.example como inventário. O mínimo:

DATABASE_URL=postgresql://crawlers_usr:SENHA@infra-postgres:5432/crawlers_db?sslmode=disable
CREDENCIAIS_CHAVE_MESTRA=            # uv run python -m core.contas chave
CONTAS_UI_URL=https://painel.seudominio
DOCS_URL=https://docs.seudominio
MINIO_ENDPOINT=https://minio.seudominio
MINIO_ACCESS_KEY=
MINIO_SECRET_KEY=
JOBS_BUCKET=crawlers-jobs
JOBS_CONCORRENCIA=2

• CREDENCIAIS_CHAVE_MESTRA abre o cofre dos certificados. Gere uma só vez, guarde uma cópia fora do servidor e nunca troque sem a rotação (docs/contas-e-cofre.md): sem ela, as credenciais guardadas se perdem.
• DOCKER=true e JOBS_RUNNER_NA_API=0 já vêm do compose e da imagem; não precisa defini-las.
• DOCS_URL faz o /documentacao do painel redirecionar para o domínio das docs; CONTAS_UI_URL é o destino do botão "Abrir o painel" nas docs. Não use o domínio do painel em DOCS_URL (o redirecionamento entraria em loop).
• API_HOST, UI_HOST e DOCS_HOST não são usados aqui (são do docker-compose.api.yml, que usa labels próprias do Traefik).

3. Domínios (aba Domains)

O painel já atende a API em https://painel.seudominio/api/... (e as docs, em https://docs.seudominio/api/...); o domínio próprio da API só é necessário se algum integrador precisar dele. O CONTAS_UI_URL deve ser o domínio do painel (é o endereço dos links de convite).

4. Deploy e primeiro acesso

1. Deploy. Acompanhe os logs de crawlers-migrar (deve terminar com código 0) e de crawlers-api.

2. Crie o administrador inicial pelo terminal do container crawlers-api (o do Dokploy ou docker exec -it <container> bash); a senha é pedida sem eco:

   python -m core.contas admin admin@seudominio "Seu Nome"
   

3. Entre em https://painel.seudominio, crie as API keys e convide os usuários. A documentação fica em https://docs.seudominio (a raiz leva a /documentacao).

Operação

• Escalar a fila: aumente JOBS_CONCORRENCIA (cada navegador consome de 300 a 500 MB) ou suba outro executor em outra máquina apontando para o mesmo banco (python -m core.jobs, ver docs/servico-fila.md).
• Tribunais que exigem navegador visível (TJRN, TRF3, TJPB): o executor do container não tem tela e responde bloqueado. Para eles, rode um executor numa máquina com sessão gráfica, com JOBS_TAREFAS=processos.*.
• Volumes: jobs (artefatos dos jobs, compartilhado por API e executor), cache e logs. Com MinIO configurado, os artefatos também ficam no bucket e a API os busca de lá se o arquivo local sumir.
• Atualizar: um novo deploy refaz as imagens e roda as migrations antes de subir a API e o executor. Jobs em andamento voltam para a fila quando o executor é reiniciado (lease expirado).