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=adminThe URI contains three important settings:
local:localis the local development username and password.directConnection=trueconnects straight tolocalhost:27017without trying to resolve the replica set’s Docker-only address.authSource=adminidentifies 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:
docker compose up -d db-mongo mongo-initExisting volume that must keep its data
Restart MongoDB with authentication enabled, then run the repeatable migration script:
docker compose up -d db-mongo./peerdb-local/enable-mongo-auth.shThe 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:
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_dagsteruseslocalhost:27018and a remote Atlas cluster.forms-backend,fuel-verify-agent,fleet_visualiser, andevidencehave no local connection to port 27017.control-rooms/integration-testsandcontrol-rooms/sdk-generatorcreate their own isolated MongoDB instances.- The
fleet-trackingLawson scripts use a remote Atlas cluster.
Verify the migration
-
Run the
mongoshping command above and confirm that it prints1. -
Start the
control-roomsbackend and confirm that it connects without aMongoSecurityException. -
Run
fleet-trackinglocally and confirm that it can read its collections. -
Start the local PeerDB stack and create the CDC mirror:
Terminal window cd peerdb-local./peerdb-up.sh./create-peers-mirror.sh -
Follow
peerdb-local/README.mdto 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:
docker compose stop db-mongodocker compose rm -f db-mongoAfter switching to a Compose configuration without authentication, start MongoDB and restore the host-resolvable replica-set address:
docker compose up -d db-mongomongosh "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.