test: move mongodb to different port to avoid port conflicts (#14993)

This moves the exposed mongodb docker image port from 27017 to 27018 in
order to avoid conflict with locally installed mongodb applications
running on port 27017.

Previously, you would have to make sure you don't have mongodb running
locally when using the docker image - otherwise, it would fail to
connect.

It also adds the old .env variables commented out in the .env.example
for users who do not wish to use docker. The CONTRIBUTING.md now
includes docker installation steps for macOS users.

Author: AlessioGr

.env.example

@@ -3,3 +3,16 @@ PAYLOAD_DATABASE=mongodb
 
 # Optional - used for the `translateNewKeys` script
 OPENAI_KEY=
+
+
+
+
+
+
+
+
+
+# If you're NOT using our docker scripts and want to manually install your database, uncomment these and point them to your local database.
+# Do not uncomment these if you're using our Docker scripts to run your database.
+# MONGODB_URL=mongodb://127.0.0.1/payloadtests
+# POSTGRES_URL=postgres://127.0.0.1:5432/payloadtests

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

@@ -26,15 +26,15 @@ runs:
       shell: bash
       run: |
         docker compose -f test/helpers/db/mongodb/docker-compose.yml up -d --wait
-        echo "url=mongodb://payload:payload@localhost:27017/payload?authSource=admin&directConnection=true&replicaSet=rs0" >> $GITHUB_OUTPUT
+        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/db/mongodb-atlas/docker-compose.yml up -d --wait
-        echo "url=mongodb://localhost:27018/payload?directConnection=true&replicaSet=mongodb-atlas-local" >> $GITHUB_OUTPUT
+        echo "url=mongodb://localhost:27019/payload?directConnection=true&replicaSet=mongodb-atlas-local" >> $GITHUB_OUTPUT
 
     - name: Start PostgreSQL
       id: postgres

CONTRIBUTING.md

@@ -87,7 +87,9 @@ 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 database.
+
+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
 
@@ -107,7 +109,7 @@ pnpm docker:mongodb:restart:clean  # Start fresh (removes data)
 pnpm docker:mongodb:stop           # Stop
 ```
 
-URL: `mongodb://payload:payload@localhost:27017/payload?authSource=admin&directConnection=true&replicaSet=rs0`
+URL: `mongodb://payload:payload@localhost:27018/payload?authSource=admin&directConnection=true&replicaSet=rs0`
 
 ### MongoDB Atlas Local
 
@@ -117,17 +119,20 @@ pnpm docker:mongodb-atlas:restart:clean # Start fresh (removes data)
 pnpm docker:mongodb-atlas:stop          # Stop
 ```
 
-URL: `mongodb://localhost:27018/payload?directConnection=true&replicaSet=mongodb-atlas-local` (no auth required)
+URL: `mongodb://localhost:27019/payload?directConnection=true&replicaSet=mongodb-atlas-local` (no auth required)
 
 ### SQLite
 
 SQLite databases don't require Docker - they're stored as files in the project.
 
 ### Testing with your own database
 
-If you wish to use your own MongoDB database for the `test` directory instead of using the docker database, all you need to do is add the following env variable to your `.env` file:
+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:
 
-- `DATABASE_URL` to your database URL e.g. `mongodb://127.0.0.1/your-test-db`.
+```env
+MONGODB_URL=mongodb://127.0.0.1/payloadtests # Point this to your locally installed MongoDB database
+POSTGRES_URL=postgres://127.0.0.1:5432/payloadtests # Point this to your locally installed PostgreSQL database
+```
 
 ### Running the e2e and int tests
 

test/generateDatabaseAdapter.ts

@@ -5,11 +5,12 @@ import { fileURLToPath } from 'node:url'
 const filename = fileURLToPath(import.meta.url)
 const dirname = path.dirname(filename)
 
+// Runs on port 27018 to avoid conflicts with locally installed MongoDB
 const mongooseAdapterArgs = `
     ensureIndexes: true,
     url:
         process.env.MONGODB_URL || process.env.DATABASE_URL ||
-      'mongodb://payload:payload@localhost:27017/payload?authSource=admin&directConnection=true&replicaSet=rs0',
+      'mongodb://payload:payload@localhost:27018/payload?authSource=admin&directConnection=true&replicaSet=rs0',
 `
 
 export const allDatabaseAdapters = {
@@ -21,15 +22,15 @@ export const allDatabaseAdapters = {
   })`,
   // mongodb-atlas uses Docker-based MongoDB Atlas Local (all-in-one with search)
   // Start with: pnpm docker:mongodb-atlas:start
-  // Runs on port 27018 to avoid conflicts with mongodb
+  // Runs on port 27019 to avoid conflicts with mongodb
   'mongodb-atlas': `
   import { mongooseAdapter } from '@payloadcms/db-mongodb'
 
   export const databaseAdapter = mongooseAdapter({
     ensureIndexes: true,
     url:
         process.env.MONGODB_ATLAS_URL || process.env.DATABASE_URL ||
-      'mongodb://localhost:27018/payload?directConnection=true&replicaSet=mongodb-atlas-local',
+      'mongodb://localhost:27019/payload?directConnection=true&replicaSet=mongodb-atlas-local',
   })`,
   cosmosdb: `
   import { mongooseAdapter, compatibilityOptions } from '@payloadcms/db-mongodb'

test/helpers/db/mongodb-atlas/docker-compose.yml

@@ -16,7 +16,7 @@ services:
     container_name: mongodb-atlas-payload-test
     hostname: mongodb-atlas-local # Sets a fixed replica set name (used in connection string replicaSet param)
     ports:
-      - '27018:27017'
+      - '27019:27017'
     volumes:
       - mongodb_atlas_data:/data/db
     environment:

test/helpers/db/mongodb-atlas/run-test-connection.ts

@@ -9,5 +9,5 @@ import { testConnection } from '../mongodb/test-connection.js'
 
 await testConnection(
   process.env.MONGODB_ATLAS_URL ||
-    'mongodb://localhost:27018/payload?directConnection=true&replicaSet=mongodb-atlas-local',
+    'mongodb://localhost:27019/payload?directConnection=true&replicaSet=mongodb-atlas-local',
 )

test/helpers/db/mongodb/docker-compose.yml

@@ -17,7 +17,7 @@ services:
     image: mongodb/mongodb-community-server:8.2-ubi9
     container_name: mongodb-payload-test
     ports:
-      - '27017:27017'
+      - '27018:27017'
     volumes:
       - mongodb_data:/data/db
       - ./keyfile:/etc/mongodb/keyfile:ro

test/helpers/db/mongodb/run-test-connection.ts

@@ -9,5 +9,5 @@ import { testConnection } from './test-connection.js'
 
 await testConnection(
   process.env.MONGODB_URL ||
-    'mongodb://payload:payload@localhost:27017/payload?authSource=admin&directConnection=true&replicaSet=rs0',
+    'mongodb://payload:payload@localhost:27018/payload?authSource=admin&directConnection=true&replicaSet=rs0',
 )