Usar perfiles con Compose

Los perfiles (profiles) te ayudan a adaptar tu aplicación de Compose para diferentes entornos o casos de uso activando servicios de forma selectiva. Los servicios se pueden asignar a uno o más perfiles; los servicios no asignados se inician/detienen de forma predeterminada, mientras que los asignados solo lo hacen cuando su perfil está activo. Con esta configuración, puedes incluir servicios específicos, como aquellos de depuración o desarrollo, en un único archivo compose.yml y activarlos solo según sea necesario.

Asignar perfiles a los servicios

Los servicios se asocian con perfiles a través del atributo profiles, el cual toma un array de nombres de perfiles:

services:
  frontend:
    image: frontend
    profiles: [frontend]

  phpmyadmin:
    image: phpmyadmin
    depends_on: [db]
    profiles: [debug]

  backend:
    image: backend

  db:
    image: mysql

Aquí, a los servicios frontend y phpmyadmin se les asignan los perfiles frontend y debug respectivamente, por lo que solo se inician cuando se habilitan sus respectivos perfiles.

Los servicios sin el atributo profiles siempre están habilitados. En este caso, al ejecutar docker compose up solo se iniciarían backend y db.

Los nombres de perfil válidos siguen el formato regex de [a-zA-Z0-9][a-zA-Z0-9_.-]+.

Tip

Los servicios principales de tu aplicación no deberían tener profiles asignados, de modo que siempre estén habilitados y se inicien automáticamente.

Iniciar perfiles específicos

Para iniciar un perfil específico, proporciona la opción de línea de comandos --profile o utiliza la variable de entorno COMPOSE_PROFILES:

$ docker compose --profile debug up

$ COMPOSE_PROFILES=debug docker compose up

Ambos comandos inician los servicios con el perfil debug habilitado. En el archivo compose.yaml anterior, esto inicia los servicios db, backend y phpmyadmin.

Iniciar múltiples perfiles

También puedes habilitar múltiples perfiles; por ejemplo, con docker compose --profile frontend --profile debug up se habilitarán los perfiles frontend y debug.

Se pueden especificar múltiples perfiles pasando varias banderas --profile o una lista separada por comas en la variable de entorno COMPOSE_PROFILES:

$ docker compose --profile frontend --profile debug up

$ COMPOSE_PROFILES=frontend,debug docker compose up

Si deseas habilitar todos los perfiles al mismo tiempo, puedes ejecutar docker compose --profile "*".

Inicio automático de perfiles y resolución de dependencias

Cuando te diriges explícitamente a un servicio en la línea de comandos que tiene uno o más perfiles asignados, no necesitas habilitar el perfil manualmente, ya que Compose ejecuta ese servicio independientemente de si su perfil está activado. Esto es útil para ejecutar servicios únicos (one-off) o herramientas de depuración.

Solo se inicia el servicio seleccionado (y cualquiera de sus dependencias declaradas mediante depends_on). Los demás servicios que comparten el mismo perfil no se iniciarán a menos que:

• También se seleccionen explícitamente, o
• El perfil se habilite explícitamente mediante --profile o COMPOSE_PROFILES.

Cuando se selecciona explícitamente en la línea de comandos un servicio con perfiles asignados, sus perfiles se inician automáticamente, por lo que no es necesario iniciarlos manualmente. Esto se puede utilizar para servicios únicos y herramientas de depuración. Como ejemplo, considera la siguiente configuración:

services:
  backend:
    image: backend

  db:
    image: mysql

  db-migrations:
    image: backend
    command: myapp migrate
    depends_on:
      - db
    profiles:
      - tools

# Solo iniciar backend y db (sin perfiles involucrados)
$ docker compose up -d

# Ejecutar el servicio db-migrations sin habilitar manualmente el perfil 'tools'
$ docker compose run db-migrations

En este ejemplo, db-migrations se ejecuta aunque esté asignado al perfil tools, porque fue seleccionado explícitamente. El servicio db también se inicia automáticamente porque está listado en depends_on.

Si el servicio seleccionado tiene dependencias que también están limitadas por un perfil, debes asegurarte de que esas dependencias estén:

• En el mismo perfil
• Se inicien por separado
• No estén asignadas a ningún perfil para que siempre estén habilitadas

Detener la aplicación y los servicios con perfiles específicos

Al igual que para iniciar perfiles específicos, puedes usar la opción de línea de comandos --profile o utilizar la variable de entorno COMPOSE_PROFILES:

$ docker compose --profile debug down

$ COMPOSE_PROFILES=debug docker compose down

Ambos comandos detienen y eliminan los servicios con el perfil debug y los servicios sin perfil. En el siguiente archivo compose.yaml, esto detiene los servicios db, backend y phpmyadmin.

services:
  frontend:
    image: frontend
    profiles: [frontend]

  phpmyadmin:
    image: phpmyadmin
    depends_on: [db]
    profiles: [debug]

  backend:
    image: backend

  db:
    image: mysql

Si solo deseas detener el servicio phpmyadmin, puedes ejecutar:

$ docker compose down phpmyadmin

o

$ docker compose stop phpmyadmin

Note

Ejecutar docker compose down solo detiene backend and db.

Información de referencia

• profiles