Pular para o conteúdo principal
Um template de imagem roda um app a partir de uma imagem Docker em vez de código-fonte. Você gera a imagem a partir do seu próprio Dockerfile e depois escreve um manifesto que aponta para essa imagem e declara a porta, a memória, o healthcheck e as perguntas. Neste tutorial você empacota um pequeno app web que guarda um contador de visitas no disco persistente e termina com um template privado que qualquer pessoa da sua conta pode fazer deploy em poucos cliques. Use um template de imagem quando o app precisar de outra linguagem ou versão, de pacotes do sistema, de um processo de inicialização próprio, ou quando você estiver empacotando um software pronto. Se o código-fonte puro basta, um template de código é mais simples e não usa vaga de imagem.

Antes de começar

A CLI da Vertra autenticada com uma chave de API que tenha os escopos templates:read, templates:write e templates:deploy, mais os escopos que fazem build de imagens.
Um plano que possa criar imagens Docker e templates privados (veja Planos e limites). Cada conta mantém até 5 templates privados.
Você conhece as regras das imagens Docker personalizadas: caminhos graváveis, usuário 1000:1000, a variável PORT e o que o build recusa.
Toda imagem em uso ocupa uma vaga de imagem na conta que a usa, não importa quantos apps rodem a partir dela. Quando você faz deploy do seu próprio template, a imagem já é sua; quem o recebe por um link ganha a própria cópia e usa uma vaga cada.

Passo a passo

1

Escreva um app que siga as regras da plataforma

Uma imagem roda com o mesmo isolamento de qualquer aplicação: o sistema de arquivos raiz é somente leitura, o usuário é sempre 1000:1000, /app é o único disco persistente e o servidor precisa escutar na variável PORT. Crie esta pasta:
O server.js serve a página, conta as visitas em um arquivo em /app/data e responde /healthz para o healthcheck:
server.js
O Dockerfile mantém o programa fora de /app (tudo o que a imagem coloca em /app fica escondido pelo disco persistente quando o app roda) e não usa USER, VOLUME nem HEALTHCHECK, que a plataforma ignora ou recusa:
Dockerfile
Teste localmente do mesmo jeito que vai rodar: docker run --rm --read-only --user 1000:1000 --tmpfs /tmp -e PORT=3000 -p 3000:3000 -v "$PWD/data:/app/data" hello-counter. Se só funcionar com a raiz gravável ou como root, não vai funcionar na plataforma.
2

Faça o build da imagem na plataforma

O template não carrega o Dockerfile: ele referencia uma imagem que já existe na sua conta. Faça o build a partir da pasta:
Encontre o id da imagem com vertra image list. Espere até o build ficar success; uma falha mostra o motivo no log. Os arquivos .env* são removidos do contexto e o .dockerignore é respeitado. Cada build bem-sucedido vira uma nova versão da mesma imagem, com o mesmo id.
3

Escreva o manifesto

Crie o vertracloud.template.yaml. O valor de source.image é o id da sua imagem; troque o id de exemplo pelo seu:
vertracloud.template.yaml
Os campos que diferem de um template de código:
source.context e digests de imagem (@sha256:...) pertencem a templates do catálogo público, onde a imagem é fixada por digest e construída a partir da pasta do template. Em um template privado, a imagem da sua conta é a origem. O último tutorial mostra como um template privado vira um template do catálogo.
4

Valide

Corrija todos os achados. Um template de imagem também pode ser recusado na criação por um motivo que o validate não enxerga, como uma imagem que não é sua (IMAGE_NOT_FOUND) ou que ainda não foi construída (IMAGE_NOT_READY).
5

Crie o template e faça o deploy

Nenhum zip é enviado: um serviço que roda uma imagem da sua conta não precisa de um. O job de deploy cria o app a partir da imagem, define as variáveis, publica o endereço, espera o /healthz e imprime as saídas. Abra o endereço e recarregue: o contador deve subir. Reinicie o app pelo painel e recarregue de novo: o número sobrevive, porque o /app é persistente.
6

Publique uma nova versão

Altere o código, execute vertra image rebuild <image-id> --context ., espere o success, aumente version no manifesto e execute vertra template create --template hello-counter --changelog "Describe the change". A nova versão do template fixa a nova versão da imagem. Os apps criados a partir do template veem “New version available” e se atualizam quando o dono escolher, com um snapshot de segurança antes.
Você não pode excluir uma imagem que é a origem da versão atual de um template privado: a requisição falha com IMAGE_IN_USE. Publique uma versão que use outra imagem ou exclua o template primeiro.

Solução de problemas

Próximos passos

Última modificação em 28 de outubro de 2026