chore: monorepo devcontainer support, refactor db adapter and docker start script (#16396)

## Devcontainers

Adds dev container configuration, so contributors can open the repo in
VS Code without setting up Node, pnpm, or Docker on their own machine.
Works for both "Reopen in Container" (your local clone bind-mounted in)
and "Clone Repository in Container Volume" (a fresh clone inside an
isolated Docker volume, useful when running multiple parallel sessions
against the same repo without them stepping on each other).

`test/generateDatabaseAdapter.ts` was renamed to `test/dbAdapters.ts`
and is the source of truth for anything db-adapter-related in one place:
the source templates the codegen writes out, and the host/port/env-var
defaults per adapter, which the new `assertDbReachable.ts` function uses
to probe services.

This should enable running multiple agents conflict-free

## DB Connection probe + docker:start script improvements

`assertDbReachable` is now run within `pnpm dev`. If the db connection
fails, you now get immediate feedback through a helpful error, instead
of having to wait for Next.js to compile and then be thrown off by a
cryptic db seed error:

<img width="852" height="488" alt="screenshot 2026-04-26 at 15 26 12@2x"
src="https://github.com/user-attachments/assets/aecfee0a-20eb-4d25-9215-256f8c8f5f8a"
/>

`pnpm docker:start` is now an interactive picker. You can still pass
profile names as args (`pnpm docker:start postgres mongodb`) to skip the
prompt:

<img width="898" height="348" alt="screenshot 2026-04-26 at 15 28 04@2x"
src="https://github.com/user-attachments/assets/7d4b8f3d-89a5-46b7-b3ca-887a793246b1"
/>

These changes encourages contributors not to start every single service
we have available (uses around 4gb of ram), and only start the database
service that you're using => much less memory usage.


---
- To see the specific tasks where the Asana app for GitHub is being
used, see below:
  - https://app.asana.com/0/0/1214135483864575

Author: AlessioGr

.devcontainer/.env.example

@@ -0,0 +1 @@
+PAYLOAD_DATABASE=sqlite

.devcontainer/devcontainer.json

@@ -0,0 +1,61 @@
+{
+  "name": "Payload Monorepo",
+  "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+  "features": {
+    "ghcr.io/payloadcms/devcontainer-features/mise-bootstrap:1": {},
+    "ghcr.io/devcontainers/features/docker-in-docker:2": {},
+    "ghcr.io/devcontainers/features/common-utils:2": {
+      "configureZshAsDefaultShell": true,
+      "installZsh": true,
+      "installOhMyZsh": true,
+      "installOhMyZshConfig": true,
+      "upgradePackages": true
+    }
+  },
+  // Runs before feature postCreateCommands so the named volume is writable
+  // by the time mise-bootstrap tries to install into node_modules.
+  "onCreateCommand": "sudo chown vscode:vscode ${containerWorkspaceFolder}/node_modules",
+  // setup.sh auto-detects bind-mount vs volume-clone mode and handles both.
+  "postCreateCommand": ".devcontainer/setup.sh",
+  // Only the Next.js dev server should be forwarded
+  "forwardPorts": [3000],
+  "portsAttributes": {
+    "3000": {
+      "label": "Next Dev Server"
+    }
+  },
+  "customizations": {
+    "vscode": {
+      "extensions": [
+        "anthropic.claude-code",
+        "dbaeumer.vscode-eslint",
+        "esbenp.prettier-vscode",
+        "eamodio.gitlens",
+        "hverlin.mise-vscode",
+        "stylelint.vscode-stylelint",
+        "vitest.explorer",
+        "ms-playwright.playwright"
+      ],
+      "settings": {
+        "terminal.integrated.defaultProfile.linux": "zsh",
+        "terminal.integrated.profiles.linux": {
+          "zsh": {
+            "path": "zsh"
+          }
+        },
+        // Stop VS Code from auto-forwarding every ephemeral port a process opens.
+        // Only ports in `forwardPorts` above are exposed.
+        "remote.autoForwardPorts": false
+      }
+    }
+  },
+  // Allows us to detect whether we are within a devcontainer
+  "containerEnv": {
+    "DEVCONTAINER": "true"
+  },
+  // node_modules volume: isolates linux-arm64 installs from darwin-arm64 host
+  // files in bind-mount mode.
+  "mounts": [
+    "source=${containerWorkspaceFolderBasename}-node-modules,target=${containerWorkspaceFolder}/node_modules,type=volume"
+  ]
+}

