Pular para o conteúdo principal

Auto-hospedagem no Railway

O ChurchApps publica um modelo de um clique para o Railway que dá à sua igreja uma instância privada do B1 Admin, do portal de membros B1, da API e de um banco de dados MySQL — tudo rodando em uma infraestrutura que você possui e paga diretamente. Este guia coloca tudo no ar em cerca de 15 minutos e depois percorre a configuração pós-implantação que a maioria das igrejas acaba querendo.

Início rápido​

Deploy on Railway

  1. Clique no botão Deploy on Railway acima.
  2. Entre no Railway (ou crie uma conta gratuita) e adicione uma forma de pagamento.
  3. Clique em Deploy sem alterar nada — cada variável tem um padrão sensato.
  4. Espere de 5 a 10 minutos até os quatro serviços ficarem verdes.
  5. Abra a URL do serviço B1Admin, clique em Registrar e crie sua conta. A primeira conta é automaticamente administradora do servidor.
  6. Siga as instruções no aplicativo para criar sua primeira igreja.

Pronto. Você já tem uma instância do ChurchApps totalmente funcional. Tudo abaixo é um acabamento opcional.

Dica

A implantação está atualmente em beta. Se você encontrar algo que a documentação não cobre, abra uma issue em github.com/ChurchApps/Api/issues com os logs de implantação anexados.

O que você precisa

  • Uma conta gratuita no Railway
  • Um cartão de crédito cadastrado no Railway (cerca de US$ 15–25/mês para uma congregação pequena; veja Custos)
  • Cerca de 15 minutos para a implantação inicial
  • Opcional, mas fortemente recomendado depois: credenciais SMTP e um domínio personalizado

O que é implantado​

O modelo provisiona quatro serviços em um único projeto do Railway:

ServiçoFinalidadeURL após a implantação
MySQLArmazena todos os dados (uma instância, vários esquemas)somente interna
ApiBackend de membership, conteúdo, doações, presença etc.https://api-<id>.up.railway.app
B1AdminAplicativo web da equipe/administraçãohttps://b1admin-<id>.up.railway.app
B1AppAplicativo web para membros e site da igrejahttps://b1app-<id>.up.railway.app

Os esquemas do banco de dados são criados automaticamente no primeiro start pela migração de inicialização da API.

Configuração inicial​

Agora que está no ar, estas são as coisas que a maioria das igrejas configura em seguida, mais ou menos por ordem de prioridade.

Sem e-mail, os membros ainda conseguem se cadastrar e usar o sistema, mas não conseguem redefinir uma senha esquecida — um administrador precisa fazer isso por eles. Configurar o SMTP leva cerca de 5 minutos.

No painel do Railway, abra o serviço Api → Variables e adicione:

MAIL_SYSTEM=SMTP
SMTP_HOST=<your provider host>
SMTP_USER=<your username>
SMTP_PASS=<your password or API key>
SMTP_SECURE=false
SUPPORT_EMAIL=noreply@yourchurch.org

Três provedores que vale conhecer:

Resend — opção gratuita mais simples (100 e-mails/dia)​

  1. Cadastre-se em resend.com.
  2. Verifique um domínio de envio (ou use o remetente de teste onboarding@resend.dev para começar).
  3. Crie uma chave de API.
  4. Defina SMTP_HOST=smtp.resend.com, SMTP_USER=resend, SMTP_PASS=re_xxxxxxxxx.

Gmail — gratuito para uso pessoal (~500/dia)​

  1. Ative a verificação em duas etapas na conta do Google.
  2. Crie uma Senha de app.
  3. Defina SMTP_HOST=smtp.gmail.com, SMTP_USER=seu-endereco@gmail.com, SMTP_PASS=<a senha de app de 16 caracteres>.

AWS SES — o mais barato em escala​

  1. Verifique um domínio de envio na AWS.
  2. Saia do sandbox do SES se for enviar para endereços não verificados.
  3. Crie credenciais SMTP em SES → SMTP Settings → Create credentials.
  4. Defina SMTP_HOST=email-smtp.us-east-2.amazonaws.com, SMTP_USER=AKIA..., SMTP_PASS=<senha SMTP do SES>.

