CMD vs. ENTRYPOINT: Container Startup Commands

A Anatomia de um Comando de Inicialização

Quando um contêiner é iniciado, o Docker precisa saber qual processo deve ser o principal. Este processo é o "coração" do contêiner; se ele terminar, o contêiner para. As instruções CMD e ENTRYPOINT são as formas de especificar esse processo.

Antes de nos aprofundarmos, é importante conhecer as duas formas de sintaxe que ambas as instruções suportam:

1. Forma exec (preferencial): INSTRUCTION ["executável", "param1", "param2"]
   • Esta é a forma recomendada. Ela executa o comando e seus parâmetros diretamente, sem um shell intermediário.
2. Forma shell: INSTRUCTION comando param1 param2
   • Esta forma executa o comando dentro de um shell (/bin/sh -c). É mais simples para comandos básicos, mas tem implicações importantes para o gerenciamento de processos e sinais, como veremos mais adiante.

Usando CMD para Definir um Comando Padrão

A instrução CMD tem um propósito principal: fornecer um comando padrão para um contêiner em execução. A palavra-chave aqui é "padrão", pois ele é facilmente substituível.

Vamos adicionar um CMD ao nosso Dockerfile da lição anterior para que ele execute nossa API. O comando que queremos executar é dotnet /app/publish/HelloApi.dll.

Modifique seu Dockerfile para incluir a instrução CMD no final:

# Estágio 1: Build
FROM mcr.microsoft.com/dotnet/sdk:8.0
WORKDIR /app

# Otimização de cache de camadas (da lição anterior)
COPY *.csproj .
RUN dotnet restore
COPY . .

# Publica a aplicação
RUN dotnet publish -c Release -o /app/publish

# Configura a porta
ENV ASPNETCORE_URLS=http://+:8080

# --- NOVA INSTRUÇÃO ---
# Define o comando padrão para iniciar a aplicação
CMD ["dotnet", "/app/publish/HelloApi.dll"]

Agora, vamos construir e testar:

1. No seu terminal, no diretório do projeto, reconstrua a imagem com uma nova tag:

   docker build -t hello-api:2.0 .
   

2. Execute um contêiner a partir da nova imagem:

   docker run --rm -d -p 8080:8080 --name my-api hello-api:2.0
   

   • Note que não precisamos mais especificar um comando (nginx -g 'daemon off;') como fazíamos nas primeiras lições. O CMD cuidou disso.
   • Acesse http://localhost:8080 em seu navegador. Você deverá ver a mensagem "API is running!".

A Flexibilidade do CMD: Substituição

A principal característica do CMD é que qualquer comando que você passar para docker run após o nome da imagem irá substituir completamente o CMD do Dockerfile.

1. Primeiro, pare o contêiner anterior: docker stop my-api.
2. Agora, execute este comando:

   docker run --rm -it hello-api:2.0 /bin/bash
   

   O contêiner iniciará e lhe dará um prompt de shell interativo (-it) em vez de iniciar a API .NET. O comando /bin/bash substituiu ["dotnet", "/app/publish/HelloApi.dll"]. Isso é extremamente útil para depuração e inspeção.

Para uma demonstração visual dessa substituição, assista ao trecho a seguir.

Usando ENTRYPOINT para Definir o Executável Principal

A instrução ENTRYPOINT tem um propósito diferente: configurar um contêiner para ser executado como um executável específico.

Ao contrário do CMD, o ENTRYPOINT não é facilmente substituído. Em vez disso, os argumentos passados para docker run são anexados ao ENTRYPOINT.

Vamos modificar nosso Dockerfile para usar ENTRYPOINT:

# ... (instruções anteriores) ...

# Define a porta
ENV ASPNETCORE_URLS=http://+:8080

# --- MUDANÇA DE CMD PARA ENTRYPOINT ---
# Define o executável principal do contêiner
ENTRYPOINT ["dotnet", "/app/publish/HelloApi.dll"]

Construa e teste novamente:

1. Reconstrua a imagem:

   docker build -t hello-api:3.0 .
   

2. Execute o contêiner da mesma forma:
   docker run --rm -d -p 8080:8080 --name my-api hello-api:3.0
   O resultado parece o mesmo: a API inicia. A mágica acontece quando tentamos passar argumentos.

O Comportamento do ENTRYPOINT: Anexação

Vamos tentar "substituir" o comando como fizemos antes. Primeiro, pare o contêiner my-api.

docker run --rm -it hello-api:3.0 /bin/bash

