MongoDB Community Server on AWS User Guide

Overview

This image runs MongoDB Community Server, the open source document database, fully installed and configured from the official MongoDB package repository. The database listens on the standard MongoDB wire protocol port and the mongosh shell is preinstalled for local administration and scripting.

Authentication is enabled by default. On the first boot of every deployed instance, a one shot service generates two fresh, strong passwords unique to that instance: an admin superuser in the admin database and an application user cloudimg in the appdb database. Both passwords are written to a file at /root/mongodb-credentials.txt that only the root user can read. No shared or default database credentials ship in the image.

Database files and the journal live on a separate, independently resizable storage volume mounted at the MongoDB data directory, so database storage is kept off the operating system disk and can be grown, snapshotted and backed up on its own schedule.

A small nginx healthcheck shim runs on port 80 and serves a static OK response, so external HTTP probes have a 2xx endpoint to hit. MongoDB itself uses its TCP wire protocol on port 27017 for all client traffic.

Prerequisites

Before you deploy this image you need:

• An Amazon Web Services account where you can launch EC2 instances
• IAM permissions to launch instances, create security groups, and subscribe to AWS Marketplace products
• An EC2 key pair in the target Region for SSH access to the instance
• A VPC and subnet in the target Region, with a security group allowing inbound port 22 from your management network
• The AWS CLI version 2 installed locally if you plan to deploy from the command line

Step 1: Launch the Instance from the AWS Marketplace

Sign in to the AWS Management Console, open the EC2 service, and select Launch instance. Under Application and OS Images choose AWS Marketplace AMIs and search for MongoDB Community Server. Select the cloudimg listing and choose Select, then Continue on the subscription summary.

Pick an instance type of m5.large or larger as a balanced default; size the instance to the working set your collections require. Choose your EC2 key pair under Key pair (login). Under Network settings select your VPC and subnet, and either create or select a security group that allows inbound port 22 from your management network. If your application servers run in the same VPC and need to reach the database, also open inbound TCP port 27017 from those servers' security group.

Select Launch instance. First boot initialisation takes about a minute after the instance state becomes Running and the status checks pass; this is the window in which mongodb-firstboot.service rotates the admin and application passwords.

Step 2: Launch the Instance from the AWS CLI

The following block launches an instance from the cloudimg MongoDB Community Server Marketplace AMI into an existing subnet and security group. Replace <ami-id> with the AMI ID shown on the Marketplace listing, <key-name> with your EC2 key pair name, <subnet-id> with your subnet ID, and <security-group-id> with a security group that opens port 22 from your management network and (optionally) port 27017 from your application tier.

aws ec2 run-instances \
  --image-id <ami-id> \
  --instance-type m5.large \
  --key-name <key-name> \
  --subnet-id <subnet-id> \
  --security-group-ids <security-group-id> \
  --block-device-mappings '{"DeviceName":"/dev/sda1","Ebs":{"VolumeSize":30,"VolumeType":"gp3"}}' \
  --metadata-options 'HttpTokens=required,HttpEndpoint=enabled' \
  --tag-specifications 'ResourceType=instance,Tags=[{Key=Name,Value=mongodb-server}]'

The image attaches a dedicated 30 GiB database storage volume automatically, mounted at the MongoDB data directory. To start with more database storage, enlarge that volume on the Storage step in the console, or add a second block device mapping on the CLI.

Step 3: Connect to the Instance over SSH

Connect to the instance with SSH as the default login user for the operating system variant you launched. The login user differs by variant:

Replace <key-file> with the path to your private key file and <instance-public-ip> with the public IP address or DNS name of the instance.

ssh -i <key-file> ubuntu@<instance-public-ip>

Step 4: Read the Per Instance Database Passwords

On the first boot of the instance the mongodb-firstboot.service one shot generates two passwords unique to your instance. They are written to /root/mongodb-credentials.txt, which is readable only by the root user. Display the file with sudo:

sudo cat /root/mongodb-credentials.txt

The file lists two accounts:

• MONGO_ADMIN_USER=admin with role root in the admin database — full cluster administration
• MONGO_APP_USER=cloudimg with roles readWrite and dbAdmin in the appdb database — the application-tier user

Both passwords are unique to this instance and were generated by openssl rand -hex 16 on first boot. Keep them in a secrets manager and treat the credentials file as read-only on the instance.

Step 5: Confirm the MongoDB Server

Check the installed server, the storage engine and the dedicated data volume.

mongod --version | head -1

mongosh --version

Confirm the database service and the healthcheck shim are running:

systemctl is-active mongod.service nginx.service

