Skip to main content

​
Required tools

Capsule uses mongodump (from MongoDB Database Tools) and mongosh to connect and restore.
Install MongoDB Database Tools directly from MongoDB’s package repo — not via apt (the apt package is outdated and may be missing mongodump):
Do not use brew tap mongodb/brew on Linux — it installs macOS binaries that cannot run on Linux and will produce an exec format error.
Verify:

​
Connection details

​
Authentication

If your MongoDB instance uses authentication, provide the username and password. Capsule builds a mongodb:// connection URI (with your credentials embedded and URL-encoded) and passes it to mongodump via --uri.
Unlike the PostgreSQL and MySQL integrations, this URI is passed as a plain command-line argument — for the duration of the backup, it’s visible to anyone on the same server who can run ps aux or read /proc/<pid>/cmdline on that process. If you’re on a server shared with other users you don’t fully trust, keep this in mind.

​
Replica sets and Atlas

For a replica set, enter any member’s host in the Host field. Capsule does not force a direct, single-node connection — mongodump will attempt normal replica set topology discovery from that seed host, the same as connecting with any standard MongoDB client. This means the other replica set members need to be reachable (by whatever hostname the replica set itself advertises them as) from the machine running Capsule, not just the one host you entered. For MongoDB Atlas, use the connection hostname from your Atlas dashboard (e.g., cluster0.abcde.mongodb.net) — Capsule detects the .mongodb.net suffix and automatically uses the mongodb+srv:// scheme instead of a plain host:port, which is what Atlas’s DNS-seedlist connection format requires.

​
Docker

If MongoDB runs in a container, enter the container name when adding the connection. Capsule will exec mongodump inside the container via docker exec.

​
Troubleshooting

mongodump: command not found The mongodb-database-tools package is separate from the MongoDB server. Install it explicitly and run capsule doctor to confirm. mongosh: command not found mongosh is a separate package from mongodb-database-tools. Install it alongside the tools (see installation steps above). Auth failed Ensure the user has the backup built-in role or equivalent read access on the target database.