Skip to content

Migrate local development to authenticated MongoDB

The shared local db-mongo service now uses authentication so PeerDB can use it as a Change Data Capture (CDC) source. PeerDB v0.37.5 validates the source using an authenticated replica-set user with explicit replication roles.

This is a one-time migration for an existing MongoDB volume. After migration, every program running on your host must provide credentials when connecting to the shared MongoDB service.

Connection URI

Use this URI for host applications such as the backend, mongosh, MongoDB Compass, and local scripts:

mongodb://local:local@localhost:27017/?directConnection=true&authSource=admin

The URI contains three important settings:

  • local:local is the local development username and password.
  • directConnection=true connects straight to localhost:27017 without trying to resolve the replica set’s Docker-only address.
  • authSource=admin identifies the database that stores the user.

PeerDB runs inside Docker and uses normal replica-set discovery. Do not add directConnection=true to PeerDB’s connection URI.

Migrate MongoDB

Run these commands from the control-rooms repository root.

Fresh or disposable volume

No migration is needed. Docker Compose creates the user and enables authentication automatically:

Terminal window
docker compose up -d db-mongo mongo-init

Existing volume that must keep its data

Restart MongoDB with authentication enabled, then run the repeatable migration script:

Terminal window
docker compose up -d db-mongo
./peerdb-local/enable-mongo-auth.sh

The script preserves the volume, creates the local user, updates the advertised replica-set address, grants PeerDB’s required roles, and retains at least 24 hours of changes in MongoDB’s operation log.

Confirm that authentication works:

Terminal window
mongosh "mongodb://local:local@localhost:27017/?directConnection=true&authSource=admin" \
--eval 'db.adminCommand("ping").ok'

The command should print 1.

Update applications

control-rooms backend

The sc-11153 branch already updates the development MongoDB URIs in backend/api-server/src/main/resources/application.yaml. No additional change is needed after that branch merges.

fleet-tracking

Production already uses an authenticated MongoDB Atlas cluster, so no application code change is required. Local configuration must use the authenticated URI.

Replace the ip value in the committed config.example.json template. Apply the same change to your ignored config.json or config-run-fleet-service.json file.

// Before
"ip": "localhost"
// After
"ip": "mongodb://local:local@localhost:27017/?directConnection=true&authSource=admin"

Leave port set to 27017. PyMongo ignores the separate port when ip contains a complete MongoDB URI.

If you use the standalone runner, update scripts/fleet_service_runner/main.py as well:

MONGO_HOST = "mongodb://local:local@localhost:27017/?directConnection=true&authSource=admin"

Avoid committing credentials outside the existing local-development convention. For personal configuration, prefer a gitignored file or an environment variable.

Other local tools

Use the connection URI above in mongosh, MongoDB Compass, and personal scripts.

The following projects do not connect to the shared MongoDB service and require no changes:

  • skyledge_dagster uses localhost:27018 and a remote Atlas cluster.
  • forms-backend, fuel-verify-agent, fleet_visualiser, and evidence have no local connection to port 27017.
  • control-rooms/integration-tests and control-rooms/sdk-generator create their own isolated MongoDB instances.
  • The fleet-tracking Lawson scripts use a remote Atlas cluster.

Verify the migration

  1. Run the mongosh ping command above and confirm that it prints 1.

  2. Start the control-rooms backend and confirm that it connects without a MongoSecurityException.

  3. Run fleet-tracking locally and confirm that it can read its collections.

  4. Start the local PeerDB stack and create the CDC mirror:

    Terminal window
    cd peerdb-local
    ./peerdb-up.sh
    ./create-peers-mirror.sh
  5. Follow peerdb-local/README.md to insert an event and confirm that it appears in ClickHouse.

Roll back authentication

Rollback changes the shared MongoDB service and requires a control-rooms branch whose Compose configuration starts MongoDB without --auth or --keyFile.

Stop and remove only the MongoDB container. This does not delete its bind-mounted ./data/mongo directory:

Terminal window
docker compose stop db-mongo
docker compose rm -f db-mongo

After switching to a Compose configuration without authentication, start MongoDB and restore the host-resolvable replica-set address:

Terminal window
docker compose up -d db-mongo
mongosh "mongodb://localhost:27017/?directConnection=true" --eval \
'c=rs.conf(); c.members[0].host="localhost:27017"; rs.reconfig(c,{force:true})'

Finally, restore unauthenticated MongoDB URIs in each local application.