chore: consolidate docker scripts into single docker-compose with profiles (#15974)

Replaces 18 docker scripts and 4 separate docker-compose files with 3
scripts and 1 unified compose file using Docker Compose profiles.

```
pnpm docker:start  # Nuke volumes + start all services fresh
pnpm docker:stop   # Stop everything
pnpm docker:test   # Test database connections
```

The goal is one single command that covers 99% of cases: `pnpm
docker:start`. Running it gives you all services started clean, with no
leftover data from previous runs. No more looking through `package.json`
for the right `docker:mongodb:start` or `docker:postgres:restart:clean`
- just one command.

Docker Compose starts all services in parallel, so there's no
performance overhead compared to the old targeted commands.

<img width="1284" height="922" alt="screenshot 2026-03-16 at 17 11
44@2x"
src="https://github.com/user-attachments/assets/56c35547-5b82-496e-9200-cb43982c0dad"
/>

All services (PostgreSQL, MongoDB, mongot, MongoDB Atlas Local,
LocalStack, Azure Storage, GCS) now show grouped under a single
`payload-monorepo` project in Docker Desktop / Orbstack, as seen in the
screenshot.

All services are defined in `test/docker-compose.yml` with profiles
(`postgres`, `mongodb`, `mongodb-atlas`, `storage`, `all`). CI uses
individual profiles to start only what it needs.

Author: AlessioGr

.github/actions/start-database/action.yml

@@ -25,23 +25,23 @@ runs:
       if: contains(fromJSON('["mongodb", "cosmosdb", "documentdb", "firestore"]'), inputs.database)
       shell: bash
       run: |
-        docker compose -f test/__helpers/shared/db/mongodb/docker-compose.yml up -d --wait
+        docker compose -f test/docker-compose.yml --profile mongodb up -d --wait
         echo "url=mongodb://payload:payload@localhost:27018/payload?authSource=admin&directConnection=true&replicaSet=rs0" >> $GITHUB_OUTPUT
 
     - name: Start MongoDB Atlas Local
       id: mongodb-atlas
       if: inputs.database == 'mongodb-atlas'
       shell: bash
       run: |
-        docker compose -f test/__helpers/shared/db/mongodb-atlas/docker-compose.yml up -d --wait
+        docker compose -f test/docker-compose.yml --profile mongodb-atlas up -d --wait
         echo "url=mongodb://localhost:27019/payload?directConnection=true&replicaSet=mongodb-atlas-local" >> $GITHUB_OUTPUT
 
     - name: Start PostgreSQL
       id: postgres
       if: startsWith(inputs.database, 'postgres')
       shell: bash
       run: |
-        docker compose -f test/__helpers/shared/db/postgres/docker-compose.yml up -d --wait
+        docker compose -f test/docker-compose.yml --profile postgres up -d --wait
         echo "url=postgresql://payload:payload@localhost:5433/payload" >> $GITHUB_OUTPUT
 
     - name: Configure PostgreSQL custom schema

CLAUDE.md

@@ -82,7 +82,7 @@ Payload is a monorepo structured around Next.js, containing the core CMS platfor
 - Auto-login is enabled by default with credentials: `dev@payloadcms.com` / `test`
 - To disable: pass `--no-auto-login` flag or set `PAYLOAD_PUBLIC_DISABLE_AUTO_LOGIN=false`
 - Default database is MongoDB (in-memory). Switch to Postgres with `PAYLOAD_DATABASE=postgres`
-- Docker services: `pnpm docker:start` / `pnpm docker:stop` / `pnpm docker:restart`
+- Docker services: `pnpm docker:start` / `pnpm docker:stop` / `pnpm docker:test`
 
 ### Playwright MCP
 

CONTRIBUTING.md

@@ -140,43 +140,29 @@ Set `PAYLOAD_DATABASE` in your `.env` file to choose the database adapter:
 - `supabase` - Supabase (PostgreSQL)
 - `d1` - D1 (SQLite)
 
-Then use Docker to start your database.
+Then use Docker to start your databases and storage emulators.
 
-On MacOS, the easiest way to install Docker is to use brew. Simply run `pnpm install --cask docker`, open the docker desktop app, apply the recommended settings and you're good to go.
-
-### PostgreSQL
+On MacOS, the easiest way to install Docker is to use brew. Simply run `brew install --cask docker`, open the docker desktop app, apply the recommended settings and you're good to go.
 
 ```bash
-pnpm docker:postgres:start         # Start (persists data)
-pnpm docker:postgres:restart:clean # Start fresh (removes data)
-pnpm docker:postgres:stop          # Stop
+pnpm docker:start  # Start all services (PostgreSQL, MongoDB, storage emulators) with fresh data
+pnpm docker:stop   # Stop all services
+pnpm docker:test   # Test database connections
 ```
 
-URL: `postgres://payload:payload@127.0.0.1:5433/payload`
-
-### MongoDB (with vector search)
-
-```bash
-pnpm docker:mongodb:start          # Start (persists data)
-pnpm docker:mongodb:restart:clean  # Start fresh (removes data)
-pnpm docker:mongodb:stop           # Stop
-```
+Every `docker:start` automatically removes old data and starts fresh, so you always get a clean environment.
 
-URL: `mongodb://payload:payload@localhost:27018/payload?authSource=admin&directConnection=true&replicaSet=rs0`
-
-### MongoDB Atlas Local
-
-```bash
-pnpm docker:mongodb-atlas:start         # Start (persists data)
-pnpm docker:mongodb-atlas:restart:clean # Start fresh (removes data)
-pnpm docker:mongodb-atlas:stop          # Stop
-```
+All services are defined in a single `test/docker-compose.yml` using Docker Compose profiles (`postgres`, `mongodb`, `mongodb-atlas`, `storage`, `all`).
 
-URL: `mongodb://localhost:27019/payload?directConnection=true&replicaSet=mongodb-atlas-local` (no auth required)
+**Connection URLs:**
 
-### SQLite
+| Database            | URL                                                                                                       |
+| ------------------- | --------------------------------------------------------------------------------------------------------- |
+| PostgreSQL          | `postgres://payload:payload@127.0.0.1:5433/payload`                                                       |
+| MongoDB             | `mongodb://payload:payload@localhost:27018/payload?authSource=admin&directConnection=true&replicaSet=rs0` |
+| MongoDB Atlas Local | `mongodb://localhost:27019/payload?directConnection=true&replicaSet=mongodb-atlas-local` (no auth)        |
 
-SQLite databases don't require Docker - they're stored as files in the project.
+SQLite databases don't require Docker — they're stored as files in the project.
 
 ### Testing with your own database
 

package.json

@@ -82,24 +82,9 @@
     "dev:prod": "cross-env NODE_OPTIONS=--no-deprecation tsx ./test/dev.ts --prod",
     "dev:vercel-postgres": "cross-env PAYLOAD_DATABASE=vercel-postgres pnpm runts ./test/dev.ts",
     "devsafe": "node ./scripts/delete-recursively.js '**/.next' && pnpm dev",
-    "docker:mongodb-atlas:restart": "pnpm docker:mongodb-atlas:stop && pnpm docker:mongodb-atlas:start",
-    "docker:mongodb-atlas:restart:clean": "docker rm -f mongodb-atlas-payload-test 2>/dev/null; docker compose -f test/__helpers/shared/db/mongodb-atlas/docker-compose.yml down -v && pnpm docker:mongodb-atlas:start",
-    "docker:mongodb-atlas:start": "docker compose -f test/__helpers/shared/db/mongodb-atlas/docker-compose.yml up -d --wait",
-    "docker:mongodb-atlas:stop": "docker compose -f test/__helpers/shared/db/mongodb-atlas/docker-compose.yml down",
-    "docker:mongodb-atlas:test": "pnpm runts test/__helpers/shared/db/mongodb-atlas/run-test-connection.ts",
-    "docker:mongodb:restart": "pnpm docker:mongodb:stop && pnpm docker:mongodb:start",
-    "docker:mongodb:restart:clean": "docker rm -f mongodb-payload-test mongot-payload-test 2>/dev/null; docker compose -f test/__helpers/shared/db/mongodb/docker-compose.yml down -v && pnpm docker:mongodb:start",
-    "docker:mongodb:start": "docker compose -f test/__helpers/shared/db/mongodb/docker-compose.yml up -d --wait",
-    "docker:mongodb:stop": "docker rm -f mongodb-payload-test mongot-payload-test 2>/dev/null; docker compose -f test/__helpers/shared/db/mongodb/docker-compose.yml down",
-    "docker:mongodb:test": "pnpm runts test/__helpers/shared/db/mongodb/run-test-connection.ts",
-    "docker:postgres:restart": "pnpm docker:postgres:stop && pnpm docker:postgres:start",
-    "docker:postgres:restart:clean": "docker rm -f postgres-payload-test 2>/dev/null; docker compose -f test/__helpers/shared/db/postgres/docker-compose.yml down -v && pnpm docker:postgres:start",
-    "docker:postgres:start": "docker compose -f test/__helpers/shared/db/postgres/docker-compose.yml up -d --wait",
-    "docker:postgres:start:clean": "docker pull ghcr.io/payloadcms/postgis-vector:latest && docker compose -f test/__helpers/shared/db/postgres/docker-compose.yml down -v && docker compose -f test/__helpers/shared/db/postgres/docker-compose.yml up -d --wait",
-    "docker:postgres:stop": "docker rm -f postgres-payload-test 2>/dev/null; docker compose -f test/__helpers/shared/db/postgres/docker-compose.yml down",
-    "docker:restart": "pnpm docker:stop --remove-orphans && pnpm docker:start",
-    "docker:start": "docker compose -f test/docker-compose.yml up -d",
-    "docker:stop": "docker compose -f test/docker-compose.yml down",
+    "docker:start": "docker compose -f test/docker-compose.yml --profile all down -v --remove-orphans 2>/dev/null; docker compose -f test/docker-compose.yml --profile all up -d --wait",
+    "docker:stop": "docker compose -f test/docker-compose.yml --profile all down --remove-orphans",
+    "docker:test": "pnpm runts test/__helpers/shared/db/mongodb/run-test-connection.ts && pnpm runts test/__helpers/shared/db/mongodb-atlas/run-test-connection.ts",
     "force:build": "pnpm run build:core:force",
     "lint": "turbo run lint --log-order=grouped --continue --filter \"!blank\" --filter \"!website\" --filter \"!ecommerce\"",
     "lint-staged": "lint-staged",