Ir al contenido
Fundamentos de Docker

Conceptos 01 - Anatomía del archivo compose.yml

Estructura, claves de configuración y comportamiento de red en Docker Compose. Recorra cada sección para ver ejemplos y explicaciones detalladas.

  • 10 conceptos en 3 partes
  • 6 elementos interactivos
  • Autoevaluación final
Parte 1

Estructura

Concepto 1 de 10

El archivo compose.yml

Documento YAML que describe la aplicación multicontenedor. Compose lo busca automáticamente en el directorio de trabajo actual.

El archivo compose.yml (también aceptado como docker-compose.yml) se ubica habitualmente en la raíz del proyecto. Define los servicios, volúmenes y redes que componen la aplicación.

# Estructura típica del proyecto
mi-proyecto/
├── app/
│   ├── main.py
│   └── requirements.txt
├── Dockerfile
├── docker-compose.yml
└── .env

Concepto 2 de 10

Ejemplo completo con tres servicios

Aplicación Flask + PostgreSQL + Adminer. Ilustra las claves más frecuentes de un archivo Compose.

Seleccione un servicio o un bloque para resaltarlo en el archivo.

Aplicación Flask. Se construye a partir del Dockerfile del proyecto (build: .), publica el puerto 8000, arma DATABASE_URL con variables del .env y depende de db.

compose.ymlservices:  web:    build: .    ports:      - "8000:8000"    environment:      - DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}    depends_on:      - db    restart: unless-stopped   db:    image: postgres:16    environment:      - POSTGRES_USER=${POSTGRES_USER}      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}      - POSTGRES_DB=${POSTGRES_DB}    volumes:      - pgdata:/var/lib/postgresql/data    restart: unless-stopped   adminer:    image: adminer    ports:      - "8080:8080"    depends_on:      - db    restart: unless-stopped volumes:  pgdata:

Concepto 3 de 10

Bloques principales del archivo

Los bloques de nivel superior que componen la estructura del archivo Compose.

services

Define los componentes de la aplicación. Cada clave es un nombre de servicio que se convierte en hostname dentro de la red interna.

volumes

Declara volúmenes nombrados gestionados por Docker. Existen independientemente del ciclo de vida de los contenedores.

networks

Define redes explícitas. Si no se declara, Compose crea automáticamente una red por defecto para el proyecto.

Parte 2

Claves de configuración

Concepto 4 de 10

Claves frecuentes dentro de un servicio

Las opciones de configuración más utilizadas al definir un servicio en Compose.

Seleccione una clave para ver su función y resaltar dónde aparece en el ejemplo completo.

Construye la imagen a partir de un Dockerfile en la ruta especificada.

compose.ymlservices:  web:    build: .    ports:      - "8000:8000"    environment:      - DATABASE_URL=postgresql://${POSTGRES_USER}:${POSTGRES_PASSWORD}@db:5432/${POSTGRES_DB}    depends_on:      - db    restart: unless-stopped   db:    image: postgres:16    environment:      - POSTGRES_USER=${POSTGRES_USER}      - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}      - POSTGRES_DB=${POSTGRES_DB}    volumes:      - pgdata:/var/lib/postgresql/data    restart: unless-stopped   adminer:    image: adminer    ports:      - "8080:8080"    depends_on:      - db    restart: unless-stopped volumes:  pgdata:

Concepto 5 de 10

Diferencia entre build e image

Dos formas de especificar la imagen de un servicio con propósitos y comportamientos distintos.

build

Indica cómo construir la imagen a partir del código fuente. build: . usa el directorio actual como contexto y busca el Dockerfile allí. Se emplea en servicios desarrollados como parte del proyecto.

Qué indica
Cómo construir la imagen a partir del código fuente
Origen
Un contexto local con su Dockerfile (build: .)
Uso típico
Servicios desarrollados como parte del proyecto

image

