MongoDB

Deploy and manage MongoDB databases on Dokploy

MongoDB is a document-oriented NoSQL database known for flexibility, scalability, and developer-friendly features. It stores data in JSON-like documents with dynamic schemas.

Creating a MongoDB Database

1. Navigate to Databases

   In your Dokploy dashboard, select your environment and click Add Database > MongoDB.

2. Configure Basic Settings

   Provide the basic information:

   • Name: Display name for your database
   • App Name: Internal DNS name (e.g., mongo-prod)
   • Description: Optional notes
   • Docker Image: MongoDB version (default: mongo:15)
3. Set Credentials

   MongoDB requires authentication credentials:

   Database User: admin
   Database Password: <strong-password>
   

   Passwords cannot contain: $ ! ' " \ / or spaces

   MongoDB creates a user with root privileges. You can create additional users after deployment.

4. Optional: Enable Replica Sets

   For production deployments, enable replica sets:

   • Check Enable Replica Sets
   • Provides high availability and data redundancy
   • Required for transactions and change streams

   Replica sets require additional configuration after deployment.

5. Deploy

   Click Create to deploy. Dokploy will:

   • Pull the MongoDB Docker image
   • Create a volume at /data/db
   • Initialize with your credentials

Connection Information

Internal Connection

Applications in the same environment use internal DNS:

Host: <app-name>  # e.g., mongo-prod
Port: 27017
Username: admin
Password: <your-password>
Auth Database: admin

Connection String Examples:

# Standard format
mongodb://admin:password@mongo-prod:27017

# With authentication database
mongodb://admin:password@mongo-prod:27017/?authSource=admin

# With specific database
mongodb://admin:password@mongo-prod:27017/myapp?authSource=admin

# MongoDB Shell
mongosh mongodb://admin:password@mongo-prod:27017/myapp?authSource=admin

External Connection

To enable external access:

1. Navigate to Settings > External Port
2. Assign a port (e.g., 27018)
3. Click Save and redeploy

Connection String Examples:

# Standard format
mongodb://admin:[e-mail]:27018

# With options
mongodb://admin:[e-mail]:27018/myapp?authSource=admin

# MongoDB Shell
mongosh mongodb://admin:[e-mail]:27018/myapp?authSource=admin

Exposing MongoDB externally requires proper firewall configuration and strong passwords.

Application Drivers

Connection examples for popular languages:

Node.js:

const { MongoClient } = require('mongodb');

const uri = 'mongodb://admin:password@mongo-prod:27017/myapp?authSource=admin';
const client = new MongoClient(uri);

await client.connect();
const db = client.db('myapp');

Python:

from pymongo import MongoClient

uri = 'mongodb://admin:password@mongo-prod:27017/myapp?authSource=admin'
client = MongoClient(uri)
db = client['myapp']

Go:

import "go.mongodb.org/mongo-driver/mongo"

uri := "mongodb://admin:password@mongo-prod:27017/myapp?authSource=admin"
client, err := mongo.Connect(context.TODO(), options.Client().ApplyURI(uri))
db := client.Database("myapp")

Configuration

Environment Variables

Customize MongoDB with environment variables:

# Performance settings
MONGO_MAXPOOLSIZE=100
MONGO_CONNECTTIMEOUTMS=10000
MONGO_SOCKETTIMEOUTMS=30000

# WiredTiger storage engine
MONGO_WIREDTIGER_CACHE_SIZE_GB=1
MONGO_WIREDTIGER_CONCURRENT_READ_TRANSACTIONS=128
MONGO_WIREDTIGER_CONCURRENT_WRITE_TRANSACTIONS=128

# Logging
MONGO_VERBOSE=v
MONGO_LOGPATH=/var/log/mongodb/mongod.log

# Security
MONGO_AUTH=true
MONGO_BIND_IP_ALL=false

# Replication (if replica sets enabled)
MONGO_REPLSET=rs0

# Timezone
TZ=America/New_York

Resource Allocation

Recommended resources by workload:

Workload	Memory Reservation	Memory Limit	CPU Reservation	CPU Limit
Development	256MB	512MB	0.1	0.25
Small Application	512MB	1GB	0.25	0.5
Production	1GB	2GB	0.5	1.0
High Performance	2GB	8GB	1.0	4.0

MongoDB benefits from more memory for caching. Allocate at least 1GB for production workloads.

Docker Image Versions

MongoDB version options:

# Community Edition
mongo:15           # Default version
mongo:7            # MongoDB 7.x
mongo:6            # MongoDB 6.x
mongo:5            # MongoDB 5.x

# Specific versions
mongo:7.0.5
mongo:6.0.13

# Note: Version 15 in the default is likely mongo:5 or mongo:6
# Verify available versions at hub.docker.com/_/mongo

Database Operations

Lifecycle Management

Start/Stop

Control database availability:

Start:

• Status: done
• Accepts connections
• Loads data from volume

Stop:

• Status: idle
• Closes connections gracefully
• Data persists in volume
• No resource usage

Reload

Restart MongoDB:

1. Click Reload
2. MongoDB shuts down
3. Container restarts
4. Database comes online

Use reload for:

• Applying environment changes
• Clearing caches
• Troubleshooting issues

Rebuild

Rebuild the container:

1. Go to Settings > Rebuild
2. Confirm rebuild
3. Container recreated
4. Data volume preserved

Rebuild causes downtime. Plan maintenance windows.

Volume Management

