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
• não executar o processo principal como root; use um usuário não privilegiado
• escutar em uma porta compatível com usuário não privilegiado, como 8080, quando a imagem não puder abrir portas abaixo de 1024
• 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.

Para NGINX, use uma imagem que já rode sem privilégios de root, como:

docker.io/nginxinc/nginx-unprivileged:stable-alpine

Nesse caso, configure a porta do projeto conforme a porta exposta pela imagem, geralmente 8080, 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.