Pré-requisitos

Para criar um projeto na Zenifra, é necessário ter:

• Uma conta criada e verificada
• Login realizado no console

Acessando a Criação de Projeto

No menu lateral do console, clique em + Criar Projeto.

Passo 1: Escolher o Tipo de Projeto

A Zenifra oferece diferentes tipos de aplicações para deploy:

Aplicação HTTP

Ideal para:

• Aplicações Web (React, Vue, Angular)
• Servidores HTTP (Nginx, Apache)
• APIs REST
• Aplicações Node.js e Python via Repositório GitHub
• Java, Go, PHP, .NET, Nginx, Apache e outros stacks via Imagem OCI

Formas de publicação

A Zenifra oferece duas formas de publicar um projeto HTTP:

• Repositório GitHub: escolha Origem de Projeto como Repositório GitHub, selecione o repositório e a branch. Se quiser publicar automaticamente a cada push nessa branch, habilite auto-deploy durante a criação. Depois da criação, você também pode editar os comandos de pre-build, build e start na tela de editar projeto. pre-build e build são opcionais; start é obrigatório.
• Imagem OCI: informe uma imagem padrão OCI (Docker) para publicar a aplicação. Nesse fluxo, novas versões são publicadas atualizando a imagem ou tag no console.

Banco de Dados PostgreSQL

Se você precisa de um banco de dados gerenciado, veja nosso tutorial de como criar um banco de dados PostgreSQL.

Passo 2: Selecionar o Plano

Os planos definem os recursos disponíveis e o preço da sua aplicação. Cada plano oferece diferentes níveis de:

• CPU, Memória e GPU
• Armazenamento gratuito (se houver)
• Recursos exclusivos (subdomínio personalizado, bloqueio de IP, etc.)

Modelos de Pagamento

Escolha como deseja pagar pelo seu projeto:

Dica: No pagamento por hora, se sua aplicação rodar apenas 10 minutos no mês, você paga apenas por 1 hora!

Passo 3: Configurar Informações Básicas

Nome do Projeto

O nome é utilizado para:

• Identificar seu projeto no dashboard
• Criar subdomínios automáticos

Regras do nome:

• Mínimo: 6 caracteres
• Máximo: 32 caracteres
• Apenas letras minúsculas, números e hífens
• Exemplo: meu-projeto-web, api-minha-empresa

Descrição

Campo opcional para adicionar informações sobre o projeto. Ajuda a organizar e identificar projetos quando você tem vários.

Passo 4: Configurar a Origem do Projeto

Repositório GitHub

Se você escolheu Repositório GitHub, selecione o repositório, a branch principal e o runtime da aplicação. Para projetos Node.js e Python, revise os comandos de pre-build, build e start antes de criar o projeto. Nem todo projeto precisa de build; o campo pode ficar vazio quando a aplicação só precisa de start.

O auto-deploy é opcional. Quando ele está habilitado, cada push na branch selecionada publica uma nova versão. Quando está desabilitado, você controla a publicação manualmente pelo console.

Imagem OCI

A imagem OCI é o modelo que será utilizado para criar sua instância. Você pode usar imagens públicas ou privadas.

Imagem Pública

Imagens que não necessitam de autenticação para download. Exemplos:

docker.io/nginxinc/nginx-unprivileged:stable-alpine
docker.io/metabase/metabase:v0.50.0
docker.io/wordpress:6.5.3-php8.2-apache

Para NGINX, use a imagem nginxinc/nginx-unprivileged, pois imagens OCI na Zenifra não devem executar o processo principal como root.

Imagem Privada

Para imagens em registries privados, você precisará configurar autenticação:

Opção 1: AWS ECR

• Região AWS onde seu repositório está localizado
• Access Key ID e Secret Access Key
• ID da sua conta AWS

Opção 2: Usuário e Token

• Nome de usuário do registry
• Token ou senha de acesso

Importante: Sempre utilize tags específicas (como v1.2.3) em vez de latest. Isso garante que sua aplicação sempre utilizará a mesma versão da imagem.

Passo 5: Configurar Porta e Instâncias

Porta da Aplicação

A porta que sua aplicação escuta internamente. O tráfego externo (HTTP/HTTPS nas portas 80 e 443) será roteado para esta porta.

Portas comuns por tecnologia:

Quantidade de Instâncias

Número de réplicas da sua aplicação:

• 1 instância: Ideal para aplicações de baixo tráfego ou testes
• 2+ instâncias: Alta disponibilidade e balanceamento de carga

Recomendação: Para aplicações em produção, utilize pelo menos 2 instâncias para garantir disponibilidade em caso de falhas.

Passo 6: Variáveis de Ambiente

As variáveis de ambiente (ENVs) são configurações que sua aplicação pode acessar em tempo de execução. São úteis para:

• Configurações sensíveis (API keys, senhas)
• URLs de APIs externas
• Configurações que mudam entre ambientes

Exemplos de ENVs:

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

