MongoDB Compass is MongoDB’s free desktop GUI: browse collections, edit documents, build queries and aggregation pipelines visually, inspect indexes and explain() plans. Connecting it to MongoDB on your VPS is easy, but it must be done securely: exposed, unauthenticated MongoDB servers are one of the most common causes of data leaks and ransom attacks.

Step 1: enable authentication

A fresh MongoDB install allows anyone who can reach the port to do anything. Create an admin user first (on the server):

mongosh
use admin
db.createUser({
  user: "admin",
  pwd: passwordPrompt(),
  roles: [ { role: "userAdminAnyDatabase", db: "admin" }, { role: "readWriteAnyDatabase", db: "admin" } ]
})

Turn authorization on in /etc/mongod.conf:

security:
  authorization: enabled
sudo systemctl restart mongod
mongosh -u admin -p --authenticationDatabase admin

For day-to-day work, create users with only the roles they need (for example readWrite on one database). See installing MongoDB on Ubuntu.

Keep MongoDB listening on localhost only (the default bindIp: 127.0.0.1), and reach it through SSH. Nothing new is exposed to the internet.

Compass’s built-in SSH tunnel: New Connection → Advanced Connection Options → Proxy/SSH:

  • SSH Hostname: your server’s IP; SSH Port: 22;
  • SSH Username: your Linux user;
  • authentication: identity file (your private key) or password.

Then use the connection string as if you were on the server:

mongodb://admin:[email protected]:27017/?authSource=admin

Or a manual tunnel, which works with any tool:

ssh -N -L 27018:127.0.0.1:27017 [email protected]

and connect Compass to mongodb://admin:[email protected]:27018/?authSource=admin. See SSH tunnels and port forwarding and SSH keys with ssh-keygen.

Option B: direct connection (only with protection)

If applications on other servers need direct access, open MongoDB carefully:

  1. Bind to the private or public interface as well as localhost:
net:
  port: 27017
  bindIp: 127.0.0.1,10.0.0.5
  1. Firewall: allow only specific source IPs:
sudo ufw allow from 198.51.100.7 to any port 27017 proto tcp
  1. TLS: encrypt connections, especially across the internet:
net:
  tls:
    mode: requireTLS
    certificateKeyFile: /etc/ssl/mongodb/mongodb.pem
  1. Authentication enabled (step 1), with strong passwords.

Then connect Compass with mongodb://user:[email protected]:27017/?authSource=admin&tls=true.

Never open 27017 to 0.0.0.0/0 without auth. Automated scanners find such servers within hours. See UFW firewall.

Replica sets

For a replica set, connect with all members and the set name, so Compass can find the primary:

mongodb://user:PASSWORD@db1:27017,db2:27017,db3:27017/?replicaSet=rs0&authSource=admin

Through an SSH tunnel, add directConnection=true to connect to one member directly. Otherwise, the driver tries to reach members by the hostnames in the replica set config, which aren’t reachable from your laptop. See MongoDB replica sets.

Troubleshooting

Error Likely cause
connect ECONNREFUSED MongoDB not running, or bound to localhost while connecting directly
Timeout Firewall or provider security group blocking the port; wrong IP
Authentication failed Wrong password or wrong authSource (users created in admin need authSource=admin)
not authorized on db to execute command User lacks a role for that database
SSH tunnel errors Wrong key or username; test with plain ssh user@host first
getaddrinfo ENOTFOUND db2 Replica set hostnames not resolvable; use directConnection=true

Check what MongoDB listens on with sudo ss -tlnp | grep 27017. See ss and netstat.

Alternatives to Compass

  • mongosh over SSH: always available on the server.
  • VS Code MongoDB extension: queries from your editor.
  • Studio 3T (commercial) and NoSQLBooster: richer GUIs.
  • mongo-express: a web UI. If you run it, keep it behind authentication and an SSH tunnel or VPN.

Quick reference

Goal Setting
Require login security.authorization: enabled
Safest access SSH tunnel; bindIp: 127.0.0.1
Direct access bindIp + firewall allowlist + TLS
Users in admin DB ?authSource=admin
Replica set via tunnel directConnection=true

Related: MongoDB performance and database security.

  • MongoDB
  • SSH
  • Database