Toda la aplicación en un archivo

De docker run a docker-compose.yml

Una aplicación real tiene varios servicios: la API, su base de datos, quizá una caché. Levantarlos a mano significa crear la red, el volumen y escribir varias órdenes largas en el orden correcto, cada vez. Docker Compose describe todo eso en un archivo YAML y lo levanta con una sola orden.

services:
  app:
    build: .                    # construye con el Dockerfile de esta carpeta
    ports:
      - "3000:3000"
    environment:
      DB_HOST: db               # el nombre del servicio es su nombre en la red
    depends_on:
      - db                      # arranca db antes que app
  db:
    image: postgres:15.1
    environment:
      POSTGRES_PASSWORD: ${DB_PASSWORD}   # se toma del archivo .env
    volumes:
      - datos:/var/lib/postgresql/data

volumes:
  datos:                        # volumen con nombre, declarado aquí

Cada clave bajo services es un servicio, y cada servicio equivale a un docker run. Las versiones viejas del archivo empezaban con una línea version: "3.8"; hoy esa línea está obsoleta, Compose la ignora y solo muestra una advertencia, así que puedes quitarla.

En YAML la sangría es la estructura: se usan espacios (nunca tabulaciones), una lista se escribe con guiones y un mapa con clave: valor. Un espacio de más o de menos cambia el significado.

up, ps, logs, down

docker compose up -d      # crea red, volúmenes y contenedores, y los arranca
docker compose ps         # estado de los servicios del proyecto
docker compose logs -f    # logs de todos, con el nombre del servicio delante
docker compose down       # detiene y borra contenedores y la red
docker compose down -v    # … y también los volúmenes (¡borra los datos!)

Compose agrupa todo bajo un proyecto, que por defecto se llama como la carpeta. Los contenedores se nombran proyecto-servicio-1 y la red proyecto_default. En esa red, cada servicio se encuentra por el nombre de su servicio: la API se conecta a db:5432 sin que tengas que crear la red ni poner alias.

depends_on solo ordena el arranque: garantiza que el contenedor de la base arrancó, no que ya esté lista para aceptar conexiones. Una aplicación robusta reintenta la conexión unos segundos; Compose también permite esperar a un healthcheck.

Variables con .env

El docker-compose.yml se sube al repositorio para que todo el equipo use la misma configuración; las contraseñas, no. Compose lee automáticamente un archivo .env en la misma carpeta y reemplaza cada ${VARIABLE} del YAML por su valor. El .env va en el .gitignore, y en el repositorio se deja un .env.example con los nombres de las variables y valores de ejemplo.

Antes de leer la respuesta