Deploy em produção na Zenifra

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é-requisitos

• 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ção

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 OCI

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 HTTP

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 dados

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: a Zenifra não oferece backup automático com restauração pelo console. Antes de ir para produção, defina uma rotina própria de dumps ou exports (por exemplo, pg_dump ou mysqldump) e teste a restauração.

Passo 5: validar logs, métricas e versão

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 acesso

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 deploy

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ça

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 passos

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

FAQ

Posso usar a Zenifra em produção?

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?

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?

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.