MongoDB Docker Backup to a Workstation

First PublishedJun 16, 2026ByAtif Alam

This runbook covers backing up MongoDB that runs inside Docker on a remote Linux VPS and moving the data to a Mac workstation — either as a dated archive file or directly into a local MongoDB instance. It uses mongodump over SSH (stream or scp). For SSH keys and host aliases, see OpenSSH Client Keys. For backup theory and restore drills, see RDBMS reliability and on-call.

Use placeholders below — never paste production hostnames, container names, or passwords into tickets or docs.

Scenario

Remote: MongoDB in a Docker container on a Linux VPS you reach over SSH.
Local: Your Mac — save a .gz backup file or restore into a local mongod.
Method: docker exec … mongodump on the VPS, streamed or copied to the Mac.

Choose Your Path

Goal	Option	Best when
Restore now into local MongoDB	A — SSH pipe	Local `mongod` is running; you do not need a saved file
Archive a backup on disk (recommended)	B — `.gz` file	You want a dated file for drills or later restore
Pipe fails or you want files on the VPS first	C — dump + scp	Debugging remote dump, very large data, or unstable SSH stream

Prerequisites

On the Mac:

1
brew install mongodb-database-tools mongosh
2
# Optional: local MongoDB server (required for Option A)
3
brew tap mongodb/brew
4
brew install mongodb-community
5
brew services start mongodb-community   # before Option A only

Keep Database Tools close to the remote MongoDB major version (for example both on 7.x).

On the VPS: Docker running; you can docker exec into the MongoDB container.

SSH: Access to the VPS as a non-root user (or your team’s standard deploy user). See OpenSSH Client Keys for keys and ~/.ssh/config host aliases.

Disk space: Check before large dumps:

1
df -h ~                    # Mac destination (Options B/C)
2
ssh [email protected] 'df -h /tmp'   # VPS staging (Option C)

Variables

Set these once per session (adjust to your environment):

1
REMOTE_HOST=vps.example.com
2
SSH_USER=deploy
3
CONTAINER_NAME=myapp-mongo

Use a Host alias from ~/.ssh/config instead of SSH_USER@REMOTE_HOST if you prefer (for example ssh my-vps).

Find Credentials

On the VPS (after ssh ${SSH_USER}@${REMOTE_HOST}), inspect the container environment:

1
docker inspect "${CONTAINER_NAME}" | grep -A 20 '"Env"'

Common variables on the official MongoDB image:

MONGO_INITDB_ROOT_USERNAME
MONGO_INITDB_ROOT_PASSWORD

Or read your project compose file:

1
cat ~/app/docker-compose.yml   # path on the VPS

Do not rely on docker inspect for routine production credential lookup — use your secrets store or compose secrets. Never commit passwords to git.

No-auth dev containers: omit --username, --password, and --authenticationDatabase.

Single database only: add --db=mydb to mongodump to shrink the backup.

Option A — Stream Into Local MongoDB

Pipes the archive from the container to local mongorestore — no file is saved.

Requires local mongod running. This does not create a backup file on disk.

1
ssh "${SSH_USER}@${REMOTE_HOST}" \
2
  "docker exec ${CONTAINER_NAME} mongodump \
3
  --username=YOUR_USER \
4
  --password=YOUR_PASSWORD \
5
  --authenticationDatabase=admin \
6
  --archive --gzip" \
7
  | mongorestore --archive --gzip

Custom SSH key or port (same pattern for Options B and C):

1
ssh -i ~/.ssh/id_ed25519_deploy -p 22 "${SSH_USER}@${REMOTE_HOST}" ...

Restoring may merge with or duplicate databases already on your Mac. Use —drop on mongorestore only when you intend to replace existing local databases.

Option B — Save a `.gz` Archive on Mac (Recommended)

1
ssh "${SSH_USER}@${REMOTE_HOST}" \
2
  "docker exec ${CONTAINER_NAME} mongodump \
3
  --username=YOUR_USER \
4
  --password=YOUR_PASSWORD \
5
  --authenticationDatabase=admin \
6
  --archive --gzip" \
7
  > ~/mongo-backup-$(date +%Y%m%d).gz

Creates a file like ~/mongo-backup-20260616.gz.

Restore from the archive later

1
mongorestore --archive=~/mongo-backup-20260616.gz --gzip

Option C — Dump on VPS, Then `scp` to Mac

Use when piping fails or you want to inspect the dump on the server first.

1. Dump inside the container (on the VPS)

1
ssh "${SSH_USER}@${REMOTE_HOST}"
2
docker exec "${CONTAINER_NAME}" mongodump \
3
  --username=YOUR_USER \
4
  --password=YOUR_PASSWORD \
5
  --authenticationDatabase=admin \
6
  --out=/dump

2. Copy dump to the VPS host

1
docker cp "${CONTAINER_NAME}:/dump" /tmp/mongo-backup

3. Transfer to Mac (run on the Mac)

1
scp -r "${SSH_USER}@${REMOTE_HOST}:/tmp/mongo-backup" ~/mongo-backup

With a custom key or port:

1
scp -r -i ~/.ssh/id_ed25519_deploy -P 22 \
2
  "${SSH_USER}@${REMOTE_HOST}:/tmp/mongo-backup" ~/mongo-backup

4. Restore from the directory (on the Mac)

Option C produces a folder dump, not a gzip archive:

1
mongorestore ~/mongo-backup

5. Cleanup on the VPS

1
rm -rf /tmp/mongo-backup
2
docker exec "${CONTAINER_NAME}" rm -rf /dump

Verify the Restore

1
mongosh

Inside the shell:

1
show dbs
2
use mydb
3
db.stats()

You should see your restored database names listed.

Troubleshooting

Error	Cause	Fix
`Command listDatabases requires authentication`	Missing credentials on `mongodump`	Add `--username`, `--password`, `--authenticationDatabase=admin`
`I/O failure reading beginning of archive: EOF`	`mongodump` failed on the VPS; empty pipe	Run the remote command alone; fix errors before piping
`0 documents restored`	Empty or failed dump	Check VPS-side `mongodump` output
Wire version / tool version errors	Database Tools vs server mismatch	Align `mongodb-database-tools` major version with remote MongoDB

Quick Reference

Goal	Command
Backup to local MongoDB	`ssh … docker exec … mongodump --archive --gzip \| mongorestore --archive --gzip`
Backup to `.gz` on Mac	Same remote dump; redirect with `> ~/mongo-backup-$(date +%Y%m%d).gz`
Restore from `.gz`	`mongorestore --archive=~/mongo-backup-YYYYMMDD.gz --gzip`
Restore from directory (Option C)	`mongorestore ~/mongo-backup`
Verify	`mongosh` → `show dbs`
Find credentials (dev)	`docker inspect CONTAINER \| grep -A 20 '"Env"'`

Production Notes

mongodump is a standard logical backup for ops and migration. It is not a substitute for managed PITR, replica-set oplog backups, or vendor snapshot policies — see Backup, restore, and restore drills.

RDBMS reliability and on-call — RPO/RTO, restore drills, backup monitoring
Docker volumes and storage — where container data lives on disk
Docker Compose — typical MongoDB service definitions
OpenSSH client keys — SSH and scp setup
Stateful backup and restore on Kubernetes — different path for K8s-hosted databases