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 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 GitHub ou Imagem OCI
parâmetros de build e inicialização em projetos baseados em GitHub
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 do projeto	Sim	Consulte o fluxo atual antes de assumir troca de origem
Branch e comandos GitHub	Sim, em projetos GitHub	Sim
Variáveis de ambiente	Sim	Sim
Domínios personalizados	Sim	Sim
Instâncias	Sim	Sim
Storage	Sim	Capacidade pode variar conforme o plano; o diretório persistido exige atenção

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

Ao criar um projeto HTTP, a Zenifra trabalha principalmente com duas origens.

Repositório GitHub

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

proprietário e nome do repositório
branch
runtime e versão do runtime
auto-deploy
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.

Imagem OCI

Essa opção é indicada quando você já possui uma imagem pronta, quer controlar o artefato fora do GitHub ou precisa publicar via registry.

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 GitHub

Em projetos baseados em GitHub, 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.

Auto-deploy

Quando ativado, o auto-deploy permite que pushes na branch configurada disparem novas publicações. Isso reduz trabalho manual, mas também pede mais cuidado com estabilidade da branch monitorada.

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

No fluxo atual confirmado, projetos com origem em GitHub podem editar esses comandos depois da criação pela tela de configuração do projeto.

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

Subdomínio e domínios personalizados

Dependendo do plano, o projeto 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, a Zenifra também pode expor listas de IP em formato CIDR.

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

Em fluxos de edição confirmados no console, instâncias fazem parte da configuração operacional do projeto.

Porta da aplicação

A porta informa para onde o tráfego HTTP/HTTPS deve ser roteado dentro do container. Ela precisa refletir a porta em que sua aplicação realmente escuta.

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 do container 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 mudanca 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.