Você receberá um erro! O Docker tentou executar dotnet /app/publish/HelloApi.dll /bin/bash, passando /bin/bash como um argumento para a sua API, o que não faz sentido para a aplicação.

Isso torna o ENTRYPOINT ideal para imagens que são projetadas para fazer uma coisa específica, como executar sua API ou uma ferramenta de linha de comando. Ele transforma seu contêiner em algo que se comporta como um executável.

O Melhor dos Dois Mundos: ENTRYPOINT + CMD

A combinação de ENTRYPOINT e CMD é o padrão mais poderoso e flexível. As regras são:

• ENTRYPOINT especifica o executável principal.
• CMD especifica os argumentos padrão para o ENTRYPOINT.

Isso cria um contêiner que tem um propósito fixo (o ENTRYPOINT), mas permite que o usuário substitua facilmente os argumentos padrão (o CMD).

Vamos ver um exemplo clássico. Imagine uma imagem para executar pings:

ENTRYPOINT ["ping", "-c", "3"]
CMD ["localhost"]

• Se você executar docker run <imagem>, o comando executado será ping -c 3 localhost.
• Se você executar docker run <imagem> google.com, google.com substitui o CMD e o comando executado será ping -c 3 google.com.

ENTRYPOINT ["dotnet", "MyApp.dll"]
# Qual seria a instrução CMD?

A Fundo: exec vs shell e a Importância do PID 1

Agora, vamos à parte que você, com seu background em engenharia e interesse nos mecanismos internos, achará mais interessante. Por que a forma exec (["comando", "param"]) é tão preferível à forma shell (comando param)?

A resposta está no gerenciamento de processos e sinais dentro do contêiner.

Como você leu, o processo com PID 1 em um contêiner é especial. É ele quem recebe os sinais do sistema operacional do host, como o SIGTERM que o Docker envia quando você executa docker stop. Um processo que recebe SIGTERM deve iniciar um desligamento gracioso (graceful shutdown).

• Forma shell: ENTRYPOINT /bin/sh -c "dotnet ..."

  • O shell (/bin/sh) se torna o PID 1.
  • O shell então inicia sua aplicação como um processo filho.
  • Problema: A maioria dos shells não encaminha sinais para seus filhos. Quando docker stop envia SIGTERM, o shell o recebe, mas sua aplicação .NET não. Ela continua rodando.
  • O Docker espera (por padrão, 10 segundos) e, como o contêiner não parou, ele envia um SIGKILL, que mata o processo à força. Isso impede um desligamento limpo, podendo corromper dados ou deixar conexões abertas.

• Forma exec: ENTRYPOINT ["dotnet", ...]

  • Sua aplicação (dotnet) se torna o PID 1.
  • Quando docker stop envia SIGTERM, sua aplicação o recebe diretamente.
  • O host do ASP.NET Core é projetado para lidar com SIGTERM e iniciar um desligamento gracioso. O contêiner para de forma rápida e limpa.

O blog oficial do Docker tem um excelente artigo que aprofunda essa distinção.

O artigo também inclui um fluxograma útil para ajudar a decidir qual forma usar.

Conclusão

Nesta lição, você aprendeu a diferença fundamental entre CMD e ENTRYPOINT e, mais importante, as implicações de como você os escreve.

Principais pontos a reter:

• CMD define um comando padrão e facilmente substituível. Ideal para dar flexibilidade ao usuário da imagem.
• ENTRYPOINT define o executável principal do contêiner, transformando-o em uma ferramenta específica. Argumentos de docker run são anexados a ele.
• A combinação ENTRYPOINT ["executável"] e CMD ["argumento-padrão"] é o padrão mais robusto e flexível.
• A forma exec (["...", "..."]) é crucial para aplicações de produção, pois permite que sua aplicação se torne PID 1 e lide corretamente com sinais do sistema (como SIGTERM), garantindo desligamentos graciosos.

Nosso Dockerfile para a API .NET está agora mais robusto, usando ENTRYPOINT ["dotnet", "/app/publish/HelloApi.dll"]. No entanto, se você olhar o tamanho da nossa imagem (docker images hello-api), verá que ela é bem grande. Isso ocorre porque ela inclui todo o SDK do .NET, que é necessário para compilar, mas não para executar a aplicação.

Na próxima lição, vamos resolver esse problema. Você aprenderá a implementar builds de múltiplos estágios (multi-stage builds), uma técnica poderosa para criar imagens de produção pequenas e seguras, separando o ambiente de compilação do ambiente de execução.