MongoDB Agent

Standalone backup agent for MongoDB databases. Supports standalone instances, replica sets, and sharded clusters with point-in-time recovery.

v1.0.0Updated 2026-01-01
View on Docker Hub

Features

  • MongoDB 4.4, 5.0, 6.0, and 7.0 support
  • Standalone, replica sets, and sharded clusters
  • Oplog backup for point-in-time recovery
  • Native gzip compression
  • Parallel collection dumps for faster backups
  • Connection URI support for complex topologies
  • Secondary preferred reads to reduce primary load
  • Automatic source identifier for backup tracking

Quick Start

Docker Compose

# docker-compose.yml
version: '3.8'

services:
  mongodb:
    image: mongo:7.0
    environment:
      MONGO_INITDB_ROOT_USERNAME: admin
      MONGO_INITDB_ROOT_PASSWORD: ${MONGO_PASSWORD}
    volumes:
      - mongo_data:/data/db

  lox-mongodb-agent:
    image: loxbackup/mongodb-agent:latest
    environment:
      LOX_API_KEY: ${LOX_API_KEY}
      MONGO_HOST: mongodb
      MONGO_PORT: 27017
      MONGO_USER: admin
      MONGO_PASSWORD: ${MONGO_PASSWORD}
      MONGO_AUTH_DB: admin
      BACKUP_SCHEDULE: "0 3 * * *"
      BACKUP_GZIP: "true"
    depends_on:
      - mongodb

volumes:
  mongo_data:

Using Connection URI

docker run -d \
  --name lox-mongodb-agent \
  -e MONGO_URI="mongodb://user:pass@host1:27017,host2:27017/admin?replicaSet=rs0" \
  -e LOX_API_KEY=your-api-key \
  -e BACKUP_OPLOG=true \
  loxbackup/mongodb-agent:latest

Single Backup

docker run --rm \
  -e MONGO_HOST=mongodb.example.com \
  -e MONGO_USER=backup_user \
  -e MONGO_PASSWORD=secret \
  -e LOX_API_KEY=your-api-key \
  -e RUN_MODE=once \
  loxbackup/mongodb-agent:latest

Environment Variables

Connection Settings

VariableDefaultDescription
MONGO_HOSTlocalhostMongoDB hostname
MONGO_PORT27017MongoDB port
MONGO_USER-MongoDB username
MONGO_PASSWORD-MongoDB password
MONGO_DATABASEallSpecific database or all databases
MONGO_AUTH_DBadminAuthentication database
MONGO_URI-Full connection URI (overrides above)
MONGO_REPLICA_SET-Replica set name
MONGO_READ_PREFERENCEsecondaryPreferredRead preference for replica sets

Backup Settings

VariableDefaultDescription
LOX_API_KEY-LOX API key (required)
LOX_BASE_URLhttps://backlox.com/apiLOX API base URL
BACKUP_SCHEDULE0 2 * * *Cron schedule expression
BACKUP_RETENTION_DAYS30Days to retain backups
BACKUP_TAGSmongodb,automatedComma-separated tags
RUN_MODEcronRun mode: once, daemon, cron
SOURCE_IDENTIFIERautoCustom source ID (auto-generated if not set)

Source Identifier

The agent automatically generates a unique source_identifier for each MongoDB instance (format: mongodb-hostname-database-hash). This enables tracking backups across multiple servers and identifying their origin in the dashboard.

Advanced Options

VariableDefaultDescription
BACKUP_OPLOGfalseInclude oplog for PITR (requires replica set)
BACKUP_GZIPtrueCompress backup with gzip
BACKUP_PARALLEL_COLLECTIONS4Number of parallel collection dumps

Database User Setup

Create a dedicated backup user with minimum required privileges:

// Connect to MongoDB as admin
mongosh admin -u admin -p

// Create backup user
db.createUser({
  user: "lox_backup",
  pwd: "secure-password",
  roles: [
    { role: "backup", db: "admin" },
    { role: "readAnyDatabase", db: "admin" }
  ]
})

// For oplog backup (PITR), add clusterMonitor role
db.grantRolesToUser("lox_backup", [
  { role: "clusterMonitor", db: "admin" }
])

Security Note

Always use a dedicated backup user. The backup role provides the minimum privileges needed for mongodump.

Deployment Topologies

Standalone Instance

lox-mongodb-agent:
  image: loxbackup/mongodb-agent:latest
  environment:
    LOX_API_KEY: ${LOX_API_KEY}
    MONGO_HOST: mongodb
    MONGO_PORT: 27017
    MONGO_USER: lox_backup
    MONGO_PASSWORD: ${MONGO_PASSWORD}
    MONGO_AUTH_DB: admin
    BACKUP_SCHEDULE: "0 3 * * *"

Replica Set

For replica sets, use the connection URI with all members for automatic failover:

