Acessando as Configurações

Para operar estas configurações por API, conceda o scope mínimo por ação em project:<project-id>:

owner tem acesso completo na sessão de usuário. assistant, member e API Keys da organização precisam do grant específico.

1. No menu lateral, clique em Projetos
2. Localize e clique no nome do projeto desejado
3. Na página do projeto, clique no botão Editar

Nota: Lista branca e lista negra são recursos exclusivos de projetos HTTP. Bancos de dados não oferecem whitelist ou blacklist.

Configurações Disponíveis

Nome do Projeto

O nome do projeto pode ser alterado a qualquer momento.

Regras:

• Mínimo: 6 caracteres
• Máximo: 32 caracteres
• Apenas letras minúsculas, números e hífens

Nota: A alteração do nome não afeta o subdomínio existente.

Subdomínio da Zenifra

Ao criar ou alterar a exposição pública, o projeto recebe um subdomínio da Zenifra sem usar o ID do projeto. O endereço é baseado no nome do projeto e pode receber um sufixo aleatório quando o nome já estiver ocupado.

Quando o plano permite personalização (a partir do Premium), altere o subdomínio na seção Domínio principal e clique em Salvar domínio principal. O subdomínio informado deve ter de 3 a 54 caracteres, usando letras minúsculas, números e hífens internos. Projetos privados não têm domínio público.

Descrição do Projeto

A descrição do projeto pode ser alterada a qualquer momento.

Características:

• Campo opcional para descrever o propósito do projeto
• Ajuda a identificar e organizar seus projetos
• Pode incluir informações como tecnologia utilizada, cliente, ou finalidade

Imagem do Projeto

A imagem OCI utilizada pelo projeto pode ser atualizada.

Como atualizar:

1. Na seção de imagem, insira a nova imagem no formato:

   docker.io/nginx:alpine

Limitações:

• Não é possível mudar o tipo de autenticação da imagem (pública/privada)
• A imagem privada deve continuar sendo privada
• A imagem pública deve continuar sendo pública

Dica: Para atualizar a imagem automaticamente via GitHub Actions, consulte nosso tutorial de deploy automático.

Repositório Git e comandos de build

Projetos Forgejo têm a seção Repositório Git, que permite trocar o repositório ou a branch, ajustar runtime (Node.js ou Python) e versão, editar os comandos Comando Start, Comando Pré-build e Comando Build e o Diretório raiz, e desconectar o repositório. Projetos GitHub criados pelo console mostram o card Deploy pelo GitHub e a seção Comandos GitHub (Comando de Inicialização, Comando de Pré-build, Comando de Build e Diretório raiz); runtime e branch não mudam pelo console. Em projetos GitHub, salvar novos comandos ou um novo diretório raiz dispara uma nova build; em projetos Forgejo, a mudança vale a partir da próxima build.

Quando isso é útil:

• Ajustar o fluxo de build após mudar framework ou estrutura do repositório
• Corrigir comandos de instalação antes de uma nova publicação
• Alterar o comando de inicialização sem recriar o projeto
• Apontar a build para outra pasta do repositório, como em monorepos

Exemplos de comandos:

pre-build: npm install
build: npm run build
start: npm run start

pre-build é opcional, build também é opcional e start continua obrigatório. Projetos mais simples podem funcionar apenas com start.

Diretório raiz é a pasta do repositório onde a instalação, o build e o start são executados. Use . para a raiz ou um caminho relativo, como backend ou apps/api, sem .. e sem barra inicial. Se a pasta não existir na branch, a build falha com a mensagem "O diretório raiz configurado não existe no repositório.". Veja Diretório raiz e monorepos.

Nota: Essa opção vale para projetos com origem em repositório Git. Projetos publicados por imagem OCI não usam esses comandos nessa tela.

Exposição do Projeto

Projetos HTTP podem ser alterados entre Público e Privado mesmo depois da criação.

Como alterar:

1. Na página de edição do projeto, localize a seção Exposição
2. Selecione Público - expõe rota e domínio ou Privado - sem rota pública
3. Clique em Salvar Exposição
4. Confirme a ação no modal

Efeitos:

• Público: cria ou restaura a rota pública e o domínio do projeto
• Privado: remove a rota pública, o subdomínio da Zenifra e domínios personalizados
• Domínios personalizados e regras de acesso por IP só ficam editáveis quando o projeto está público

Use Privado para automações, aplicações administrativas e rotinas que não precisam receber tráfego da internet. Para tarefas em horários definidos, use um Job agendado.

Variáveis de Ambiente (ENVs)

As variáveis de ambiente podem ser adicionadas, editadas ou removidas.

Características:

• Limite de 50 ENVs por projeto
• As instâncias são reiniciadas automaticamente ao alterar ENVs
• Use ENVs para configurações sensíveis como API keys e senhas de banco

Exemplo de ENVs:

DATABASE_URL=postgres://user:pass@host:5432/db
API_KEY=sua-chave-aqui
NODE_ENV=production

Nota: Além das ENVs definidas por você, a Zenifra também pode injetar variáveis operacionais automaticamente, como ZENIFRA_INSTANCE_VERSION, útil para diferenciar versões nos logs e no troubleshooting.

Acesso de Rede

A seção Acesso de Rede está disponível a partir do plano Premium Plus e somente para projetos públicos. Ative Ativar controle de acesso por IP, preencha as listas e clique em Salvar Acesso de Rede. Se o plano não tiver o recurso, as listas são ignoradas.

Lista Branca (Whitelist)

A Lista Branca de Entrada define quais endereços IP podem acessar o projeto.

Características:

