Qual é a diferença entre ENTRYPOINT e CMD?

Question

Accepted Answer

**ENTRYPOINT** e **CMD** definem o que é executado quando um contêiner é iniciado, mas servem funções diferentes e interagem de maneiras específicas. Entender a diferença (e as duas formas — exec vs shell) é importante para escrever Dockerfiles que funcionem corretamente.

## CMD — o comando padrão (substituível)

```dockerfile
CMD ["node", "server.js"]
# → the DEFAULT command when the container starts
# → but it's REPLACED if you pass a command at run time:
#   docker run myapp echo hello   → runs "echo hello" INSTEAD of node server.js
```

`CMD` fornece o **comando padrão**, que é **completamente substituído** por qualquer comando fornecido em `docker run`.

## ENTRYPOINT — o executável fixo

```dockerfile
ENTRYPOINT ["node", "server.js"]
# → ALWAYS runs; run-time arguments are APPENDED (not replacing it):
#   docker run myapp --port 8080   → runs "node server.js --port 8080"
# → makes the container behave like a specific executable
```

`ENTRYPOINT` define um **executável fixo** que sempre é executado; argumentos de tempo de execução são **anexados** como seus argumentos em vez de substituí-lo.

## Usando-os juntos (o padrão comum)

```dockerfile
ENTRYPOINT ["node", "server.js"]   # the fixed command
CMD ["--port", "3000"]              # DEFAULT arguments (overridable)
# docker run myapp                  → node server.js --port 3000 (defaults)
# docker run myapp --port 8080      → node server.js --port 8080 (CMD overridden)
→ ENTRYPOINT = the command; CMD = default arguments you can override. A clean pattern.
```

## Forma exec vs forma shell

```text
EXEC form  → CMD ["node", "server.js"]  (JSON array) — PREFERRED:
  runs the executable DIRECTLY (PID 1) → receives signals (SIGTERM) → graceful shutdown
SHELL form → CMD node server.js  → runs via /bin/sh -c → the shell is PID 1,
  the app may NOT receive signals properly (shutdown issues) → avoid for the main process
```

## Por que isso importa

Entender a diferença entre ENTRYPOINT e CMD é importante para **escrever Dockerfiles que funcionem corretamente**, portanto é um conhecimento prático valioso e um tópico comumente confundido.

A distinção no comportamento é importante: **CMD** fornece um comando padrão que é **completamente sobrescrito** por qualquer comando passado para `docker run`, enquanto **ENTRYPOINT** define um executável fixo que sempre é executado com argumentos de tempo de execução **anexados** a ele — comportamentos diferentes que afetam como o contêiner responde aos argumentos de tempo de execução.

Entender o **padrão comum de usá-los juntos** (`ENTRYPOINT` como o comando e `CMD` como argumentos padrão substituíveis) é uma abordagem limpa e idiomática que faz contêineres se comportarem como executáveis configuráveis — uma técnica amplamente utilizada que vale a pena conhecer.

Criticamente, entender a **forma exec vs forma shell** é importante para a correção: a **forma exec** (array JSON, por exemplo `CMD ["node", "server.js"]`) é preferida porque executa o executável **diretamente como PID 1**, então **recebe sinais como SIGTERM** corretamente, permitindo **encerramento elegante** — enquanto a **forma shell** (`CMD node server.js`) é executada via um shell que se torna PID 1, frequentemente fazendo com que a aplicação **não receba sinais de encerramento corretamente** (levando a encerramento não elegante, trabalho em andamento perdido ou paradas lentas).

Este problema de manipulação de sinais/encerramento elegante é um problema real e sutil que a forma exec evita.

Como definir o que é executado quando um contêiner é iniciado é fundamental para cada Dockerfile, e como a distinção ENTRYPOINT/CMD (e a preocupação com signal-handling da forma exec vs shell) afeta diretamente o comportamento e a correção do contêiner (manipulação de argumentos, encerramento elegante), entender ENTRYPOINT vs CMD — seus papéis, como se combinam, e a prática importante da forma exec para sinais — é conhecimento Docker valioso e praticamente relevante, um tópico comumente incompreendido onde entender as diferenças previne bugs reais de comportamento e encerramento.