External MongoDB and Redis
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.
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
andclusterMonitor
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.
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
External Redis
You can add your external Redis to Appsmith using one of the below ways:
Admin settings
You can use Admin Settings to set up an external Redis. The Redis URL property is present under Advanced Settings. Add your Redis URL to the setting and click the SAVE & RESTART button. The server restart establishes a connection with the external Redis.
Environment variable
To connect to an external Redis server, update the environment variable APPSMITH_REDIS_URL
:
APPSMITH_REDIS_URL=redis://hostname:6379
Restart the Appsmith container by using the below command:
docker-compose restart appsmith
Troubleshooting
If you are facing issues during deployment, please refer to the guide on troubleshooting deployment errors. If you continue to face issues, contact the support team using the chat widget at the bottom right of this page.