Deploy em produção na ZenifraCopy Anchor Link

Este guia reúne o caminho recomendado para sair de uma conta nova até uma aplicação validada em produção. Use-o quando quiser conectar deploy, banco, observabilidade, domínio e cobrança em um único fluxo.

Pré-requisitosCopy Anchor Link

• conta ativa na Zenifra
• crédito disponível (inclusive o crédito promocional para novos usuários, enquanto a promoção estiver disponível) ou cartão configurado para cobrança automática; o plano Free não exige crédito
• repositório GitHub ou Forgejo, ou imagem OCI pronta para publicação
• comando de inicialização conhecido, como npm start, uvicorn main:app --host 0.0.0.0 --port 8000 ou equivalente
• porta HTTP em que a aplicação realmente escuta

Importante: a Zenifra roteia tráfego para a porta configurada no projeto. A aplicação precisa escutar nessa mesma porta.

Passo 1: preparar a aplicaçãoCopy Anchor Link

Antes de criar o projeto, confirme localmente que a aplicação sobe sem depender de arquivos ausentes.

Para Node.js, prefira ler a porta por variável de ambiente:

const PORT = process.env.PORT || 3000;
app.listen(PORT, '0.0.0.0');

Para Python com FastAPI, use um comando de start explícito:

uvicorn main:app --host 0.0.0.0 --port 8000

Se a aplicação usa banco, fila ou serviços externos, liste as variáveis necessárias antes do deploy. Não coloque senhas, tokens ou chaves no repositório.

Passo 2: escolher repositório Git ou imagem OCICopy Anchor Link

Use Repositório Git (GitHub ou Forgejo) quando quiser que a Zenifra faça o fluxo de build a partir do código-fonte. Esse caminho é ideal para aplicações que recebem mudanças frequentes e podem se beneficiar do modo Automático por branch.

Use Imagem OCI quando você já possui uma imagem pronta, gerada por CI externa, ou quando deseja controlar o artefato de produção por tag.

Passo 3: criar o projeto HTTPCopy Anchor Link

No console, clique em Criar projeto e preencha:

1. organização onde o projeto será criado
2. origem do projeto
3. runtime ou imagem
4. porta HTTP
5. comandos pre-build, build e start, quando a origem for um repositório Git
6. variáveis de ambiente
7. plano, instâncias e armazenamento conforme a necessidade

Depois da criação, abra a URL *.clients.zenifra.com e valide uma rota simples, como / ou /health.

Passo 4: conectar banco de dadosCopy Anchor Link

Se a aplicação usa PostgreSQL, MariaDB, Analytics (ClickHouse) ou Valkey (Chave-Valor, Cache e Filas), crie o serviço gerenciado e copie os dados de conexão no console. As conexões exigem TLS.

A Zenifra não injeta automaticamente DATABASE_URL no projeto HTTP. O fluxo correto é:

1. criar o banco
2. copiar a URI completa no console
3. configurar manualmente DATABASE_URL no projeto HTTP
4. reiniciar ou redeployar a aplicação se necessário
5. validar a conexão pelos logs e por uma rota da aplicação

Para detalhes de engine, réplicas, storage e failover, consulte Banco de Dados.

Backup: os bancos gerenciados têm backup automático incluído no plano, com restauração pelo suporte (veja Backups automáticos). Antes de ir para produção, mantenha também uma rotina própria de dumps ou exports (por exemplo, pg_dump ou mysqldump) como camada extra e teste a restauração.

Passo 5: validar logs, métricas e versãoCopy Anchor Link

Depois do deploy, verifique:

• logs da aplicação
• logs de build, quando houver
• CPU, RAM e armazenamento
• quantidade de requisições HTTP recebidas pela aplicação
• variável ZENIFRA_INSTANCE_VERSION, quando usada pelo seu código

Os logs da aplicação estão disponíveis em todos os planos; as métricas, a partir do plano Premium. Os logs são lidos ao vivo das instâncias, sem histórico retido; envie para um serviço próprio o que precisar guardar. Para detalhes, consulte Observabilidade.

Em projetos Git, abra Logs de build na página do projeto para acompanhar instalação de dependências, pre-build, build e publish. Use os logs da aplicação separadamente para investigar falhas depois do start.

Passo 6: configurar domínio e acessoCopy Anchor Link

Todo projeto recebe uma URL da Zenifra. Para produção, normalmente você também configura um domínio próprio.

Antes de apontar tráfego real:

• configure DNS no provedor do domínio
• valide a propagação
• mantenha a URL da Zenifra como fallback operacional
• revise whitelist e blacklist de IP quando o projeto for administrativo ou interno (a partir do plano Premium Plus)

Passo 7: validar o modo de deployCopy Anchor Link

Se Automático por branch estiver selecionado, faça uma alteração pequena na branch configurada e envie um novo push. Para validar as opções por tag e release, siga o guia de Implantação via GitHub ou Implantação via Forgejo.

Valide:

1. novo build iniciado
2. logs de build sem erro
3. aplicação respondendo na URL pública
4. versão nova visível nos logs ou em uma rota de diagnóstico

Nos modos Manual, Por Tag e Por Release, um push na branch não inicia uma atualização automática.

Passo 8: acompanhar cobrançaCopy Anchor Link

Antes de manter o projeto em produção, revise:

• modalidade de cobrança do projeto
• crédito disponível
• cartão como fallback de cobrança, quando configurado
• custo de banco e storage persistente
• consumo de IA, se a aplicação usa modelos da Zenifra

Para regras de crédito, mensalidade, anualidade e uso por hora, consulte Modelos de Pagamento.

Próximos passosCopy Anchor Link

• Checklist antes de ir para produção
• Deploy via GitHub
• Deploy via imagem OCI
• Segurança, privacidade e confiabilidade
• Limites e quotas

FAQCopy Anchor Link

Posso usar a Zenifra em produção?Copy Anchor Link

Sim. Use este guia junto com os documentos de deploy, banco, observabilidade, segurança e limites para validar se o plano e a configuração atendem ao seu cenário.

Preciso configurar DATABASE_URL manualmente?Copy Anchor Link

Sim. Bancos gerenciados mostram os dados de conexão no console, mas o projeto HTTP precisa receber DATABASE_URL manualmente como variável de ambiente.

Como sei que o deploy novo entrou no ar?Copy Anchor Link

Use logs, métricas, a URL pública e uma identificação de versão, como ZENIFRA_INSTANCE_VERSION ou uma rota /health que exponha a versão da aplicação.