Configuração do projeto

As configurações do projeto na Zenifra definem como sua aplicação é publicada, executada e exposta na internet. Esta página funciona como uma visão central das principais opções disponíveis no console, com foco em regras, decisões práticas e limites mais importantes.

Para detalhes de cada área, veja Variáveis de ambiente, Armazenamento persistente, Rede e controle de acesso e Domínios personalizados.

Para passo a passo detalhado de criação e edição, consulte também:

O que entra na configuração do projeto

No fluxo atual da Zenifra, a configuração de um projeto pode envolver:

identidade do projeto, como nome e descrição
origem da publicação, como Repositório Git (GitHub ou Forgejo) ou imagem OCI
parâmetros de build e inicialização em projetos baseados em repositório Git
variáveis de ambiente e segredos operacionais
subdomínio e domínios personalizados
regras de acesso de rede por IP
capacidade operacional, como instâncias e armazenamento

Essas opções ficam concentradas no console e ajudam a decidir como a aplicação será implantada, atualizada e mantida.

O que costuma ser definido na criação e o que pode mudar depois

Algumas escolhas são feitas logo na criação do projeto e outras aparecem novamente na tela de edição.

Área	Definida na criação	Pode ter ajustes depois
Nome e descrição	Sim	Sim
Origem e repositório	Sim	Forgejo: sim, na seção Repositório Git é possível trocar ou desconectar o repositório. GitHub: não pelo console
Branch	Sim	Forgejo: sim, na seção Repositório Git. GitHub: não pelo console
Forma de atualização	Sim	Sim
Runtime e comandos de build	Sim, em projetos com repositório Git	Comandos: sim. Runtime: em projetos Forgejo, sim; em projetos GitHub, não pelo console
Variáveis de ambiente	Sim	Sim
Subdomínio da Zenifra	Sim	Sim, em planos com subdomínio personalizado (a partir do Premium)
Domínios personalizados	Não	Sim, depois que o projeto público estiver criado
Instâncias	Sim	Sim
Storage	Sim	Capacidade pode ser aumentada (nunca reduzida) em projetos por hora; o diretório persistido não muda

Nota: Nem toda configuração segue a mesma regra de edição. Quando uma escolha impacta build, restart, persistência ou faturamento, valide o comportamento esperado na tela de edição do projeto.

Escolhendo a origem do projeto

No console, a origem de um projeto HTTP é Repositório Git ou Imagem Docker (imagem OCI). Também é possível começar por um template ou publicar pela CLI e pela GitHub Action.

Repositório Git (GitHub ou Forgejo)

Essa opção é indicada quando você quer manter o deploy ligado ao código-fonte. Nesse modo, o console pode expor configurações como:

provedor Git, proprietário e nome do repositório
branch
runtime e versão do runtime (Node.js, Python ou Bun)
forma de atualização
comandos pre-build, build e start

Esse modelo é útil para aplicações que evoluem com frequência e precisam de um fluxo de publicação mais próximo do desenvolvimento.

Se o projeto usa GitHub como origem, veja também como conectar GitHub à Zenifra. Para Forgejo, veja Implantação via Forgejo.

Imagem OCI

Essa opção é indicada quando você já possui uma imagem pronta, quer controlar o artefato fora do repositório ou precisa publicar via registry. Também é o caminho para stacks sem runtime de build na Zenifra, como Go, Java, PHP ou .NET.

Ela costuma fazer mais sentido quando:

o pipeline de build já roda fora da Zenifra
a imagem é gerada por CI externa
você quer promover versões imutáveis por tag

Se precisar trocar a imagem publicada, use o fluxo descrito em como alterar a imagem do projeto.

Build e inicialização em projetos com repositório Git

Em projetos baseados em repositório Git, a configuração não se limita ao repositório. O console também pode expor parâmetros que afetam diretamente a compilação e a subida da aplicação.

Runtime e versão

Esses campos ajudam a alinhar o ambiente de build com a stack usada no projeto. Em fluxos Node.js ou Python, por exemplo, a escolha da versão pode evitar diferenças entre desenvolvimento e produção.

Automático por branch

No modo Automático por branch, pushes na branch selecionada disparam novas publicações. Escolha esse modo somente quando a branch monitorada estiver estável; outros modos permitem publicar manualmente, por tag ou por release.

Comandos `pre-build`, `build` e `start`

