Visão geral

A auto-hospedagem começa pela stack da aplicação. Faturamento, armazenamento, e-mail e analítica são decisões de infraestrutura adicionais, depois que essa stack estiver saudável.

Pilha mínima implantável

No momento o repositório não oferece uma implantação de produção com um único comando. Antes de seguir os guias de serviços opcionais, planeje e opere:

• PostgreSQL 17 com a extensão pgvector, migrações, backups e testes de restauração
• Redis para as filas, o cache e a coordenação em tempo real
• o serviço de API, o app web e os workers em segundo plano da mesma versão
• as URLs públicas de web, API e WebSocket, TLS, as origens permitidas e os segredos e URLs do Better Auth
• entrega de jobs compatível com QStash/Workflow e as respectivas chaves de assinatura
• uma chave de provedor de IA e uma política de modelos para os recursos de IA e de embeddings que você ativar: ou uma chave do Vercel AI Gateway (AI_GATEWAY_API_KEY, o padrão) ou uma do OpenRouter (OPENROUTER_API_KEY), escolhidas com AI_PROVIDER
• armazenamento e rotação de segredos, logs estruturados, verificações de saúde, alertas e reversão

O docker-compose.yml local é uma base de desenvolvimento para Postgres, Redis e GeoIP. Não é uma topologia de produção. Rode as migrações antes de servir uma nova versão e mantenha alinhados na mesma versão a API, a web, os workers, o schema e o que o SDK publicado espera.

Quando esse núcleo estiver rodando, resolva estas quatro responsabilidades:

O Fluxo espera:

• uma decisão clara sobre o modo de faturamento: deixar o Polar ativado ou desativar o faturamento e rodar com permissões auto-hospedadas ilimitadas
• armazenamento de objetos para os uploads e a leitura pública de arquivos
• infraestrutura de e-mail transacional capaz de enviar mensagens, receber respostas e reportar os eventos de ciclo de vida
• infraestrutura de analítica para as métricas da caixa de entrada e a presença ao vivo, ou a decisão explícita de desativar esses recursos de analítica gerenciada

Recomendamos o caminho da AWS para a instalação auto-hospedada oficial porque o repositório já traz módulos de Terraform para ela, mas a documentação desta seção é organizada por funções, não por fornecedores:

• Faturamento explica o interruptor POLAR_ENABLED, por que o Polar continua ativado por padrão e o que muda ao desativar o faturamento
• Armazenamento cobre os uploads, a leitura pública de arquivos e o caminho de configuração com o AWS S3
• Configuração de e-mail cobre o e-mail transacional, as respostas recebidas e como escolher entre Resend e SES
• Analítica cobre a analítica baseada no Tinybird, as variáveis de ambiente que ligam o Tinybird e o DataFast, e o que acontece ao desativá-la

Responsabilidade do faturamento

O Fluxo tem dois modos de faturamento válidos ao auto-hospedar:

• deixar o Polar ativado e preservar o comportamento de assinatura e de medição de IA do produto hospedado
• desativar o Polar e rodar em um modo auto-hospedado onde os fluxos de faturamento, a medição de créditos e os limites de plano são ignorados

O Polar vem ativado por padrão para que o repositório se comporte como o produto gerenciado, a menos que você o desative explicitamente.

Use o guia de faturamento para decidir qual modo você quer e configurar o POLAR_ENABLED.

Por que recomendamos o caminho da AWS

O repositório já traz módulos de Terraform para os dois serviços:

• infra/aws/s3-public-setup
• infra/aws/ses-email-setup

Isso importa porque o caminho da auto-hospedagem é concreto, não teórico. Você não começa do zero com um armazenamento ou um e-mail genéricos: segue uma infraestrutura que já bate com o que o app espera em execução.

Responsabilidade do armazenamento

O Fluxo precisa de um armazenamento de objetos onde a API possa gerar URLs de upload pré-assinadas e onde os arquivos enviados possam ser lidos de volta por URLs públicas estáveis.

Na prática, isso significa:

• a API assina os uploads
• o navegador envia direto para o armazenamento de objetos
• o app guarda e exibe as URLs públicas resultantes
• os arquivos enviados podem ser agrupados por organização, site e entidade

Use o guia de armazenamento para configurar isso.

Responsabilidade do e-mail

No e-mail, o Fluxo precisa de mais do que o simples envio de saída. O app também depende do roteamento das respostas e dos eventos de ciclo de vida.

Na prática, isso significa:

• o React Email gera o conteúdo do e-mail dentro do app
• o envio de saída é escolhido por EMAIL_TRANSPORT_PROVIDER
• os endereços de resposta apontam para um domínio de entrada controlado pelo Fluxo
• as respostas recebidas acabam voltando para a API como cargas de webhook normalizadas
• os eventos de retorno, reclamação e falha alimentam o estado de supressão

A boa notícia é que você pode escolher o transporte:

• resend é suportado e continua sendo o padrão
• ses é suportado e é o caminho nativo da AWS para a auto-hospedagem

Use o guia de configuração de e-mail para escolher o provedor e configurar o caminho completo de entrada e saída.

Responsabilidade da analítica

O Fluxo usa infraestrutura de analítica para duas áreas do produto:

• a analítica da caixa de entrada
• a presença de visitantes ao vivo e o enriquecimento de "visto pela última vez no app"

Para a auto-hospedagem você tem dois caminhos válidos:

• deixar o Tinybird ativado e apontar o app para a sua instalação do Tinybird
• desativar o Tinybird por completo e rodar sem a interface de analítica que depende dele

O app inclui ainda um script separado do DataFast para a nossa analítica web hospedada. Quem auto-hospeda pode desativá-lo de forma independente.

Use o guia de analítica para decidir como tratar o Tinybird e o DataFast no seu deploy.

Como as peças se encaixam

Em linhas gerais, um deploy auto-hospedado é assim:

1. Um navegador pede à API uma URL de upload pré-assinada.
2. A API assina um PUT para o S3 e devolve a URL de upload junto com a URL pública.
3. O navegador envia o arquivo direto para o S3 em vez de fazê-lo passar pela API.
4. O Fluxo envia o e-mail com templates do React Email e o provedor selecionado por EMAIL_TRANSPORT_PROVIDER.
5. Os novos endereços de resposta apontam para o domínio de entrada do provedor de e-mail ativo.
6. O Resend ou o SES devolvem à API as respostas recebidas e os eventos de ciclo de vida usando a ponte específica de cada provedor configurada no app.
7. A API transforma esses eventos em mensagens da linha do tempo, gatilhos de notificação e registros de retorno ou de reclamação.
8. O faturamento com Polar continua ativado por padrão, a menos que você o desative explicitamente com POLAR_ENABLED=false.
9. A analítica da caixa de entrada e a presença ao vivo baseadas no Tinybird ou são ativadas pela sua instalação de analítica ou são desativadas explicitamente por variáveis de ambiente.

Ordem de configuração recomendada

Para um primeiro deploy limpo:

1. Provisione o PostgreSQL com pgvector e o Redis, configure os segredos e as URLs públicas, rode as migrações e suba a API, o app web e os workers.
2. Verifique a autenticação, a saúde da API, a conectividade de WebSocket, os jobs em segundo plano e o backup e a restauração antes das integrações opcionais.
3. Leia Faturamento e decida se o Polar continua ativado.
4. Configure o armazenamento e verifique os uploads.
5. Configure o e-mail e teste tanto o envio quanto as respostas recebidas.
6. Configure os recursos do Tinybird do repositório ou desative explicitamente a analítica e o DataFast.
7. Ensaie uma atualização e uma reversão em homologação antes de receber tráfego de produção.

Se você faz um deploy auto-hospedado do zero e não pretende usar o Resend, pode ir direto para o SES assim que confirmar que o DNS, as identidades e os webhooks funcionam no seu ambiente.

Guias

• Armazenamento
• Faturamento
• Configuração de e-mail
• Analítica