Imagens Docker personalizadas

Envie um projeto com um Dockerfile e a Vertra Cloud constrói a imagem em um ambiente de build isolado. Depois, você cria aplicações a partir dessa imagem. Use quando o catálogo de linguagens não cobre o que você precisa: outra linguagem ou versão, pacotes do sistema, seu próprio processo de start ou aplicações prontas. Imagens personalizadas estão disponíveis no Enterprise 28, Enterprise 30 e Enterprise 32. As imagens e aplicações que você já tem continuam rodando se você migrar para um plano sem o recurso, mas não é possível criar nem fazer rebuild de imagens até voltar para um desses planos. Excluir é sempre permitido.

​

Requisitos

• Um arquivo ZIP de até 100 MB, ou um repositório do GitHub (a branch é opcional; sem ela, usa-se a branch padrão do repositório). O contexto também precisa ficar abaixo de 512 MB descompactado e 50.000 entradas, e o Dockerfile, abaixo de 1 MB. Acima de qualquer um desses limites, a requisição falha com IMAGE_CONTEXT_TOO_LARGE.
• Um arquivo com o nome exato Dockerfile na raiz do projeto. Uma única pasta envolvendo o projeto inteiro é aceita.
• Uma imagem linux/amd64. Outras arquiteturas não são suportadas.
• Até 20 imagens por conta, contando imagens em qualquer estado (building, success ou failed). Rebuilds, commits e versões não contam.

Arquivos .env* são sempre removidos do contexto de build, e o .dockerignore é respeitado. O seu Dockerfile é usado exatamente como você escreveu: nada é reescrito. Variáveis de ambiente não ficam disponíveis durante o build; defina-as na aplicação.

​

Limites do build

Cada build roda no seu próprio ambiente de build isolado, com os mesmos limites do build de uma aplicação comum:

• RAM de 2x a RAM por app do plano, com mínimo de 1.024 MB e máximo de 4.096 MB.
• Um limite de tempo de 26 minutos.
• A imagem final pode ter no máximo 10 GB descompactada. Uma imagem maior falha com IMAGE_TOO_LARGE.

Rebuilds que só mudam o seu código terminam mais rápido que o primeiro build.

​

O que é recusado e o que gera aviso

Antes do build, o Dockerfile é verificado, no painel e de novo no servidor. Recusas bloqueiam o build: Avisos não bloqueiam o build: Você pode rodar a mesma verificação pela API com Verificar Dockerfile.

​

Como a aplicação roda

A aplicação roda com o mesmo isolamento de qualquer outra aplicação da plataforma.

• Caminhos graváveis. /app é o disco persistente do app (cota, gerenciador de arquivos, snapshots). /tmp, /var/tmp e /run são graváveis, mas temporários: são limpos quando o app reinicia. O resto é somente leitura. Uma imagem que escreve em outro lugar falha, então aponte logs, caches e dados para /app. A aba Arquivos do app mostra /app, não o código dentro da imagem.
• Usuário. O app sempre roda como usuário 1000:1000. A instrução USER do Dockerfile é ignorada, então uma imagem que precisa de root para escrever fora dos caminhos acima não roda.
• Comando. O ENTRYPOINT e o CMD da imagem. Não são configuráveis.
• Instruções ignoradas. HEALTHCHECK é ignorado. EXPOSE apenas sugere a porta.

​

Porta e PORT

Só apps web têm porta. Ao criar o app, o padrão é o primeiro EXPOSE do Dockerfile, ou 80 quando não há nenhum. A imagem devolve esse valor como suggested_port em Obter imagem. A plataforma injeta-o como a variável de ambiente PORT e roteia o tráfego para ele, então o seu servidor deve escutar em PORT. Um app criado com web desligado (um bot ou um worker) não tem porta nem subdomínio. Você pode publicá-lo na web depois com Publicar aplicação, informando em port a porta em que a imagem escuta; sem ela, a chamada falha com IMAGE_APP_PORT_REQUIRED.

​

Variáveis de ambiente

As variáveis são definidas por aplicação, nunca na imagem, então vários apps podem rodar a partir de uma mesma imagem com valores diferentes. As chaves do arquivo .env do seu projeto podem ser usadas para pré-preencher as variáveis ao criar o app. Os valores delas nunca entram na imagem.

​

Criar uma imagem e um app

Se você enviar um projeto que tem um Dockerfile no fluxo comum de criação de app, o painel oferece criar uma imagem a partir do mesmo arquivo, sem novo upload.

​

Atualizar uma imagem

Você pode renomear uma imagem e dar a ela uma descrição (até 128 caracteres) no painel ou com Atualizar imagem; nada é construído nem reiniciado. Cada build bem-sucedido vira uma nova versão da mesma imagem, com o mesmo ID. Só um build roda por vez em cada imagem: um segundo pedido responde IMAGE_BUILD_IN_PROGRESS.