Esses comandos controlam etapas importantes do deploy, como instalação de dependências, compilação e inicialização da aplicação. Eles são especialmente úteis quando:

o projeto mudou de framework
o comando padrão não atende a estrutura do repositório
o processo de start precisa ser ajustado sem recriar o projeto

Projetos com origem em repositório Git podem editar esses comandos depois da criação pela tela de edição do projeto; salvar novos comandos dispara uma nova build.

Variáveis de ambiente e segredos

As variáveis de ambiente centralizam valores que não devem ficar fixos no código, como:

DATABASE_URL
API_KEY
PORT
URLs de APIs externas

Boas práticas:

use o console para armazenar segredos sensíveis
não comite tokens, senhas ou chaves no repositório
separe variáveis operacionais de valores de desenvolvimento local
revise nomes e valores antes de salvar, porque mudanças podem exigir reinício das instâncias

Variáveis injetadas pela plataforma

Além das variáveis definidas por você no console, a Zenifra também pode injetar variáveis operacionais automaticamente nas instâncias.

Um exemplo importante é:

ZENIFRA_INSTANCE_VERSION: informa a versão da instância publicada

Você pode usar essa variável no código para:

distinguir logs entre versões diferentes
identificar rapidamente qual release está atendendo uma requisição
ajudar em troubleshooting durante rollouts e atualizações

Para exemplos práticos de preenchimento, consulte o guia de criação de projeto HTTP.

Rede, domínios e exposição pública

Projetos HTTP podem ser criados com exposure: public ou exposure: private.

public: cria rota pública, subdomínio da Zenifra e permite domínios próprios conforme o plano.
private: mantém a aplicação sem domínio público, útil para automações, workers e rotinas internas.

Subdomínio e domínios personalizados

Dependendo do plano, um projeto público pode usar um subdomínio da Zenifra e também aceitar domínios próprios. Essa camada de configuração define como os usuários chegam à sua aplicação.

Domínios personalizados fazem sentido quando você quer:

publicar com a identidade da sua empresa
separar ambientes por host
usar um endpoint mais estável para integrações

Whitelist e blacklist

Para cenários que pedem controle de acesso em projetos públicos, a partir do plano Premium Plus, a Zenifra oferece listas de IP em formato CIDR (até 10 em cada lista).

a whitelist define quem pode entrar
a blacklist bloqueia IPs específicos

Esse recurso é útil em ambientes internos, painéis administrativos, APIs restritas ou fases de homologação.

Escala e operação

Instâncias

O número de instâncias influencia capacidade, disponibilidade e custo. Em geral:

menos instâncias simplificam ambientes de teste
mais instâncias aumentam capacidade e redundância

As instâncias podem ser alteradas na tela de edição do projeto. Em planos pagos, o auto-scaling ajusta as instâncias automaticamente entre um mínimo e um máximo.

Porta da aplicação

A porta informa para onde o tráfego HTTP/HTTPS deve ser encaminhado dentro da aplicação. Ela precisa refletir a porta em que sua aplicação realmente escuta (padrão 3000 para Node.js e Bun, 8000 para Python).

Mesmo quando a documentação detalhada estiver no fluxo de criação, vale tratar essa definição como parte crítica da configuração inicial do projeto.

Armazenamento persistente

O storage define se determinados dados da aplicação devem sobreviver a reinicializações e novas execuções.

Quando usar

Armazenamento persistente faz sentido quando a aplicação precisa:

manter uploads
guardar artefatos gerados
preservar arquivos usados entre reinicializações

Um caso comum é usar /data para armazenar arquivos temporários de trabalho, imports, relatórios ou PDFs gerados que podem ser removidos depois do uso, mas que não devem sumir no meio da operação.

O que observar

a capacidade configurada deve acompanhar o volume esperado de dados
o caminho persistido precisa ser escolhido com cuidado
nem toda mudança de storage segue a mesma regra entre planos e modelos de pagamento

Se o seu fluxo depende de persistência, veja os detalhes no tutorial de criação de projeto HTTP.

Guias desta seção

Guia	Quando usar
Variáveis de ambiente	Configurar segredos, limites e reinícios
Armazenamento persistente	Manter arquivos entre reinícios e versões
Rede e controle de acesso	Projeto público ou privado e listas de IP
Domínios personalizados	Publicar com o domínio da sua empresa

Use esta página para decidir o que configurar e por que configurar. Para cliques e validações de tela, siga os guias do console.