lox-mongodb-agent:
  image: loxbackup/mongodb-agent:latest
  environment:
    LOX_API_KEY: ${LOX_API_KEY}
    MONGO_URI: "mongodb://lox_backup:password@mongo1:27017,mongo2:27017,mongo3:27017/admin?replicaSet=rs0"
    # Enable oplog for point-in-time recovery
    BACKUP_OPLOG: "true"
    # Read from secondary to reduce primary load
    MONGO_READ_PREFERENCE: secondaryPreferred
    BACKUP_SCHEDULE: "0 */6 * * *"

Replica Set Benefits

With secondaryPreferred, backups run on secondary nodes, avoiding performance impact on the primary. Oplog backup enables point-in-time recovery.

Sharded Cluster

Connect to a mongos router for sharded cluster backups:

lox-mongodb-agent:
  image: loxbackup/mongodb-agent:latest
  environment:
    LOX_API_KEY: ${LOX_API_KEY}
    MONGO_HOST: mongos.example.com
    MONGO_PORT: 27017
    MONGO_USER: lox_backup
    MONGO_PASSWORD: ${MONGO_PASSWORD}
    MONGO_AUTH_DB: admin
    # Increase parallelism for large clusters
    BACKUP_PARALLEL_COLLECTIONS: 8
    BACKUP_SCHEDULE: "0 2 * * *"

Point-in-Time Recovery

Enable oplog backup for point-in-time recovery (requires replica set):

lox-mongodb-agent:
  image: loxbackup/mongodb-agent:latest
  environment:
    LOX_API_KEY: ${LOX_API_KEY}
    MONGO_URI: "mongodb://user:pass@rs1:27017,rs2:27017,rs3:27017/admin?replicaSet=myrs"
    BACKUP_OPLOG: "true"
    BACKUP_SCHEDULE: "0 */4 * * *"

Oplog Considerations

Oplog backup captures all write operations since the last backup. Ensure your oplog window is larger than your backup interval. Check with rs.printReplicationInfo().

Restoring Backups

Full Restore

# Download the backup from LOX
curl -H "Authorization: Bearer $LOX_API_KEY" \
  "https://backlox.com/api/v1/backups/{uuid}/download" -o backup.archive.gz

# Restore to MongoDB
mongorestore --gzip --archive=backup.archive.gz

# Restore to a different cluster
mongorestore --gzip --archive=backup.archive.gz \
  --host=newcluster.example.com \
  --username=admin \
  --password=secret \
  --authenticationDatabase=admin

Selective Restore

# Restore specific database
mongorestore --gzip --archive=backup.archive.gz \
  --nsInclude="mydb.*"

# Restore specific collection
mongorestore --gzip --archive=backup.archive.gz \
  --nsInclude="mydb.users"

# Restore with name mapping
mongorestore --gzip --archive=backup.archive.gz \
  --nsFrom="prod.*" --nsTo="staging.*"

Point-in-Time Restore

# Restore with oplog replay up to specific timestamp
mongorestore --gzip --archive=backup.archive.gz \
  --oplogReplay \
  --oplogLimit="1703520000:1"  # Unix timestamp:increment

Examples

MongoDB Atlas

lox-mongodb-agent:
  image: loxbackup/mongodb-agent:latest
  environment:
    LOX_API_KEY: ${LOX_API_KEY}
    MONGO_URI: "mongodb+srv://lox_backup:password@cluster0.xxxxx.mongodb.net/admin?retryWrites=true&w=majority"
    BACKUP_SCHEDULE: "0 4 * * *"
    BACKUP_TAGS: "mongodb,atlas,production"

Single Database with High Frequency

lox-mongodb-agent:
  image: loxbackup/mongodb-agent:latest
  environment:
    LOX_API_KEY: ${LOX_API_KEY}
    MONGO_HOST: mongodb
    MONGO_USER: lox_backup
    MONGO_PASSWORD: ${MONGO_PASSWORD}
    MONGO_DATABASE: critical_app  # Only this database
    BACKUP_SCHEDULE: "0 */2 * * *"  # Every 2 hours
    BACKUP_RETENTION_DAYS: 7
    BACKUP_TAGS: "mongodb,critical,hourly"

TLS/SSL Connection

lox-mongodb-agent:
  image: loxbackup/mongodb-agent:latest
  environment:
    LOX_API_KEY: ${LOX_API_KEY}
    MONGO_URI: "mongodb://lox_backup:pass@mongo:27017/admin?tls=true&tlsCAFile=/certs/ca.pem&tlsCertificateKeyFile=/certs/client.pem"
    BACKUP_SCHEDULE: "0 3 * * *"
  volumes:
    - ./certs:/certs:ro

Troubleshooting

Authentication failed

Verify the authentication database is correct (usually admin). Check user privileges with db.getUser("lox_backup").

Oplog backup failed

Oplog backup requires a replica set. Verify with rs.status(). For standalone, disable oplog: BACKUP_OPLOG=false.

Connection timeout

For large databases, increase the timeout in the connection URI: ?connectTimeoutMS=30000&socketTimeoutMS=300000

Debug mode

Check container logs for detailed output: docker logs lox-mongodb-agent

← PostgreSQL AgentCLI Tool →