Depois de salvar as variáveis, o serviço Api é reimplantado automaticamente. Teste disparando uma redefinição de senha em uma conta de teste.

Aviso

Se você definir MAIL_SYSTEM=SMTP com credenciais erradas, o cadastro vai parecer bem-sucedido, mas o e-mail de verificação nunca chega. Corrija as credenciais ou remova MAIL_SYSTEM para voltar ao modo sem e-mail.

2. Domínios personalizados​

As URLs padrão *.up.railway.app funcionam, mas a maioria das igrejas quer as suas próprias.

Para cada serviço web (B1Admin e B1App):

  1. Abra o serviço no Railway → Settings → Networking.
  2. Clique em + Custom Domain e informe o nome do host:
    • admin.suaigreja.org para o B1Admin
    • app.suaigreja.org (ou www) para o B1App
  3. Adicione o registro CNAME que o Railway mostrar ao seu provedor de DNS.
  4. Aguarde alguns minutos para a propagação do DNS. O Railway provisiona o certificado TLS automaticamente.

Depois, atualize as variáveis do serviço Api para que os links nos e-mails usem os novos domínios:

B1ADMIN_ROOT=https://admin.suaigreja.org

E no serviço B1Admin:

REACT_APP_API_BASE=https://api.suaigreja.org   (se você também definir um domínio de API personalizado)
REACT_APP_B1_WEBSITE_URL=https://{subdomain}.suaigreja.org

O token {subdomain} é literal — ele é substituído em tempo de execução pelo subdomínio de cada igreja (veja Multi-Site abaixo).

3. Multi-site (várias igrejas em uma instância)​

O ChurchApps é multi-inquilino por design — uma única implantação pode hospedar qualquer número de igrejas, cada uma com suas próprias pessoas, grupos e site. Novas igrejas são adicionadas inteiramente pela interface administrativa; não são necessárias mudanças de infraestrutura.

Adicionando igrejas extras​

  1. No B1 Admin, acesse Configurações → Gerenciar igreja → Trocar de igreja → Criar nova.
  2. Cada igreja tem um slug de subdomínio exclusivo (por exemplo, primeiraigreja, graca-comunidade).
  3. A nova igreja recebe seus próprios dados, membros, site e configuração de doações, totalmente isolados das outras igrejas da mesma instância.

Roteando cada igreja para a sua própria URL​

Duas formas de expor as igrejas publicamente:

PadrãoExemploConfiguração
Por caminho (funciona de imediato)app.suaigreja.org/primeiraigrejaNenhuma configuração extra
Por subdomínio (URLs mais limpas)primeiraigreja.suaigreja.orgDNS curinga + domínio personalizado curinga

Para o roteamento por subdomínio no Railway:

  1. No seu provedor de DNS, crie um CNAME curinga: *.suaigreja.org → <destino do railway do b1app>.
  2. No Railway, no serviço B1App → Settings → Networking, adicione *.suaigreja.org como domínio personalizado.
  3. No serviço B1Admin, defina REACT_APP_B1_WEBSITE_URL=https://{subdomain}.suaigreja.org.

Depois de reimplantar, o site de cada igreja fica disponível em <subdominio-da-igreja>.suaigreja.org automaticamente.

Info

Domínios personalizados curinga exigem um plano pago do Railway. O roteamento por caminho funciona em todos os planos e é funcionalmente idêntico — só menos bonito na barra de endereços.

4. Doações online (Stripe / PayPal)​

As doações são configuradas por igreja, dentro da interface administrativa, e não por variáveis de ambiente — assim cada igreja pode usar a sua própria conta de comerciante.

  1. Obtenha as credenciais de desenvolvedor no Stripe (Developers → API keys) ou no PayPal (My Apps & Credentials).
  2. No B1 Admin, acesse Configurações → Configurações de doações.
  3. Escolha o seu provedor, cole as chaves Pública e Secreta e configure o tratamento das taxas.
  4. Opcionalmente, adicione GOOGLE_RECAPTCHA_SECRET_KEY ao serviço Api no Railway para proteger os formulários públicos de doação contra robôs.

5. Armazenamento de arquivos​