Confirm mongod is bound to all interfaces on port 27017 and the database data directory is on its own filesystem:

sudo ss -tln | grep ':27017'
findmnt /var/lib/mongodb
df -h /var/lib/mongodb

Step 6: Open a Shell as the Admin User

Use the admin password from /root/mongodb-credentials.txt to open mongosh against the local node, authenticating against the admin database. The bash block below reads the password back out of the credentials file so the command line never has the plaintext typed into it.

ADMIN_PASS=$(sudo grep '^MONGO_ADMIN_PASSWORD=' /root/mongodb-credentials.txt | cut -d= -f2-)
mongosh --host 127.0.0.1 --port 27017 -u admin -p "$ADMIN_PASS" --authenticationDatabase admin --eval 'db.adminCommand({ping:1}).ok'

The command prints 1 if the admin user authenticated successfully and the deployment responded to ping.

To launch an interactive shell session as the admin user, drop the --eval argument:

ADMIN_PASS=$(sudo grep '^MONGO_ADMIN_PASSWORD=' /root/mongodb-credentials.txt | cut -d= -f2-)
mongosh --host 127.0.0.1 --port 27017 -u admin -p "$ADMIN_PASS" --authenticationDatabase admin

List the databases on the deployment from inside the interactive shell with show dbs. Exit the shell with exit.

Step 7: Application User Round Trip

The application user cloudimg has readWrite and dbAdmin on the appdb database. The block below reads the application password from the credentials file and runs an end to end probe: insert a document, find it back, then drop the test collection.

APP_PASS=$(sudo grep '^MONGO_APP_PASSWORD=' /root/mongodb-credentials.txt | cut -d= -f2-)
mongosh --quiet --host 127.0.0.1 --port 27017 -u cloudimg -p "$APP_PASS" --authenticationDatabase appdb appdb --eval '
  db.demo.insertOne({hello: "world", ts: new Date()});
  printjson(db.demo.findOne({hello: "world"}));
  db.demo.drop();
'

This is also the round trip that cloudimg's build pipeline uses to prove the rotated application password works on every image before the AMI ships.

Step 8: Connect from an Application Server

To connect from another EC2 instance in the same VPC, give that instance a security group that allows outbound TCP 27017 to the MongoDB instance, and add an inbound rule on the MongoDB instance's security group that allows TCP 27017 from the application server's security group.

A standard MongoDB connection string for the application user looks like this. Replace <MONGO_APP_PASSWORD> with the password shown in /root/mongodb-credentials.txt and <mongodb-private-ip> with the MongoDB instance's private IP address.

mongodb://cloudimg:<MONGO_APP_PASSWORD>@<mongodb-private-ip>:27017/appdb?authSource=appdb

Most MongoDB drivers accept this connection string directly. The shared mongosh equivalent is:

mongosh "mongodb://cloudimg:<MONGO_APP_PASSWORD>@<mongodb-private-ip>:27017/appdb?authSource=appdb"

Step 9: Database Storage

Database files and the WiredTiger journal are stored under /var/lib/mongodb, which is a separate filesystem on its own EBS volume. Confirm the dedicated mount and review free space with:

findmnt /var/lib/mongodb
df -h /var/lib/mongodb

Because the data directory is on its own volume, you can grow it independently of the operating system disk. Modify the EBS volume in the AWS console or with the CLI, then extend the filesystem on the instance with sudo resize2fs against the volume's device.

Step 10: Maintenance

Keep the operating system patched with the standard package manager. The official MongoDB APT repository is already configured on the image, so MongoDB Community Server upgrades are delivered through the normal package update process.

Review the database log files under /var/log/mongodb/ for slow operations and connection events. Use the mongotop and mongostat tools from the mongodb-database-tools package to monitor server activity, or connect a metrics collector to the diagnostic data under /var/lib/mongodb/diagnostic.data.

To take a logical backup of the appdb database, use mongodump authenticated as the application user, and restore with mongorestore. Run mongodump --help and mongorestore --help on the instance for the full set of options.

For a multi node replica set, add further nodes (each running this same image, or any compatible MongoDB build), reconfigure replication.replSetName in /etc/mongod.conf on every node, restart mongod.service, and run rs.initiate() followed by rs.add() from the primary's mongosh session.

Screenshots

Support

This Amazon Machine Image is provided by cloudimg with 24/7 technical support by email and chat. Contact cloudimg for help with deployment, replica set configuration, schema design, performance tuning, indexing and database administration.

MongoDB is a trademark of MongoDB, Inc. All other product and company names are trademarks or registered trademarks of their respective holders. Use of them does not imply any affiliation with or endorsement by them.