¿Qué es un Dockerfile y cómo escribir uno?

Question

Accepted Answer

Un **Dockerfile** es un archivo de texto con instrucciones para **construir una imagen Docker** — describe la imagen base, dependencias, archivos a copiar y cómo ejecutar la aplicación. Hace que las compilaciones de imágenes sean reproducibles y controlables por versión.

## Un 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"]
```

## Instrucciones clave

```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 (comúnmente 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 qué es importante

Comprender el Dockerfile es esencial porque es la manera en que se construyen las imágenes Docker, así que escribir uno es una habilidad fundamental y cotidiana de Docker.

Un Dockerfile proporciona **compilaciones de imágenes reproducibles y controlables por versión** — describiendo en código exactamente cómo construir una imagen (la imagen base, dependencias, archivos, configuración y comando de ejecución), de modo que cualquiera pueda compilar la misma imagen consistentemente, lo cual es central para el valor de reproducibilidad de Docker.

Comprender las **instrucciones clave** — `FROM` (la imagen base), `WORKDIR`, `COPY` (trayendo archivos), `RUN` (ejecutando comandos en tiempo de compilación como instalar dependencias), `ENV`, `EXPOSE` y `CMD`/`ENTRYPOINT` (definiendo qué se ejecuta cuando inicia el contenedor) — es necesario para escribir Dockerfiles efectivos para aplicaciones reales.

Una distinción particularmente importante y comúnmente confundida es **`RUN` vs `CMD` vs `ENTRYPOINT`**: `RUN` se ejecuta en **tiempo de compilación** (construyendo la imagen, p. ej. instalando paquetes), mientras que `CMD`/`ENTRYPOINT` definen qué se ejecuta en **inicio del contenedor** (el comando de la aplicación) — entender esto previene errores comunes.

Conocer patrones prácticos (como copiar archivos de dependencias antes del código para mejor almacenamiento en caché de capas) refleja escribir Dockerfiles eficientes.

Ya que construir imágenes es fundamental para usar Docker (cada flujo de trabajo de Docker involucra imágenes, y el Dockerfile es cómo se construyen imágenes personalizadas), y ya que entender las instrucciones y la distinción tiempo-de-compilación-vs-tiempo-de-ejecución es necesario para crear imágenes correctas y eficientes, entender el Dockerfile es conocimiento Docker esencial y frecuentemente aplicado — una habilidad fundamental para cualquiera que use Docker, el mecanismo que convierte la promesa de reproducibilidad de Docker en práctica y un requisito casi universal para contenerizar aplicaciones.