O modelo provisiona um volume persistente de 1 GB montado no serviço Api para fotos de membros, arquivos de sermões e documentos enviados.

Para aumentá-lo: abra o serviço Api → Volumes → ajuste o controle deslizante de tamanho.

Para implantações maiores (100+ GB ou muitos envios simultâneos), troque para o S3 definindo estas variáveis no serviço Api:

FILE_STORE=S3
AWS_S3_BUCKET=<seu-bucket>
AWS_ACCESS_KEY_ID=<chave>
AWS_SECRET_ACCESS_KEY=<segredo>
AWS_REGION=us-east-2

Os arquivos já existentes no volume não migram automaticamente — copie-os para o bucket antes de trocar a variável.

6. Integrações opcionais de recursos​

Estas liberam recursos específicos e podem ser adicionadas depois pelo painel do Railway. Defina-as no serviço Api.

VariávelRecurso que habilita
OPENAI_API_KEY ou OPENROUTER_API_KEYBusca assistida por IA e sugestões de conteúdo
YOUTUBE_API_KEYBusca e incorporação de sermões do YouTube
PEXELS_KEYSeletor de imagens de banco de imagens para o criador de sites
VIMEO_TOKENSuporte a sermões do Vimeo
API_BIBLE_KEYConsultas de versículos bíblicos em lições e conteúdo
YOUVERSION_API_KEYIntegração com a Bíblia YouVersion
WEB_PUSH_PUBLIC_KEY + WEB_PUSH_PRIVATE_KEYNotificações push no navegador (gere um par de chaves VAPID)
HUBSPOT_KEYSincronização opcional com CRM para novos cadastros

Atualizando​

Cada serviço está vinculado ao seu repositório do GitHub. Pushes para main em ChurchApps/Api, ChurchApps/B1Admin ou ChurchApps/B1App disparam reimplantações automáticas.

Para fixar uma versão específica, altere a configuração Branch de cada serviço para uma tag ou branch de release. Esta é a configuração recomendada para produção — a implantação automática a partir de main faz você herdar qualquer trabalho em andamento.

Custos​

Faixas reais para uma igreja pequena (menos de 200 membros, tráfego leve):

ComponenteCusto mensal aproximado
Base do RailwayUS$ 5
Plugin MySQLUS$ 5 + ~US$ 1 de armazenamento
Computação dos 3 serviços webUS$ 3–10 no total
Volume de 1 GBUS$ 0,25
Total~US$ 15–25/mês

Os custos crescem linearmente com o tráfego, os envios de fotos e o tamanho do banco de dados. O Railway mostra o uso em tempo real na aba Usage do projeto — defina limites de gasto ali para limitar sua exposição.

Solução de problemas​

SintomaCausa provávelCorreção
O build falha com EBUSY: rmdir '/app/node_modules/.cache'conflito do cache de montagem do NixpacksDefina NIXPACKS_NO_CACHE=true no serviço afetado
O build falha no B1Admin com Missing: @types/...package-lock.json fora de sincroniaAtualize para o main mais recente
O deploy da Api fica preso em "Deploying"verificação de saúde falhando — /health não retorna 200Veja os logs de deploy; normalmente falta uma variável obrigatória
O B1Admin mostra "verifique seu e-mail", mas nenhum e-mail chegaMAIL_SYSTEM=SMTP definido, mas credenciais ausentes ou erradasCorrija as credenciais, ou remova MAIL_SYSTEM para desativar o e-mail
O login redireciona para api.churchapps.orgREACT_APP_STAGE está como prodDefina REACT_APP_STAGE=custom no serviço B1Admin
Todas as igrejas por subdomínio mostram o mesmo conteúdoREACT_APP_B1_WEBSITE_URL não inclui o token {subdomain}Defina como, por exemplo, https://{subdomain}.suaigreja.org
Domínio personalizado mostra "Application not found"DNS ainda não propagado, ou certificado do Railway pendenteAguarde 5 minutos; verifique o DNS com dig admin.suaigreja.org

Se você encontrar algo que não está nesta lista, abra uma issue em github.com/ChurchApps/Api/issues com os logs de implantação anexados.

Artigos relacionados​