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.
• 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.

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

Subdomínio Zenifra

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 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.