Using profiles with Compose

Estimated reading time: 4 minutes

Profiles allow adjusting the Compose application model for various usages and environments by selectively enabling services. This is achieved by assigning each service to zero or more profiles. If unassigned, the service is always started but if assigned, it is only started if the profile is activated.

This allows one to define additional services in a single docker-compose.yml file that should only be started in specific scenarios, e.g. for debugging or development tasks.

Assigning profiles to services

Services are associated with profiles through the profiles attribute which takes an array of profile names:

version: "3.9"
services:
  frontend:
    image: frontend
    profiles: ["frontend"]

  phpmyadmin:
    image: phpmyadmin
    depends_on:
      - db
    profiles:
      - debug

  backend:
    image: backend

  db:
    image: mysql

Here the services frontend and phpmyadmin are assigned to the profiles frontend and debug respectively and as such are only started when their respective profiles are enabled.

Services without a profiles attribute will always be enabled, i.e. in this case running docker-compose up would only start backend and db.

Valid profile names follow the regex format of [a-zA-Z0-9][a-zA-Z0-9_.-]+.

Note

The core services of your application should not be assigned profiles so they will always be enabled and automatically started.

Enabling profiles

To enable a profile supply the --profile command-line option or use the COMPOSE_PROFILES environment variable:

$ docker-compose --profile debug up
$ COMPOSE_PROFILES=debug docker-compose up

The above command would both start your application with the debug profile enabled. Using the docker-compose.yml file above, this would start the services backend, db and phpmyadmin.

Multiple profiles can be specified by passing multiple --profile flags or a comma-separated list for the COMPOSE_PROFILES environment variable:

$ docker-compose --profile frontend --profile debug up
$ COMPOSE_PROFILES=frontend,debug docker-compose up

Auto-enabling profiles and dependency resolution

When a service with assigned profiles is explicitly targeted on the command line its profiles will be enabled automatically so you don’t need to enable them manually. This can be used for one-off services and debugging tools. As an example consider this configuration:

version: "3.9"
services:
  backend:
    image: backend

  db:
    image: mysql

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

# will only start backend and db
$ docker-compose up -d

# this will run db-migrations (and - if necessary - start db)
# by implicitly enabling profile `tools`
$ docker-compose run db-migrations

But keep in mind that docker-compose will only automatically enable the profiles of the services on the command line and not of any dependencies. This means that all services the targeted service depends_on must have a common profile with it, be always enabled (by omitting profiles) or have a matching profile enabled explicitly:

version: "3.9"
services:
  web:
    image: web

  mock-backend:
    image: backend
    profiles: ["dev"]
    depends_on:
      - db

  db:
    image: mysql
    profiles: ["dev"]

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

# will only start "web"
$ docker-compose up -d

# this will start mock-backend (and - if necessary - db)
# by implicitly enabling profile `dev`
$ docker-compose up -d mock-backend

# this will fail because profile "dev" is disabled
$ docker-compose up phpmyadmin

Although targeting phpmyadmin will automatically enable its profiles - i.e. debug - it will not automatically enable the profile(s) required by db - i.e. dev. To fix this you either have to add the debug profile to the db service:

db:
  image: mysql
  profiles: ["debug", "dev"]

or enable a profile of db explicitly:

# profile "debug" is enabled automatically by targeting phpmyadmin
$ docker-compose --profile dev up phpmyadmin
$ COMPOSE_PROFILES=dev docker-compose up phpmyadmin

Compose documentation

• User guide
• Installing Compose
• Getting Started
• Command line reference
• Compose file reference
• Sample apps with Compose