• Rebuild por upload. Envie um contexto completo novo com Atualizar imagem ou Rebuild da imagem. Ele substitui o contexto inteiro.
• Commit. Um commit em um app que roda a partir de uma imagem (painel, vertra app commit ou a GitHub Action) coloca os seus arquivos sobre o contexto atual e reconstrói a imagem. Como a imagem é compartilhada, o painel avisa quantos apps a usam antes de você confirmar. Só o app que recebeu o commit reinicia, e só quando você pediu reinício.
• GitHub. Vincule a imagem a um repositório das suas instalações do GitHub App. A branch é opcional (padrão: a branch padrão do repositório). Só o dono da imagem pode vincular ou desvincular (em um workspace, membros recebem 403). Cada push para essa branch reconstrói a imagem, igual a um rebuild manual. Uma imagem construída uma vez a partir de um repositório público não fica vinculada até você fazer isso. Desvincule a qualquer momento.
• GitHub Action. Use o input image-id em vez de app-id para reconstruir uma imagem no seu workflow. Com o app-id de um app que roda a partir de uma imagem, o deploy é um commit, como descrito acima. Veja GitHub Actions.

Um rebuild nunca reinicia as suas aplicações. Um build que falha não muda a versão atual: os apps continuam rodando a última que deu certo. Você pode ler o contexto atual com Baixar contexto da imagem.

​

Quando um app passa para uma nova versão

Um app só muda de versão quando você pede: um restart ou deploy pelo painel, pela API ou pela CLI (incluindo --restart em um commit). Tudo o que a plataforma faz sozinha, como recuperar-se de uma falha, recriar o container ou fazer um rollback automático, mantém a versão da release atual. Enquanto o app estiver atrasado, o painel mostra que há uma versão mais nova disponível, e a API marca isso com outdated: true.

​

Versões e rollback

Liste as versões com Listar versões da imagem. Cada uma registra o digest, a origem (upload, commit ou github), a mensagem e se algum app a está usando. Cada release de um app aponta para uma versão da imagem e para as variáveis com que ela começou. As aplicações mantêm até 30 releases por 30 dias nos planos Enterprise. Fazer rollback de um app inicia uma versão que já foi construída, então é instantâneo e não precisa de rebuild. Veja Rollback e deploys sem downtime. Uma versão só é removida quando nenhuma release de nenhum app a usa e ela não é a atual.

​

Snapshots e backups

Um snapshot de um app que roda a partir de uma imagem guarda os dados de /app, além de uma nota com a imagem e a versão em que ele estava rodando. A imagem em si não fica dentro do snapshot: o código dela já tem seu próprio histórico nas versões.

• O agendamento, a retenção, a cota e o download funcionam como em qualquer outra aplicação.
• Restaurar substitui os dados de /app e mantém a versão atual da imagem. Se a versão registrada no snapshot ainda existir, você pode escolher voltar também para essa versão, o que restaura dados e código daquele momento. Se a versão já tiver sido removida, só os dados são restaurados, e você é avisado.
• Um snapshot não impede que uma versão seja removida.
• Criar um app a partir de um snapshot o cria na mesma imagem. Se a imagem não existir mais, a requisição é recusada.

​

Excluir uma imagem

Excluir uma imagem remove as versões dela, o contexto e todas as aplicações criadas a partir dela. Você confirma digitando o nome da imagem (confirm_name em Excluir imagem). A exclusão é bloqueada enquanto um build estiver em execução. Cada app excluído segue as regras usuais de exclusão de aplicação, incluindo o snapshot de segurança nos planos que o têm. Com uma chave de API, excluir uma imagem que tem apps também exige o scope apps:delete.

​

Imagens em workspaces

Imagens podem pertencer a um workspace, como as aplicações. A imagem sempre pertence ao dono do workspace, cujo plano e limites valem; só o dono cria imagens no workspace e as vincula ao GitHub. Membros usam as permissões de aplicação: ver uma imagem exige a permissão de ver apps, renomear e fazer rebuild exigem a permissão de gerenciar apps, e excluir exige a permissão de excluir apps. Quando uma imagem também roda aplicações fora do workspace, membros não podem fazer rebuild, commit nem excluí-la.

​

Chaves de API

As imagens têm scopes próprios: images:read para listar, ler, ver versões, logs, contexto e a verificação; images:write para criar, renomear, fazer rebuild e vincular ao GitHub; e images:delete para excluir. Excluir uma imagem que tem apps também exige apps:delete, porque os apps são excluídos junto, e enviar arquivos para um app que roda uma imagem (um commit que reconstrói a imagem) exige images:write além de apps:files. Criar um app a partir de uma imagem usa apps:write.

​

Erros

Veja Erros para os status HTTP.