Compose profiles for selective services in Docker - Commands & Configuration

Introduction

Sometimes you want to run only certain parts of your app depending on the situation. Compose profiles let you choose which services start, so you don't waste resources or run unnecessary parts.

When you want to run a database only during development but not in production.

When you have optional services like monitoring or debugging tools that you run only sometimes.

When you want to test a new feature service without starting the whole app.

When you want to save resources by running only the core services in a small environment.

When you want to share one compose file but run different sets of services on different machines.

Config File - docker-compose.yml

docker-compose.yml

version: '3.9'
services:
  web:
    image: nginx:1.23
    ports:
      - "8080:80"
    profiles:
      - frontend
  db:
    image: postgres:15
    environment:
      POSTGRES_PASSWORD: example
    profiles:
      - backend
  cache:
    image: redis:7
    profiles:
      - backend
  debug:
    image: busybox
    command: tail -f /dev/null
    profiles:
      - debug

This file defines four services: web, db, cache, and debug.

Each service has a profiles key listing the profiles it belongs to.

• web is in the frontend profile.
• db and cache are in the backend profile.
• debug is in the debug profile.

When you run docker compose with a profile, only services in that profile start.

Commands

This command starts only the services in the 'frontend' profile, which is the 'web' service. It runs in detached mode so the terminal is free.

Terminal

docker compose --profile frontend up -d

Expected Output

Creating network "default" with the default driver

Creating default_web_1 ... done

→

--profile - Selects which profile's services to start

→

-d - Runs containers in the background (detached mode)

Shows the list of running containers for the current compose project to verify which services are up.

Terminal

docker compose ps

Expected Output

NAME                COMMAND                  SERVICE             STATUS              PORTS

example_web_1       "nginx -g 'daemon of…"   web                 running             0.0.0.0:8080->80/tcp

Starts only the backend services: 'db' and 'cache'. Useful when you want to run database and cache without the frontend.

Terminal

docker compose --profile backend up -d

Expected Output

Creating network "default" with the default driver

Creating default_db_1 ... done

Creating default_cache_1 ... done

→

--profile - Selects which profile's services to start

→

-d - Runs containers in the background (detached mode)

Starts services in both 'frontend' and 'backend' profiles together, so web, db, and cache all run.

Terminal

docker compose --profile frontend --profile backend up -d

Expected Output

Creating network "default" with the default driver

Creating default_web_1 ... done

Creating default_db_1 ... done

Creating default_cache_1 ... done

→

--profile - You can specify multiple profiles to start multiple groups of services

→

-d - Runs containers in the background (detached mode)

Key Concept

If you remember nothing else from this pattern, remember: Compose profiles let you start only the services you need by naming groups of services and selecting them at runtime.

Common Mistakes

Not specifying any profile and expecting only some services to start

Without profiles specified, docker compose starts all services by default, ignoring profiles.

Always use --profile flag with the profile name(s) to run selective services.

Assigning a service to a profile but forgetting to include it in the command

The service won't start because its profile was not selected.

Include all needed profiles in the docker compose command using multiple --profile flags.

Using profiles with an older docker compose version that does not support them

Profiles were introduced in Docker Compose version 1.28.0; older versions ignore them.

Use Docker Compose version 1.28.0 or newer to use profiles.

Summary

Define profiles in your docker-compose.yml to group services by purpose.

Use 'docker compose --profile name up' to start only services in that profile.

You can specify multiple profiles to run multiple groups of services together.