Como a imagem é construída

A plataforma constrói a imagem da sua aplicação a partir de um Dockerfile na pasta publicada. É o único caminho de build hoje, e a interface diz isso em vez de oferecer campos que não mudam nada.

O que o Zero espera do repositório

Item	Regra
Dockerfile	Na raiz da pasta publicada. Sem ele, a publicação falha em Construindo
Pasta	A que o serviço declara dentro do repositório do projeto. Em branco, a raiz do repositório
Branch ou tag	A da origem do projeto, ou a informada naquela publicação
Porta	A aplicação deve escutar em 0.0.0.0, na porta indicada pela variável PORT

O que a plataforma não faz

• Não detecta framework. Não existe "detectamos que é Node e configuramos para você".
• Não executa buildpack. Não há construção sem Dockerfile.
• Não aceita comando de build configurável. O que constrói é o Dockerfile.

Isso está declarado aqui e na própria tela porque um formulário com esses campos criaria a expectativa de que preenchê-los muda alguma coisa.

Um Dockerfile mínimo que funciona

FROM node:22-alpine
WORKDIR /app

COPY package*.json ./
RUN npm ci --omit=dev

COPY . .

# A plataforma entrega PORT (padrão 8080). O servidor lê process.env.PORT
# e escuta em 0.0.0.0. EXPOSE não muda a porta, e USER não é necessário.
CMD ["node", "server.js"]

O que mais faz uma publicação falhar depois do build é a porta: a aplicação precisa ler PORT do ambiente e escutar em 0.0.0.0, e não fixar um número que a plataforma não conhece. EXPOSE no Dockerfile não define a porta.

Como a aplicação roda

A plataforma executa todo serviço com o mesmo contrato, qualquer que seja a imagem:

Item	Como é
Usuário	Sempre não-root, com UID e GID numéricos 10001, qualquer que seja o USER da imagem
Sistema de arquivos	Somente leitura, exceto /tmp
/tmp	Gravável, com limite de 512 MiB
HOME	Aponta para /tmp
Porta	A plataforma entrega a variável PORT com a porta do serviço — padrão 8080. Escute em 0.0.0.0 nessa porta
Pronta	A instância aceita conexão TCP na porta do serviço

Consequências práticas:

• A imagem não precisa declarar USER. Imagem sem USER — como a maioria das imagens oficiais de linguagem, por exemplo node:18-alpine — e imagem com USER por nome, como USER node, funcionam sem ajuste.
• Arquivo temporário e cache vão para /tmp. O resto do sistema de arquivos não aceita escrita enquanto a aplicação roda.
• A verificação de prontidão é TCP, não HTTP. A plataforma não sabe que caminho a sua aplicação responde, então não pergunta por um: basta aceitar conexão na porta.
• Frameworks que seguem a convenção de PORT funcionam sem configuração — Express e Node com process.env.PORT, serve, gunicorn, Rails, Spring com server.port=${PORT}.

Quando a aplicação não fica pronta, a publicação falha com o motivo e a versão anterior continua respondendo. Ver Estados da publicação.

Monorepo

Cada serviço declara a pasta que constrói dentro do repositório do projeto — por exemplo, apps/api. Na criação do projeto, é o campo Pasta dentro do repositório. O build acontece a partir dela, e é nela que o Dockerfile precisa estar.

A pasta declarada acompanha toda publicação seguinte. Uma publicação que a omitisse procuraria o Dockerfile na raiz de um repositório que o tem em outro lugar.

O log do build

A saída completa do construtor é gravada nos dois desfechos — sucesso e falha. Gravar só na falha seria a escolha óbvia e errada: quem investiga um build lento, ou um que produziu a imagem errada, precisa do log de um que deu certo.

Você o encontra em Logs → Build, escolhendo a publicação. Credenciais que apareçam na saída são protegidas antes da gravação.

O artefato

O resultado do build é um artefato imutável, identificado por uma impressão digital única. Ele nunca é reconstruído para ser reutilizado: promover uma versão para outro ambiente reutiliza exatamente o mesmo artefato. Ver Como uma publicação funciona.

Erros comuns

Sintoma	Causa	O que fazer
Dockerfile: no such file or directory no log do build	A pasta publicada não contém o Dockerfile	Corrija a pasta do serviço
Falha de autenticação ao buscar o código	Repositório privado sem token de acesso	Informe um token em Origem, no projeto
Build passa e a publicação falha com "A aplicação iniciou, mas não respondeu"	A aplicação não escuta em 0.0.0.0 na porta de PORT — por exemplo, escuta em localhost ou numa porta fixa	Leia a porta de PORT e escute em 0.0.0.0
Build passa e a publicação falha com "A aplicação parou logo depois de iniciar"	A aplicação encerra na subida — variável ausente, dependência não configurada, ou escrita fora de /tmp	Veja as últimas linhas em Logs → Runtime
Erro de dependência durante o build	Diferença entre a máquina local e o build limpo	Fixe versões; o build não reaproveita o que existe na sua máquina

Próximos passos

• Publicar
• Estados da publicação
• Logs
• Problemas comuns