Indica qué imagen debe ejecutar el servicio. Puede provenir de un registry como postgres:16 o corresponder al nombre de una imagen construida localmente.

Qué indica
Qué imagen debe ejecutar el servicio
Origen
Un registry (postgres:16) o una imagen construida localmente
Uso típico
Servicios de terceros o imágenes ya construidas

Concepto 6 de 10

Volúmenes nombrados en el nivel superior

Desacoplan la persistencia de datos del ciclo de vida del contenedor.

services:
  db:
    image: postgres:16
    volumes:
      - pgdata:/var/lib/postgresql/data


# Nivel superior: declara el volumen nombrado
volumes:
  pgdata:

Compare qué ocurre con los datos de un servicio al eliminar y volver a crear su contenedor, con y sin volumen nombrado.

Contenedor proyecto-app-1
Capa escribible: 
Volumen proyecto_datos
Contenido: 
Guarde algunos registros y luego elimine y vuelva a crear el contenedor.
Concepto 7 de 10
Variables de entorno y archivo .env
Compose carga automáticamente las variables del archivo .env ubicado en el mismo directorio.
.env
POSTGRES_USER=admin
POSTGRES_PASSWORD=secret
POSTGRES_DB=myapp
# compose.yml — las variables ${...} se resuelven desde .env
environment:
  - POSTGRES_USER=${POSTGRES_USER}
  - POSTGRES_PASSWORD=${POSTGRES_PASSWORD}
La interpolación y la precedencia de variables se exploran en detalle en Conceptos 04.
Parte 3
Redes y dependencias
Concepto 8 de 10
depends_on y sus límites
Ordena el arranque pero no garantiza disponibilidad funcional del servicio dependiente.
depends_on indica que Compose debe crear primero el servicio del cual otro depende. Sin embargo, un contenedor en ejecución no implica que el servicio interno esté listo para aceptar conexiones.
depends_on:
  - db
depends_on:
  db:
    condition: service_healthy


# En el servicio db:
healthcheck:
  test: ["CMD-SHELL", "pg_isready -U ${POSTGRES_USER}"]
  interval: 5s
  timeout: 3s
  retries: 5
Avance paso a paso para comparar el arranque de web y db con cada forma de depends_on.
db—
web—
Ejecute docker compose up y avance paso a paso.
Los pasos son ilustrativos: los tiempos reales dependen del equipo y del servicio.
Concepto 9 de 10
Redes implícitas
Compose crea automáticamente una red por defecto y conecta a ella todos los servicios del proyecto.
mi-proyecto_default (red creada automáticamente)
web
Accede a db por hostname
db
Puerto 5432 interno
adminer
Accede a db por hostname
Los servicios se comunican usando el nombre del servicio como hostname dentro de la red interna. No es necesario gestionar direcciones IP manualmente.
Concepto 10 de 10
Redes explícitas para aislamiento
Permiten segmentar la comunicación entre servicios cuando se requiere mayor control.
services:
  web:
    networks:
      - frontend
      - backend
  db:
    networks:
      - backend
  adminer:
    networks:
      - backend


networks:
  frontend:
  backend:
frontend
web
backend
web, db, adminer
Active o desactive la pertenencia de cada servicio a cada red y observe qué pares pueden comunicarse. Un servicio sin redes explícitas queda conectado a la red default del proyecto.
    Autoevaluación
    Comprueba lo que aprendiste
    Cinco preguntas rápidas para verificar las ideas clave de la lectura. Cada respuesta incluye una explicación.
    1. 1¿Qué garantiza depends_on en su forma básica?
    2. 2¿Qué ocurre con un volumen nombrado al ejecutar docker compose down?
    3. 3¿Qué indica la clave build en un servicio?
    4. 4En la red por defecto de Compose, ¿cómo se conecta web con la base de datos?
    5. 5En el ejemplo de redes explícitas, ¿por qué db no tiene acceso directo a la red frontend?
    0/5 respuestas correctas