Use Docker Compose Profiles to Separate Web, Worker, and Admin Services Safely

Before you begin

• A Compose project that already has more than one service role.
• Clarity about which services must always run and which are occasional.
• Modern docker compose available on the host.

Docker’s Compose documentation describes profiles as a way to adjust the application model for different use cases. Services without a profiles attribute are always enabled. Services with profiles start only when that profile is activated.

Step 1: Understand what profiles are good for

Profiles are not primarily an environment system. They are a service-selection system. They work best when you keep the core production path always-on and place optional roles behind explicit profile names.

Good candidates for profiles include:

• workers that only some deployments need
• admin tools such as migration or shell helpers
• debug tooling and local-only dashboards
• batch jobs that should not run in every environment

Step 2: Mark optional services explicitly

Keep the web app and shared dependencies unprofiled if they are always required. Then attach profiles to optional services:

services:
  web:
    image: myapp-web

  worker:
    image: myapp-worker
    profiles: ["worker"]

  admin:
    image: myapp-admin
    profiles: ["admin"]

Compose’s profile reference notes that services without profiles always start, while services with profiles activate only when the matching profile is enabled. That behavior is exactly what makes maintenance safer: optional services stay off unless you asked for them.

Step 3: Start only the service set you need

You can activate a profile from the command line:

docker compose up -d
docker compose --profile worker up -d
docker compose --profile admin run --rm admin migrate

You can also set COMPOSE_PROFILES if you want profile selection in an environment or wrapper script:

export COMPOSE_PROFILES=worker,admin
docker compose up -d

Use this deliberately. A production host that never needs the admin shell running should not quietly start it just because the file knows about it.

Step 4: Use profiles to make operations cleaner

Profiles help in real day-2 work:

• maintenance windows can leave admin-only helpers off until needed
• worker services can stay paused during certain restore or migration tasks
• local debugging tools can exist in the same file without cluttering production
• one-off commands can run through a purpose-built admin service instead of the web container

This is especially useful when paired with the maintenance guidance for pausing workers and schedulers. The cleaner the service boundaries, the less likely you are to restart everything accidentally.

Expected outcome and verification

After adopting profiles, you should be able to prove:

• docker compose up -d starts only the always-on core services
• worker or admin services remain off until a profile is selected
• operators can see clearly which role each service plays
• maintenance and one-off tasks no longer require bringing up the whole stack

docker compose ps
docker compose --profile worker config

Troubleshooting common profile mistakes

A required service no longer starts.
It was probably placed behind a profile even though the app always depends on it. Remove the profile from true core services.

Operators forget which profile to use.
Standardize profile names and document the common commands in the repo README or ops runbook.

A one-off admin command fails with missing dependencies.
Make sure the service shares the right networks, env vars, and volumes even if it is not always running.

You still keep starting everything together.
That means the profile design is not influencing behavior yet. Tighten your operational commands and wrappers so the safer path is the easy path.

What to do next

Continue with Use Multiple Docker Compose Files for Dev, Staging, and Prod.