Pré-requisitos

Para criar um projeto via API, o usuário ou a API Key da organização precisa de project.create em organization:*. Se o projeto for criado como PostgreSQL/MariaDB, use database.create; se for Cache, Queue ou Valkey, use managed_service.create. Para visualizar o projeto depois, conceda project.read em project:<project-id>.

Uma sessão owner tem acesso completo. assistant, member e API Keys precisam dos grants correspondentes.

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.

Vídeo: criação de um projeto HTTP com imagem OCI no plano Free, do console até a aplicação no ar.

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, Python e Bun 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, depois escolha uma forma de atualização. Se quiser publicar automaticamente a cada push nessa branch, selecione Automático por branch. Você pode alterar a forma depois da criação; veja Implantação via GitHub. Também é possível 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, Python e Bun, 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 campo opcional Diretório raiz indica a pasta do repositório onde a instalação, o build e o start são executados. Mantenha . para usar a raiz do repositório. Em um monorepo, informe o caminho relativo da pasta da aplicação, como backend ou apps/api, sem .. e sem barra inicial. Veja Diretório raiz e monorepos.

No modo Automático por branch, cada push na branch selecionada publica uma nova versão. Nos modos Manual, Por Tag e Por Release, a atualização segue a ação ou o evento escolhido. Consulte Implantação via GitHub para os detalhes.

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/nginx:1.30.5-alpine
docker.io/metabase/metabase:v0.50.0
docker.io/wordpress:6.5.3-php8.2-apache

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

Todo projeto HTTP público recebe um subdomínio da Zenifra. A plataforma usa primeiro o nome do projeto; se o nome já estiver ocupado, acrescenta uma sequência aleatória para manter o endereço único. O ID do projeto não faz parte do endereço.

Para um subdomínio personalizado, use de 6 a 54 caracteres, com letras minúsculas, números e hífens internos. O endereço não pode começar ou terminar com hífen.

Projetos públicos em planos superiores ao Basic também podem escolher o 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

O console confirma a criação e mostra o ID do Projeto. Ao clicar em Continuar, você volta para a lista de projetos, onde o novo projeto aparece com o status atualizado:

Abra o projeto para ver:

• ID do Projeto: identificador único usado pela CLI, pela API e pela GitHub Action
• Endereço público: disponível quando o projeto foi criado como público
• Status e logs: para acompanhar a primeira publicação

Quando o status muda para Projeto rodando, a aplicação já responde no endereço público com HTTPS:

Para automatizar o projeto pela API, CLI ou GitHub Actions, crie uma API key da organização com apenas os scopes necessários. Guarde a chave em um gerenciador de segredos e nunca a versione no repositório.

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, a forma de atualização selecionada define como publicar: Automático por branch responde a pushes, enquanto Manual, Por Tag e Por Release seguem seus respectivos fluxos. 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 e o Diretório raiz 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.