• IPs não listados serão bloqueados
• Formato CIDR: 192.168.1.0/24 ou 10.0.0.1/32
• Máximo de 10 entradas na whitelist

Como adicionar um IP: Informe o CIDR e uma Descrição e clique em Adicionar. (Na criação do projeto, o botão Adicionar IP Atual inclui seu endereço automaticamente.)

Formato CIDR:

• 0.0.0.0/0 - Permite todos os IPs
• XXX.XXX.XXX.XXX/32 - IP específico
• XXX.XXX.XXX.XXX/YY - Bloco de IPs

Nota: A alteração da whitelist não reinicia as instâncias.

Lista Negra (Blacklist)

A Lista Negra de Entrada define IPs que serão bloqueados mesmo se estiverem na whitelist.

Características:

• IPs bloqueados não terão acesso ao projeto
• Útil para bloquear IPs maliciosos
• Máximo de 10 entradas na blacklist

Nota: A alteração da blacklist não reinicia as instâncias.

Número de Instâncias

Você pode aumentar ou diminuir o número de instâncias do projeto.

Limites:

• Mínimo: 1 instância
• Máximo: depende da capacidade disponível do plano; quando não há capacidade, a alteração é recusada
• Plano Free: no máximo 2 instâncias somadas na organização
• Não é possível alterar instâncias com o projeto pausado
• Com o auto-scaling ativo, desative-o para alterar as instâncias manualmente

Para picos de tráfego: Use o auto-scaling (planos pagos), que ajusta as instâncias entre um mínimo e um máximo conforme CPU e memória.

Impacto:

• Mais instâncias = maior capacidade de processamento
• Mais instâncias = maior custo
• O tráfego é distribuído entre as instâncias

Storage, plano e contrato

• Storage: aumenta o armazenamento do projeto; disponível apenas para projetos com pagamento por hora e não pode ser reduzido. Veja Armazenamento.
• Plano: disponível apenas para projetos com pagamento por hora. Não é possível trocar de/para o plano Free.
• Contrato: em contratos mensais ou anuais, mostra o modo de pagamento, a data de término e a renovação automática.

Health check e alertas

• Healthcheck da aplicação (a partir do Premium): verifica um caminho, como /health, a cada 60 segundos e lista as falhas dos últimos 30 dias. Veja Portas e health checks.
• Alertas por e-mail: avisa quando a aplicação reinicia inesperadamente ou quando uma instância usa 80% ou mais de CPU ou de memória (no máximo um e-mail por tipo de alerta por hora).

Ações do Projeto

As ações ficam na página do projeto.

Pausar o Projeto

Ao clicar em Pausar e confirmar em Pausar projeto:

• As instâncias são interrompidas
• O armazenamento efêmero é apagado
• O projeto não pode ser acessado
• Para projetos por hora, a cobrança de processamento é interrompida; o armazenamento persistente adicional continua sendo cobrado

Quando usar:

• Quando não precisa da aplicação temporariamente
• Para economizar em projetos por hora

Retomar o Projeto

Ao clicar em Retomar em um projeto pausado:

• As instâncias são iniciadas novamente
• O armazenamento efêmero é recriado
• O projeto volta a ser acessível
• A cobrança é retomada (para projetos por hora)
• Se a organização estiver bloqueada por valores em aberto, a retomada é recusada até a regularização

Desativar a Renovação Automática

Apenas para projetos com contrato mensal ou anual

Nesse caso, o comportamento correto é impedir a renovação automática do contrato:

• o projeto permanece ativo até o final do período contratado
• ao expirar, o contrato não será renovado
• o fluxo é feito pela seção Contrato da página de edição do projeto (Salvar Renovação Automática)

Nota: Para projetos com pagamento por hora, essa opção não está disponível. Use Pausar para interromper a cobrança de processamento.

Excluir o Projeto

Clique em Excluir na página do projeto e confirme. A exclusão é permanente e irreversível.

O que acontece:

• Todas as instâncias são removidas
• Todos os dados do projeto são apagados
• O armazenamento é liberado
• O uso por hora é fechado e cobrado até o momento da exclusão

Próximos Passos

• Métricas e Insights do Projeto
• Como Criar um Projeto
• Configurações de Pagamento

FAQ

Posso alterar o plano do projeto?

Sim, se o modelo de pagamento for por hora: o plano pode ser alterado a qualquer momento, exceto de ou para o plano Free. Projetos com contrato mensal ou anual não podem trocar de plano.

A alteração de ENVs causa downtime?

Sim. As instâncias são reiniciadas para aplicar as novas variáveis de ambiente. Planeje as alterações em horários de baixo acesso.

Posso restaurar um projeto deletado?

Não. A deleção é permanente. Certifique-se de fazer backup dos dados antes de deletar.

Posso alterar os comandos de pre-build, build e start depois?

Sim. Em projetos com origem em repositório Git (GitHub ou Forgejo), esses comandos e o Diretório raiz podem ser editados após a criação do projeto. Em projetos GitHub, salvar a alteração inicia uma nova build; em projetos Forgejo, ela vale a partir da próxima build.

Posso alterar o diretório de persistência depois?

Não. O caminho definido na criação do projeto para armazenamento persistente permanece fixo depois que o projeto é criado.

A Zenifra injeta alguma ENV automaticamente?

Sim. Um exemplo é ZENIFRA_INSTANCE_VERSION, que informa a versão da instância publicada e pode ser usada no código para distinguir logs e releases.

O que acontece com os dados ao parar o projeto?

• Dados persistentes: Mantidos
• Dados efêmeros: Apagados

Recomendamos usar armazenamento persistente para dados importantes.