Skip to main content

External MongoDB

Appsmith runs embedded instances of MongoDB and Redis. It uses MongoDB and Redis for data storage and session management. You can also switch to external instances. Using external instances enable better performance and scalability. Follow the steps on this page to set up external MongoDB and Redis for Appsmith.

Attention

To use external MongoDB with Appsmith v1.9.0 onwards, you need MongoDB version 5 or higher. Follow the steps in the MongoDB official documentation to Upgrade a Replica Set to 5.0

External MongoDB​

Follow the steps below to configure Appsmith to use an external MongoDB instance:

Prerequisites​

  • A self-hosted Appsmith instance. See the installation guides for installing Appsmith.
  • Ensure that your external MongoDB instance has a replica set configuration in place. Connect to your database as the admin user and run rs.initiate(). Note that if you're using MongoDB Cloud excluding serverless instances of MongoDB Atlas, which don't support replica sets, the replica set configuration is already set up for you.
  • Ensure the MongoDB user account has readWrite and clusterMonitor roles assigned.
  • At least 2 GB of free storage space for backup and update tasks.
  • Before migrating your Appsmith instance to connect with the new MongoDB, make sure to perform a backup of the old MongoDB and restore it to the new MongoDB.

Configure instance​

On Appsmith, you can add your external MongoDB by using one of the below ways:

Admin settings​

You can use Admin Settings to set up an external MongoDB. The MongoDB URI property is present under Advanced Settings. Add your MongoDB URI to the setting and click the SAVE & RESTART button. The server restart establishes a connection with the external MongoDB.

Setup an external MongoDB using Admin settings
Setup an external MongoDB using Admin settings
info

If you have set values using environment variables for your instance, those values take precedence over values specified in the Admin Settings UI.

Environment variable​

To connect to an external MongoDB server, you need to update the environment variable APPSMITH_MONGODB_URI with your MongoDB credentials in the connection string format. If your password or username contains special characters, you need to URL encode them. For instance, if the password is Something@123, it should be URL encoded as Something%40123, like:

// Syntax
APPSMITH_MONGODB_URI=mongodb+srv://<USERNAME>:<PASSWORD>@<MONGO.HOST.NAME>/<DATABASENAME>

// Example - password encoded
APPSMITH_MONGODB_URI=mongodb://appsmithadmin:Something%40123@1.3.4.5:27017/appsmith?retryWrites=true

To learn how to URL encode your username and password, see Encode to URL-encoded format.

Restart the Appsmith container by using the below command:

docker-compose restart appsmith