Deploy via imagem OCI

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 OCI

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 imagem

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 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 customizado a configuração do container.

Criar o projeto

No console:

1. clique em Criar Projeto
2. escolha origem Imagem OCI
3. informe a imagem, por exemplo ghcr.io/acme/api:1.4.2
4. selecione se a imagem é pública ou privada
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 imagem

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
4. valide logs, métricas e URL pública

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

Validação

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 conforme o plano
• DATABASE_URL e demais variáveis foram configuradas manualmente

Próximos passos

• Registry privado
• Portas e health checks
• Rollback

FAQ

Posso transformar um projeto OCI em GitHub depois?

Não trate essa troca como fluxo normal. Um projeto criado com origem OCI continua sendo um projeto OCI.

Posso usar imagem privada?

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

Devo usar latest?

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?

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.