MongoDB stores data in a Docker volume:

Volume Name: {appName}-data
Mount Path: /data/db

Volume contents:

• Database files (WiredTiger)
• Collection data
• Indexes
• Journal files
• Configuration

Backup Configuration

See Database Backups for automated backup setup using mongodump.

Advanced Configuration

Custom Startup Options

Command:

mongod

Arguments:

--wiredTigerCacheSizeGB 1
--maxConns 100
--bind_ip_all
--auth
--logpath /var/log/mongodb/mongod.log
--logappend

Replica Set Configuration

If you enabled replica sets during creation:

1. Connect to MongoDB:

   mongosh mongodb://admin:password@mongo-prod:27017?authSource=admin
   

2. Initialize replica set:

   rs.initiate({
     _id: "rs0",
     members: [
       { _id: 0, host: "mongo-prod:27017" }
     ]
   })
   

3. Verify status:

   rs.status()
   

Health Check Configuration

{
  "test": ["CMD-SHELL", "mongosh --eval 'db.adminCommand({\"ping\": 1})'"],
  "interval": 30000000000,
  "timeout": 5000000000,
  "retries": 3
}

Restart Policy

{
  "condition": "on-failure",
  "delay": 5000000000,
  "maxAttempts": 3
}

Common Use Cases

Web Application

Standard MongoDB for web apps:

Docker Image: mongo:7
Memory Limit: 1GB
CPU Limit: 0.5
Replica Sets: Disabled

# Environment
MONGO_MAXPOOLSIZE=50
MONGO_WIREDTIGER_CACHE_SIZE_GB=0.5

Production with HA

High availability configuration:

Docker Image: mongo:7
Memory Limit: 2GB
CPU Limit: 1.0
Replica Sets: Enabled

# Environment
MONGO_REPLSET=rs0
MONGO_MAXPOOLSIZE=100
MONGO_WIREDTIGER_CACHE_SIZE_GB=1

Analytics

Optimized for heavy reads:

Docker Image: mongo:7
Memory Limit: 4GB
CPU Limit: 2.0

# Environment
MONGO_WIREDTIGER_CACHE_SIZE_GB=2
MONGO_WIREDTIGER_CONCURRENT_READ_TRANSACTIONS=256

Monitoring and Logs

View MongoDB logs:

1. Open your MongoDB service
2. Go to Logs tab
3. Monitor database activity

Common log patterns:

# Successful startup
Waiting for connections on port 27017

# Connection accepted
Connection accepted from 172.x.x.x:xxxxx

# Slow query
Slow query: 1234ms { find: "users", filter: { ... } }

# Replica set status
Replica set state transition: SECONDARY -> PRIMARY

Troubleshooting

Authentication failed

Common authentication issues:

Symptoms:

• Authentication failed errors
• Cannot connect with credentials

Solutions:

1. Verify password format (no special characters)
2. Check authSource in connection string:
   mongodb://admin:password@mongo-prod:27017/?authSource=admin
   
3. Ensure user was created correctly
4. Try connecting without authentication first (if accessible)

Cannot connect

Connection troubleshooting:

1. Verify host: Use app name for internal connections
2. Check port: 27017 internal, custom external
3. Database status: Must be done
4. Network: Same environment for internal access

Test connectivity:

# Internal
telnet mongo-prod 27017

# External
telnet your-server.com 27018

Out of memory

MongoDB exceeding memory limits:

1. Increase container memory
2. Reduce WiredTiger cache:
   MONGO_WIREDTIGER_CACHE_SIZE_GB=0.5
   
3. Limit concurrent operations:
   MONGO_MAXPOOLSIZE=25
   
4. Consider upgrading resources

Slow queries

Performance optimization:

1. Create indexes:

   db.collection.createIndex({ field: 1 })
   

2. Increase cache size:

   MONGO_WIREDTIGER_CACHE_SIZE_GB=2
   

3. Enable profiling:

   db.setProfilingLevel(1, { slowms: 100 })
   db.system.profile.find().pretty()
   

4. Review explain plans:

   db.collection.find({...}).explain("executionStats")
   

Replica set issues

If replica sets are not working:

1. Check initialization:

   rs.status()
   

2. Verify configuration:

   rs.conf()
   

3. Check connectivity between nodes

4. Review logs for errors

5. Ensure hostnames are resolvable

Best Practices

Security

1. Use strong passwords: Generate random passwords
2. Limit external access: Only expose when necessary
3. Create specific users: Don’t use admin for applications
4. Enable authentication: Always run with --auth
5. Regular backups: Configure automated backups

Performance

1. Index properly: Create indexes for frequent queries
2. Monitor cache: Ensure adequate WiredTiger cache
3. Use projections: Return only needed fields
4. Avoid large documents: Keep documents under 16MB
5. Connection pooling: Reuse connections in applications

Production Deployment

1. Enable replica sets: For high availability
2. Configure monitoring: Track performance metrics
3. Set up alerts: Monitor errors and slow queries
4. Regular backups: Daily automated backups
5. Test disaster recovery: Practice restore procedures

MongoDB Compass

Connect to your MongoDB instance using MongoDB Compass GUI:

1. Download MongoDB Compass
2. Use connection string:
   mongodb://admin:[e-mail]:27018/?authSource=admin
   
3. Explore collections, run queries, and analyze performance

Next Steps

Setup Backups

Configure automated MongoDB backups

Redis

Deploy a Redis cache