O que é um Dockerfile e como você escreve um?

Question

Accepted Answer

Um **Dockerfile** é um arquivo de texto com instruções para **construir uma imagem Docker** — ele descreve a imagem base, dependências, arquivos a copiar e como executar a aplicação. Torna as compilações de imagem reproduzíveis e controláveis por versão.

## Um Dockerfile básico

```dockerfile
# FROM — the base image to build on
FROM node:20-alpine

# WORKDIR — set the working directory inside the image
WORKDIR /app

# COPY dependency files first (for better layer caching)
COPY package*.json ./
# RUN — execute a command during the BUILD (install dependencies)
RUN npm install

# COPY the rest of the application code
COPY . .

# EXPOSE — document the port the app listens on
EXPOSE 3000

# CMD — the command to run when a CONTAINER starts
CMD ["node", "server.js"]
```

## Instruções principais

```text
FROM     → the base image (starting point) — REQUIRED, usually first
WORKDIR  → set the working directory for subsequent instructions
COPY/ADD → copy files from the host into the image
RUN      → execute a command at BUILD time (install packages, compile) → creates a layer
ENV      → set environment variables
EXPOSE   → document which port(s) the container listens on
CMD      → the default command to run when the container STARTS (one per Dockerfile)
ENTRYPOINT → the executable that runs (CMD provides default args to it)
ARG      → build-time variables
```

## RUN vs CMD vs ENTRYPOINT (frequentemente confundidos)

```text
RUN        → runs at BUILD time (builds the image — e.g. install dependencies)
CMD        → runs at CONTAINER START (the default command; overridable at run)
ENTRYPOINT → the main executable at start (CMD becomes its default arguments)
→ RUN builds the image; CMD/ENTRYPOINT define what runs when it starts.
```

## Por que isso importa

Entender o Dockerfile é essencial porque é como as imagens Docker são construídas, então escrever um é uma habilidade fundamental e cotidiana do Docker.

Um Dockerfile fornece **compilações de imagem reproduzíveis e controláveis por versão** — descrevendo em código exatamente como construir uma imagem (a imagem base, dependências, arquivos, configuração e comando de execução), para que qualquer pessoa possa construir a mesma imagem consistentemente, o que é central para o valor de reprodutibilidade do Docker.

Entender as **instruções principais** — `FROM` (a imagem base), `WORKDIR`, `COPY` (trazendo arquivos), `RUN` (executando comandos em tempo de compilação, como instalação de dependências), `ENV`, `EXPOSE` e `CMD`/`ENTRYPOINT` (definindo o que é executado quando o contêiner é iniciado) — é necessário para escrever Dockerfiles eficazes para aplicações reais.

Uma distinção particularmente importante e frequentemente confundida é **`RUN` vs `CMD` vs `ENTRYPOINT`**: `RUN` executa em **tempo de compilação** (construindo a imagem, ex: instalação de pacotes), enquanto `CMD`/`ENTRYPOINT` definem o que é executado no **início do contêiner** (o comando da aplicação) — entender isso previne erros comuns.

Conhecer padrões práticos (como copiar arquivos de dependência antes do código para melhor cache de camadas) reflete a escrita de Dockerfiles eficientes.

Como construir imagens é fundamental para usar Docker (todo fluxo de trabalho Docker envolve imagens, e o Dockerfile é como imagens personalizadas são construídas), e como entender as instruções e a distinção entre tempo de compilação versus tempo de execução é necessário para criar imagens corretas e eficientes, entender o Dockerfile é conhecimento Docker essencial e frequentemente aplicado — uma habilidade central para qualquer pessoa usando Docker, o mecanismo que transforma a promessa de reprodutibilidade do Docker em prática e um requisito quase universal para containerizar aplicações.