Skip to content

Local MongoDB Development

Run a local MongoDB container seeded from an Atlas scheduled backup, so you can develop against real data without connecting to the production database.

Prerequisites

  • Docker installed and running
  • An Atlas scheduled backup .tar.gz file downloaded to your machine

Downloading an Atlas Backup

  1. Go to MongoDB Atlas → Cluster0 → Backup → Snapshots
  2. Select a scheduled snapshot and click Download
  3. Save the .tar.gz file to a local directory, e.g.:
mkdir -p ~/.syrf/backups
# Move your downloaded file
mv ~/Downloads/Cluster0-snapshot-*.tar.gz ~/.syrf/backups/

Starting MongoDB with Seed Data

Set the SYRF_ATLAS_BACKUP environment variable and start the container:

SYRF_ATLAS_BACKUP=~/.syrf/backups/Cluster0-snapshot-2026-03-07.tar.gz \
  docker compose -f docker-compose.dev.yml up -d mongodb

On first startup, the container will:

  1. Extract the Atlas backup .tar.gz (raw WiredTiger data files)
  2. Start a temporary mongod on the extracted data
  3. Rename the syrftest database to syrf_local (matching appsettings.Development.json)
  4. Drop other databases from the backup (e.g. syrfdev)
  5. Write a .syrf-seeded marker so subsequent restarts skip seeding
  6. Start mongod normally on port 27017

The API and Project Management services are already configured to connect to localhost:27017 / syrf_local in development mode — no config changes needed.

Starting Without Seed Data

If you don't need production data (e.g. for testing new features from scratch):

docker compose -f docker-compose.dev.yml up -d mongodb

Without SYRF_ATLAS_BACKUP, the container starts with an empty syrf_local database.

Re-seeding with a New Backup

To replace the database with a newer Atlas backup:

# Remove the existing container and its data volume
docker compose -f docker-compose.dev.yml down -v

# Start with the new backup
SYRF_ATLAS_BACKUP=~/.syrf/backups/newer-backup.tar.gz \
  docker compose -f docker-compose.dev.yml up -d mongodb

The -v flag removes the syrf-mongo-data volume, which triggers a fresh seed on next startup.

Troubleshooting

Check seed progress

docker logs -f syrf-mongodb

The seed script logs each phase with [syrf-seed] prefixes.

Seed failed or data looks wrong

# Reset completely
docker compose -f docker-compose.dev.yml down -v

# Try again
SYRF_ATLAS_BACKUP=~/.syrf/backups/backup.tar.gz \
  docker compose -f docker-compose.dev.yml up -d mongodb

Connect to the local database

# Via mongosh
docker exec -it syrf-mongodb mongosh syrf_local

# List collections
docker exec -it syrf-mongodb mongosh syrf_local --eval "db.getCollectionNames()"

CSUUID (GUID) format

All IDs in the database use BinData subtype 3 (CSUUID / C# Legacy). When querying manually:

// Use CSUUID(), not UUID()
db.pmProject.find({ _id: CSUUID("550e8400-e29b-41d4-a716-446655440000") })

See MongoDB Reference for details.

How It Works

The seed mechanism uses the fact that Atlas scheduled backups contain raw WiredTiger data directory files (not mongodump BSON). The script:

  • Extracts the .tar.gz into a temporary directory
  • Locates the WiredTiger data files (handling nested directory structures)
  • Starts a temporary mongod on port 27018 pointing at the extracted data
  • Uses renameCollection admin commands to rename syrftest → syrf_local
  • Copies the processed data into the container's /data/db
  • Writes a marker file to prevent re-seeding on restart

This approach is faster than mongodump/mongorestore because it works directly with the storage engine files.