Limite: Até 50 variáveis de ambiente por projeto.

Passo 7: Configurar Armazenamento

Armazenamento Persistente

Escolha "Sim" se sua aplicação precisa:

• Salvar arquivos que devem sobreviver a reinicializações
• Manter uploads de usuários

Escolha "Não" para aplicações onde os dados são efêmeros (como servidores web stateless).

Observação: Os dados de armazenamento persistente são replicados em 3 instâncias diferentes. Ou seja, caso você salve um arquivo PDF e um servidor da Zenifra falhe, seu arquivo salvo localmente continuará existindo.

Capacidade de Armazenamento

• Mínimo: 1 GB
• Máximo: 250 GB

Atenção: Para modelos de pagamento por hora, o armazenamento só pode ser aumentado, nunca reduzido. Para contratos mensais ou anuais, não é possível alterar o armazenamento após a criação do projeto.

Diretório para Persistir

Caminho absoluto do diretório dentro do container cujos dados serão salvos:

/app/data
/var/lib/postgresql/data
/uploads

Um caso de uso comum do armazenamento gratuito oferecido no plano, quando disponível, é guardar arquivos em /data, como imports temporários, PDFs gerados, relatórios ou outros artefatos que podem ser apagados depois do uso.

Importante: Você pode escolher a pasta persistida no momento da criação do projeto, mas esse caminho não pode ser alterado depois.

Passo 8: Configurar Domínios

Antes de configurar domínio, escolha a exposição do projeto:

• Público: a Zenifra cria rota pública e domínio para a aplicação.
• Privado: a aplicação roda sem rota pública na internet e não recebe domínio da Zenifra.

Use projeto privado para automações, workers, rotinas internas ou aplicações que não precisam receber tráfego externo.

Subdomínio Zenifra

Projetos públicos em planos superiores ao Basic incluem subdomínio personalizado no formato:

seu-projeto-sub-domain

Domínio Próprio

Você pode usar seu próprio domínio (ex: api.suaempresa.com) em vez do subdomínio padrão, mas essa configuração é feita depois que o projeto público já foi criado e está acessível pelo domínio padrão da Zenifra.

Para configurar após a criação:

1. Abra as configurações do projeto
2. Adicione seu domínio próprio (ex: api.suaempresa.com)
3. Para subdomínios, como api.suaempresa.com, configure um CNAME apontando para o subdomínio criado na Zenifra
4. Para domínios raiz, como suaempresa.com, use CNAME somente em provedor com CNAME flattening, ou redirecione o root para um subdomínio como www.suaempresa.com
5. Publique os registros TXT de validação SSL exibidos no console, se forem solicitados

Limite: Até 20 domínios próprios por projeto.

Passo 9: Configurar Acesso de Rede (Planos Premium+)

Esta opção está disponível apenas em planos específicos.

Lista Branca (Whitelist)

Define quais endereços IP podem acessar seu projeto. IPs não listados serão bloqueados.

Formato CIDR:

• 0.0.0.0/0 - Permite todos os IPs
• XXX.XXX.XXX.XXX/YY - Permite apenas o IP em si e todo o seu bloco.

Você pode adicionar seu IP atual automaticamente com um clique.

Lista Negra (Blacklist)

Define IPs específicos que serão bloqueados, mesmo que estejam na lista branca.

Passo 10: Finalizar a Criação

1. Revise todas as configurações
2. Clique em "Criar Projeto"
3. Aguarde alguns segundos para a criação

Após a Criação

Você receberá:

• ID do Projeto: Identificador único do seu projeto
• API Key: Chave para autenticação na API da Zenifra

Guarde a API Key em local seguro! Ela será necessária para gerenciar seu projeto via API.

Próximos Passos

• Como Atualizar Imagem Automaticamente via GitHub
• Gerenciar Projetos
• Configurações de Pagamento

FAQ

Posso mudar o plano depois de criar o projeto?

Depende. Se o modelo de pagamento for por hora, você pode alterar o plano a qualquer momento. Para contratos mensais ou anuais, a mudança só é permitida ao final do período contratado.

Como atualizar a imagem do meu projeto?

Se o projeto usa Repositório GitHub como origem e auto-deploy está habilitado, cada push na branch selecionada atualiza a instância automaticamente. Se o auto-deploy está desabilitado, publique manualmente pelo console. Se o projeto usa imagem OCI, atualize a imagem no console e publique a nova versão.

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

Sim. Em projetos com origem em Repositório GitHub, você pode editar esses comandos depois da criação na tela de editar projeto.

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

Não. O diretório escolhido na criação para armazenamento persistente, como /data, não pode ser alterado depois.

Posso ter múltiplos projetos?

Sim! Não há limite de projetos por conta. Cada projeto é cobrado independentemente de acordo com suas configurações.

Como deletar um projeto?

1. Acesse a página do projeto em específico
2. Clique em Deletar
3. Confirme a ação

Atenção: Esta ação é irreversível! Todos os dados e configurações serão excluídos permanentemente.