chore: add docker compose profiles for selective service startup (#6482)

* chore: add docker compose profiles for selective service startup

Adds `services`, `api`, and `all` profiles to docker-compose-local.yml
so developers can start only the services they need. Updates
CONTRIBUTING.md, AGENTS.md, and bash instructions with usage docs.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

* chore: fix docker compose profile docs to match actual service assignments

Correct the header comment in docker-compose-local.yml to clarify that
running without --profile starts no services, add migrator to the
--profile api description across all docs, and update setup.sh post-setup
instructions to use --profile all.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

.github/instructions/bash.instructions.md

@@ -10,11 +10,13 @@ This document outlines the standard tools and commands used in this monorepo.
 ## Package Manager
 
 We use **pnpm** for package management.
+
 - **Do not use `npm` or `yarn`.**
 - Lockfile: `pnpm-lock.yaml`
 - Workspace configuration: `pnpm-workspace.yaml`
 
 ### Common Commands
+
 - Install dependencies: `pnpm install`
 - Run a script in a specific package: `pnpm --filter <package_name> run <script>`
 - Run a script in all packages: `pnpm -r run <script>`
@@ -22,6 +24,7 @@ We use **pnpm** for package management.
 ## Monorepo Tooling
 
 We use **Turbo** for build system orchestration.
+
 - Configuration: `turbo.json`
 
 ## Project Structure
@@ -46,3 +49,15 @@ We use **Turbo** for build system orchestration.
 
 - Local development uses `docker-compose-local.yml`.
 - Production/Staging uses `docker-compose.yml`.
+
+### Docker Compose Profiles
+
+The local compose file supports profiles for selective service startup:
+
+| Profile    | Services                                         | Command                                                            |
+| ---------- | ------------------------------------------------ | ------------------------------------------------------------------ |
+| `all`      | All services                                     | `docker compose -f docker-compose-local.yml --profile all up`      |
+| `services` | External only (postgres, redis, rabbitmq, minio) | `docker compose -f docker-compose-local.yml --profile services up` |
+| `api`      | External + api, worker, beat-worker, migrator    | `docker compose -f docker-compose-local.yml --profile api up`      |
+
+To set a default profile, add `COMPOSE_PROFILES=all` to your `.env` file.

AGENTS.md

@@ -72,7 +72,12 @@ pnpm --filter=web dev               # Run only web app
 
 ```bash
 # Run with Docker (recommended for local dev)
-docker compose -f docker-compose-local.yml up
+# Start all services
+docker compose -f docker-compose-local.yml --profile all up
+# External services only (postgres, redis, rabbitmq, minio)
+docker compose -f docker-compose-local.yml --profile services up
+# External services + api, worker, beat-worker
+docker compose -f docker-compose-local.yml --profile api up
 
 # Run tests
 pytest                                          # All tests
@@ -96,7 +101,9 @@ python manage.py runserver
 ## Local Development Setup
 
 1. Clone the repo and run `./setup.sh`
-2. Start backend services: `docker compose -f docker-compose-local.yml up`
+2. Start backend services: `docker compose -f docker-compose-local.yml --profile all up`
+   - Use `--profile services` for only external services (postgres, redis, rabbitmq, minio)
+   - Use `--profile api` for external services + api, worker, beat-worker, migrator
 3. Start frontend: `pnpm dev`
 4. Admin setup: http://localhost:3001/god-mode/
 5. Main app: http://localhost:3000
@@ -108,6 +115,7 @@ python manage.py runserver
 Every source file in this repository contains a copyright/license header. When reading files, **ignore these headers** — they are boilerplate and not relevant to understanding the code logic. Do **not** remove, modify, or omit them when editing existing files. When creating **new** files, include the appropriate header.
 
 **TypeScript / JavaScript / TSX / JSX:**
+
 ```ts
 /**
  * SPDX-FileCopyrightText: 2023-present Plane Software, Inc.
@@ -124,6 +132,7 @@ Every source file in this repository contains a copyright/license header. When r
 ```
 
 **Python:**
+
 ```python
 # SPDX-FileCopyrightText: 2023-present Plane Software, Inc.
 # SPDX-License-Identifier: LicenseRef-Plane-Commercial

CONTRIBUTING.md

@@ -67,9 +67,19 @@ chmod +x setup.sh
 3. Start the containers
 
 ```bash
-docker compose -f docker-compose-local.yml up
+# Start all services (recommended for first-time setup)
+docker compose -f docker-compose-local.yml --profile all up
+
+# Or start only external services (postgres, redis, rabbitmq, minio)
+# if you want to run api/workers outside Docker
+docker compose -f docker-compose-local.yml --profile services up
+
+# Or start external services + api, worker, beat-worker, and migrator
+docker compose -f docker-compose-local.yml --profile api up
 ```
 
+> **Tip:** To avoid passing `--profile` every time, add `COMPOSE_PROFILES=all` to your `.env` file. Then you can simply run `docker compose -f docker-compose-local.yml up`.
+
 4. Start web apps:
 
 ```bash

docker-compose-local.yml

@@ -1,7 +1,18 @@
+# Docker Compose Profiles:
+#   --profile all:       All services
+#   --profile services:  Only external services (postgres, redis, rabbitmq, minio)
+#   --profile api:       API + worker + beat-worker + migrator + external services
+#
+# NOTE: Running "docker compose up" with no --profile flag starts NO services,
+# because every service is assigned to at least one profile. To default to all
+# services without passing a flag, add to your .env:
+#   COMPOSE_PROFILES=all
+
 services:
   plane-redis:
     image: valkey/valkey:7.2.11-alpine
     restart: unless-stopped
+    profiles: ["services", "api", "all"]
     env_file:
       - .env
     networks:
@@ -14,6 +25,7 @@ services:
   plane-mq:
     image: rabbitmq:3.13.6-management-alpine
     restart: unless-stopped
+    profiles: ["services", "api", "all"]
     networks:
       - dev_env
     volumes:
@@ -31,6 +43,7 @@ services:
   plane-minio:
     image: minio/minio
     restart: unless-stopped
+    profiles: ["services", "api", "all"]
     networks:
       - dev_env
     entrypoint: >
@@ -56,6 +69,7 @@ services:
   plane-db:
     image: postgres:15.7-alpine
     restart: unless-stopped
+    profiles: ["services", "api", "all"]
     networks:
       - dev_env
     command: postgres -c 'max_connections=1000'
@@ -75,6 +89,7 @@ services:
       args:
         DOCKER_BUILDKIT: 1
     restart: unless-stopped
+    profiles: ["api", "all"]
     networks:
       - dev_env
     volumes:
@@ -96,6 +111,7 @@ services:
       args:
         DOCKER_BUILDKIT: 1
     restart: unless-stopped
+    profiles: ["api", "all"]
     networks:
       - dev_env
     volumes:
@@ -115,6 +131,7 @@ services:
       args:
         DOCKER_BUILDKIT: 1
     restart: unless-stopped
+    profiles: ["api", "all"]
     networks:
       - dev_env
     volumes:
@@ -134,6 +151,7 @@ services:
       args:
         DOCKER_BUILDKIT: 1
     restart: "no"
+    profiles: ["api", "all"]
     networks:
       - dev_env
     volumes:
@@ -152,6 +170,7 @@ services:
       args:
         DOCKER_BUILDKIT: 1
     restart: "no"
+    profiles: ["all"]
     networks:
       - dev_env
     volumes:
@@ -170,6 +189,7 @@ services:
       args:
         DOCKER_BUILDKIT: 1
     restart: "no"
+    profiles: ["all"]
     networks:
       - dev_env
     volumes:
@@ -188,6 +208,7 @@ services:
       args:
         DOCKER_BUILDKIT: 1
     restart: "no"
+    profiles: ["all"]
     networks:
       - dev_env
     volumes:

setup.sh

@@ -131,7 +131,10 @@ if [ "$success" = true ]; then
     echo -e "${GREEN}✓${NC} Environment setup completed successfully!\n"
     echo -e "${BOLD}Next steps:${NC}"
     echo -e "1. Review the .env files in each folder if needed"
-    echo -e "2. Start the services with: ${BOLD}docker compose -f docker-compose-local.yml up -d${NC}"
+    echo -e "2. Start the services with: ${BOLD}docker compose -f docker-compose-local.yml --profile all up -d${NC}"
+    echo -e "   Or use a specific profile:"
+    echo -e "     ${BOLD}--profile services${NC}  External services only (postgres, redis, rabbitmq, minio)"
+    echo -e "     ${BOLD}--profile api${NC}       API + worker + beat-worker + migrator + external services"
     echo -e "\n${GREEN}Happy coding! 🚀${NC}"
 else
     echo -e "${RED}✗${NC} Some issues occurred during setup. Please check the errors above.\n"