.devcontainer/setup.sh

@@ -0,0 +1,15 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+WS="$(pwd)"
+
+if [ "$(stat -c '%u' "$WS")" = "0" ]; then
+  # Volume-clone: whole workspace was cloned as root; rehome it.
+  sudo chown -R vscode:vscode "$WS"
+else
+  # Bind-mount: only the fresh node_modules named volume is root-owned.
+  sudo chown vscode:vscode "$WS/node_modules"
+fi
+
+# Seed .env when absent
+[ -f .env ] || cp .devcontainer/.env.example .env

.github/workflows/main.yml

@@ -407,6 +407,7 @@ jobs:
         env:
           PLAYWRIGHT_JSON_OUTPUT_NAME: results_${{ matrix.suite }}_${{ matrix.shard }}.json
           NEXT_TELEMETRY_DISABLED: 1
+          PAYLOAD_DATABASE: mongodb
 
       - uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
         if: always()

.gitignore

@@ -5,6 +5,7 @@ dist
 !/.idea/runConfigurations
 /.idea/runConfigurations/_template*
 !/.idea/payload.iml
+.pnpm-store
 
 # Local AI Agent files
 AGENTS.local.md
@@ -18,7 +19,6 @@ CLAUDE.local.md
 
 test/packed
 test-results
-.devcontainer
 .localstack
 /migrations
 .localstack

CONTRIBUTING.md

@@ -166,6 +166,29 @@ All services are defined in a single `test/docker-compose.yml` using Docker Comp
 
 SQLite databases don't require Docker — they're stored as files in the project.
 
+### Development with Devcontainers
+
+You can run the entire development environment inside a devcontainer.
+
+**Prerequisites:**
+
+- Docker or [OrbStack](https://orbstack.dev) (recommended on macOS for better performance)
+- One of:
+  - VS Code with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers), or
+  - The [`@devcontainers/cli`](https://github.com/devcontainers/cli)
+
+**Start the container — pick one:**
+
+- **VS Code:** Open the repo and click "Reopen in Container" when prompted (or run `Dev Containers: Reopen in Container` from the command palette).
+- **CLI (any editor):** From the repo root, run `devcontainer up`, then `devcontainer exec zsh` for a shell. To attach an editor, point it at the running container - e.g. JetBrains "Dev Containers" plugin, Cursor / VS Code "Attach to Running Container", or just use the terminal.
+
+**Then, inside the container:**
+
+1. Run `pnpm docker:start` if you're not using sqlite
+2. Run `pnpm dev <test suite name>`
+
+The default `PAYLOAD_DATABASE` inside the devcontainer is `sqlite`, so the `pnpm docker:start` step is only needed when you switch to mongodb/postgres.
+
 ### Testing with your own database
 
 If you wish to use your own MongoDB database for the `test` directory instead of using the docker database, add the following to your `.env` file:

package.json

@@ -82,8 +82,8 @@
     "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:clean": "node ./scripts/docker-clean.js",
-    "docker:start": "pnpm docker:clean && docker compose -f test/docker-compose.yml --profile all up -d --wait",
+    "docker:clean": "node ./scripts/docker-clean.ts",
+    "docker:start": "node ./scripts/docker-start.ts",
     "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\"",
@@ -178,6 +178,7 @@
   "devDependencies": {
     "@ai-sdk/openai": "3.0.30",
     "@axe-core/playwright": "4.11.0",
+    "@clack/prompts": "1.2.0",
     "@libsql/client": "0.14.0",
     "@next/bundle-analyzer": "16.2.3",
     "@payloadcms/db-postgres": "workspace:*",
@@ -245,10 +246,6 @@
     "zod": "4.3.6"
   },
   "packageManager": "pnpm@10.27.0",
-  "engines": {
-    "node": "^18.20.2 || >=20.9.0",
-    "pnpm": "^10.27.0"
-  },
   "pnpm": {
     "onlyBuiltDependencies": [
       "@parcel/watcher",