Skip to main content

Managed MongoDB

info

This feature was introduced in Defang v1.2.0 released on June 3, 2025 for AWS. Upgrade to the latest version

Managed MongoDB is a service that allows you to store and retrieve large amounts of data in a document-oriented format. MongoDB is ideal for storing unstructured data like JSON documents, making it a popular choice for modern applications.

Current Support​

ProviderManaged MongoDB
Playground⚠️ Unmanaged
AWS✅ DocumentDB
DigitalOcean⚠️ Unmanaged
GCP✅ Firestore

How to use Managed MongoDB​

To use managed MongoDB, in your compose.yaml file, use the x-defang-mongodb extension to define your MongoDB service. Adding the extension will tell Defang to provision a managed instance, rather than running MongoDB as a container.

Required Configuration​

AWS​

When using managed MongoDB on AWS, you must set a username and password for the database. By default, these are read from the MONGO_INITDB_ROOT_USERNAME and MONGO_INITDB_ROOT_PASSWORD config variables, following the official MongoDB container image convention.

You can set these using the following commands:

defang config set MONGO_INITDB_ROOT_USERNAME <your-username>
defang config set MONGO_INITDB_ROOT_PASSWORD <your-password>

If you do not provide these values, the deployment will fail.

GCP​

When using managed MongoDB on GCP, you must set a MONGO_INITDB_DATABASE environment variable with the name of the database to create.

Defang will automatically create a config variable named <SERVICE_NAME>_URL that contains the connection string for your MongoDB database. For example, if your service is named db, the config variable will be DB_URL.

Important: GCP will ignore MONGO_INITDB_ROOT_USERNAME and MONGO_INITDB_ROOT_PASSWORD credentials since they are not needed. GCP automatically handles authentication and grants your service access to the MongoDB database.

Example​

services:
  app:
    # [...]
    environment:
      DB_URL: mongodb://$MONGO_INITDB_ROOT_USERNAME:$MONGO_INITDB_ROOT_PASSWORD@db:27017/
    depends_on:
      - db

  db:
    image: mongo:5
    x-defang-mongodb: true
    environment:
      MONGO_INITDB_DATABASE: mydb
Deleting a GCP Firestore MongoDB Database

Please be aware that GCP Firestore does not allow deletion of your database when you bring down your project using defang compose down. You must go to the GCP Cloud Console for Firestore to delete it manually.

Version

AWS DocumentDB is compatible with MongoDB 3.6, 4.0, and 5.0. The mongo:5 image is compatible with DocumentDB 5.0, so we recommend using this version for your MongoDB service. Deployment will fail for versions higher than 5.

GCP Firestore does not have a configurable version.