MongoDB

Add this database from the dashboard

Since Dashboard 1.29.0 and Agent 1.19.0, you can add this database directly from the dashboard (Add database on the agent page), without editing any file. See Adding a Database. The settings described below also apply to the dashboard form.

The agent will use mongodump to perform backups and mongorestore to restore backups.

Configuration

When running portabase agent db add, select mongodb as the database type.

MongoDB Atlas / Cloud (SRV)

Managed MongoDB clusters (MongoDB Atlas and equivalents) are reached through a DNS SRV record instead of a fixed host and port. The connection string uses the mongodb+srv:// scheme.

To use an SRV connection, omit the port field (or set it to 0). The agent detects this and automatically switches to mongodb+srv://. Use the cluster hostname (ending in .mongodb.net) as the host.

Via CLI: run portabase agent db add, choose mongodb, then set the port to 0 (--port 0) to enable the SRV connection.

databases.json

{
  "name": "MongoDB Cluster Cloud",
  "database": "mydb",
  "type": "mongodb",
  "username": "username",
  "password": "password",
  "host": "cluster0.abcde.mongodb.net",
  "generated_id": "..."
}

Generate UUID for your configuration

Generating...

No port is set for SRV connections. When port is absent (or 0), the agent builds a mongodb+srv://user:password@host/database?authSource=admin URI. With authentication, the credentials are URL-encoded automatically and authSource=admin is appended. Without a username and password, the URI is built without credentials or query string.

Options

The following optional fields can be set under an options key in the database configuration. They map to standard MongoDB connection-string query parameters.

Option	Type	Default	Description
`auth_source`	`string`	`admin` (when credentials are set)	The authentication database. Sets `authSource` on the URI. Override when your user is defined in a database other than `admin`.
`replica_set`	`string`	—	Replica set name. Sets `replicaSet` on the URI. Required when connecting to a self-hosted replica set.
`tls`	`boolean`	`false`	When `true`, appends `tls=true` to the URI to force a TLS connection.

databases.json (with options)

{
  "name": "Database - MongoDB",
  "type": "mongodb",
  "host": "db-mongodb",
  "port": 27017,
  "username": "username",
  "password": "password",
  "database": "app_db",
  "generated_id": "...",
  "options": {
    "auth_source": "admin",
    "replica_set": "rs0",
    "tls": true
  }
}

When credentials are set and auth_source is omitted, the agent defaults authSource to admin (unchanged behaviour). Values are URL-encoded automatically.

Replica Set (multiple hosts)

To connect to a self-hosted replica set, put a comma-separated host list in the host field and omit port (each host carries its own port). Set the replica_set option to the replica set name.

databases.json (replica set)

{
  "name": "Database - MongoDB Replica Set",
  "type": "mongodb",
  "host": "mongodb0.example.internal:27017,mongodb1.example.internal:27017,mongodb2.example.internal:27017",
  "username": "myDatabaseUser",
  "password": "myPassword",
  "database": "myDB",
  "generated_id": "...",
  "options": {
    "replica_set": "myRepl"
  }
}

This builds mongodb://myDatabaseUser:myPassword@mongodb0.example.internal:27017,mongodb1.example.internal:27017,mongodb2.example.internal:27017/myDB?authSource=admin&replicaSet=myRepl.

A comma in host marks a replica-set host list: the agent uses it verbatim (never SRV) and does not append a single port. Ports go inside the host list. If you omit ports in the list (host1,host2,host3), the MongoDB driver defaults each to 27017.

An empty port means different things depending on the host: a comma list is a replica set, a single .mongodb.net host is SRV (mongodb+srv://), and a single regular host requires a port. In the dashboard form, leave Port empty only for a replica-set list or an SRV cluster.

Docker Compose Example

Example with a MongoDB image.

docker-compose.yml

services:
    db-mongodb-auth:
        container_name: db-mongodb-auth
        image: mongo:latest
        ports:
          - "27082:27017"
        environment:
          MONGO_INITDB_ROOT_USERNAME: root
          MONGO_INITDB_ROOT_PASSWORD: rootpassword
          MONGO_INITDB_DATABASE: testdbauth
        command: mongod --auth
        networks:
          - portabase
        volumes:
          - mongodb-data-auth:/data/db
        healthcheck:
          test: [ "CMD", "mongosh", "--eval", "db.adminCommand('ping')" ]
          interval: 5s
          timeout: 5s
          retries: 10

    db-mongodb:
        container_name: db-mongodb
        image: mongo:latest
        ports:
          - "27083:27017"
        volumes:
          - mongodb-data:/data/db
        healthcheck:
          test: [ "CMD", "mongosh", "--eval", "db.adminCommand('ping')" ]
          interval: 5s
          timeout: 5s
          retries: 10
        environment:
          MONGO_INITDB_DATABASE: testdb
        networks:
          - portabase

    agent:
        image: portabase/agent:latest
        # ... agent configuration ...
        depends_on:
          - db-mongodb
          - db-mongodb-auth
        networks:
          - portabase

networks:
  portabase:
    external: true

volumes:
  mongodb-data:
  mongodb-data-auth:

If you use localhost as the host (because the agent is on the host machine and not in Docker, or via host-gateway), ensure your database is listening on all interfaces (0.0.0.0) or is accessible from the agent.

Configuration

MongoDB Atlas / Cloud (SRV)

Options

Replica Set (multiple hosts)

Docker Compose Example

On this page