Deploy via imagem OCICopy Anchor Link

Use imagem OCI quando sua aplicação já é empacotada fora da Zenifra. Esse fluxo é indicado para pipelines de CI que constroem a imagem, publicam em um registry e promovem versões por tag.

Quando escolher OCICopy Anchor Link

Escolha OCI quando:

• sua equipe já usa Docker em produção
• a imagem é gerada por GitHub Actions, GitLab CI, Jenkins ou outro pipeline
• você quer promover tags específicas entre ambientes
• o build precisa de etapas que não devem rodar dentro da Zenifra
• a aplicação precisa manter o mesmo artefato em diferentes plataformas

Para projetos que evoluem diretamente por código-fonte, veja Implantação via GitHub.

Requisitos da imagemCopy Anchor Link

A imagem precisa:

• expor um processo HTTP de longa duração
• escutar em 0.0.0.0
• usar a porta configurada no projeto Zenifra
• receber configuração por variáveis de ambiente
• iniciar sem depender de arquivos locais fora da imagem ou do volume configurado

Evite tags genéricas como latest em produção. Prefira tags como 1.4.2, 2026-05-16 ou o SHA do commit.

Imagens de uso exclusivo da Zenifra não podem ser usadas em projetos de clientes. A criação do projeto, a troca de imagem e os Ambientes de Preview recusam essas referências com 422 (IMAGE_NOT_ALLOWED, mensagem This image cannot be used); use uma imagem própria ou pública.

Imagens oficiais funcionam sem ajustes, inclusive as que rodam como root e escutam em portas baixas, como 80. Para NGINX, por exemplo:

docker.io/nginx:alpine

Nesse caso, configure a porta do projeto como 80, que é a porta exposta pela imagem, salvo se você tiver alterado a configuração da imagem.

Criar o projetoCopy Anchor Link

No console:

1. clique em Criar projeto no menu lateral
2. em Origem do Projeto, escolha Imagem Docker
3. informe a imagem, por exemplo ghcr.io/acme/api:1.4.2
4. em Imagem Pública, escolha Sim ou, para imagem privada, Não e preencha o Tipo de Autenticação
5. configure a porta da aplicação
6. adicione variáveis de ambiente
7. escolha plano, instâncias e storage
8. crie o projeto e acompanhe os logs

Atualizar a imagemCopy Anchor Link

Para publicar uma nova versão:

1. gere uma nova imagem no seu pipeline
2. publique a tag no registry
3. altere a imagem do projeto no console, pela CLI (zenifra project image set --project <id> --image <imagem>), pela API ou pela GitHub Action
4. valide os logs, a URL pública e, nos planos com métricas, o consumo

Se a imagem for privada, mantenha o mesmo tipo de autenticação definido na criação. Para detalhes, consulte Registry privado.

ValidaçãoCopy Anchor Link

Depois da publicação, confirme:

• a URL *.clients.zenifra.com responde
• a rota /health retorna sucesso, se existir
• logs não mostram erro de inicialização
• CPU, RAM, storage e requisições HTTP aparecem nas métricas, disponíveis a partir do plano Premium
• DATABASE_URL e demais variáveis foram configuradas manualmente

Próximos passosCopy Anchor Link

• Registry privado
• Portas e health checks
• Rollback

FAQCopy Anchor Link

Posso transformar um projeto OCI em GitHub depois?Copy Anchor Link

Sim. Na página do projeto, a seção Repositório Git conecta um repositório GitHub ou Forgejo a um projeto criado com imagem. Salvar a conexão não publica uma nova versão: as próximas passam a ser construídas a partir do código, conforme a forma de atualização escolhida. Veja Implantação via GitHub e Deploy a partir do Forgejo.

Posso usar imagem privada?Copy Anchor Link

Sim. A Zenifra aceita autenticação por AWS ECR ou por usuário e token/senha de registry.

Devo usar latest?Copy Anchor Link

Evite em produção. Tags imutáveis deixam rollback, auditoria e suporte mais previsíveis.

Minha imagem roda como root ou escuta na porta 80. Funciona?Copy Anchor Link

Sim. Imagens que rodam como root e escutam em portas baixas, como docker.io/nginx:alpine na porta 80, funcionam normalmente. Basta configurar o campo Porta do projeto com a porta exposta pela imagem.