diff --git a/website/docs/getting-started/setup/instance-configuration/custom-mongodb-redis.md b/website/docs/getting-started/setup/instance-configuration/custom-mongodb-redis.md index 669076f5b5..cfb839d549 100644 --- a/website/docs/getting-started/setup/instance-configuration/custom-mongodb-redis.md +++ b/website/docs/getting-started/setup/instance-configuration/custom-mongodb-redis.md @@ -3,19 +3,13 @@ sidebar_position: 3 toc_max_heading_level: 4 --- -# External MongoDB and Redis +# 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. +Appsmith defaults to an embedded MongoDB database. Users may also choose to set up an external MongoDB instance to host Appsmith data. This page provides instructions for configuring an external MongoDB database for Appsmith. -:::caution 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](https://www.mongodb.com/docs/manual/release-notes/5.0-upgrade-replica-set/) -::: +## Prerequisites -## External MongoDB - -Follow the steps below to configure Appsmith to use an external MongoDB instance: - -### Prerequisites +Before you begin with the setup, ensure that your environment meets the necessary requirements. - A self-hosted Appsmith instance. See the [installation guides](/getting-started/setup/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()](https://docs.mongodb.com/manual/reference/method/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. @@ -23,78 +17,54 @@ Follow the steps below to configure Appsmith to use an external MongoDB instance - 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](/getting-started/setup/instance-management/appsmithctl#backup-database) of the old MongoDB and [restore](/getting-started/setup/instance-management/appsmithctl#restore-database) it to the new MongoDB. -### Configure instance +## Set up external MongoDB instance -On Appsmith, you can add your external MongoDB by using one of the below ways: +To use an external MongoDB instance with Appsmith, you can either use an existing instance or set up a new one. Follow these steps: -- [Admin Settings](#admin-settings) -- [Environment Variables](#environment-variable) +1. Select or create a MongoDB instance. If you don’t already have an instance, you can either create one on your infrastructure or use a cloud provider like MongoDB Atlas. For setting up MongoDB on an Azure VM, follow this guide. -#### Admin settings +2. Connect to your MongoDB instance as the admin user and run `rs.initiate()` to enable replica set configuration. -You can use [Admin Settings](/getting-started/setup/instance-configuration#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. +3. Ensure the MongoDB user account that Appsmith will use has `readWrite` and `clusterMonitor` roles assigned. - +4. If migrating to an external MongoDB, restore your Appsmith database backup to the new MongoDB instance. For more information, see the Restore Appsmith database guide. -:::info -If you have set values using [environment variables](#environment-variables) for your instance, those values take precedence over values specified in the Admin Settings UI. -::: +## Connect Appsmith to external MongoDB -#### Environment variable +Follow these steps to configure Appsmith to connect to an external MongoDB instance: -To connect to an external MongoDB server, you need to update the environment variable `APPSMITH_MONGODB_URI` with your [MongoDB](https://www.mongodb.com/cloud) 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: -```js -// Syntax -APPSMITH_MONGODB_URI=mongodb+srv://:@/ +1. Go to the directory containing the Appsmith configuration file, such as `docker.env` for Docker or `values.yaml` for Kubernetes. -// 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](https://www.urlencoder.org/). +2. Set the `APPSMITH_MONGODB_URI` environment variable with the following format: +
+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: -Restart the Appsmith container by using the below command: +```js +// Syntax +APPSMITH_MONGODB_URI=mongodb+srv://:@/ -```bash -docker-compose restart appsmith +// Example - password encoded +APPSMITH_MONGODB_URI=mongodb://appsmithadmin:Something%40123@1.3.4.5:27017/appsmith?retryWrites=true ``` -## External Redis - -You can add your external Redis to Appsmith using one of the below ways: - -- [Admin Settings](#admin-settings-1) -- [Environment Variables](#environment-variable-1) - -#### Admin settings +To learn how to URL encode your username and password, see Encode to URL-encoded format. -You can use [Admin Settings](/getting-started/setup/instance-configuration#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`: +3. Restart the Appsmith server after setting `APPSMITH_MONGODB_URI` to establish a connection with the external MongoDB database. -```bash -APPSMITH_REDIS_URL=redis://hostname:6379 -``` - -Restart the Appsmith container by using the below command: +
```bash docker-compose restart appsmith ``` -## Troubleshooting - -If you are facing issues during deployment, please refer to the guide on [troubleshooting deployment errors](/help-and-support/troubleshooting-guide/deployment-errors). If you continue to face issues, contact the support team using the chat widget at the bottom right of this page. - -## Further reading - -- [Container logs](/getting-started/setup/instance-management/how-to-get-container-logs) -- [Instance Management](/getting-started/setup/instance-management) +
\ No newline at end of file diff --git a/website/docs/getting-started/setup/instance-configuration/custom-redis.md b/website/docs/getting-started/setup/instance-configuration/custom-redis.md new file mode 100644 index 0000000000..669076f5b5 --- /dev/null +++ b/website/docs/getting-started/setup/instance-configuration/custom-redis.md @@ -0,0 +1,100 @@ +--- +sidebar_position: 3 +toc_max_heading_level: 4 +--- + +# 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. + +:::caution 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](https://www.mongodb.com/docs/manual/release-notes/5.0-upgrade-replica-set/) +::: + +## 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](/getting-started/setup/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()](https://docs.mongodb.com/manual/reference/method/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](/getting-started/setup/instance-management/appsmithctl#backup-database) of the old MongoDB and [restore](/getting-started/setup/instance-management/appsmithctl#restore-database) it to the new MongoDB. + +### Configure instance + +On Appsmith, you can add your external MongoDB by using one of the below ways: + +- [Admin Settings](#admin-settings) +- [Environment Variables](#environment-variable) + +#### Admin settings + +You can use [Admin Settings](/getting-started/setup/instance-configuration#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. + + + +:::info +If you have set values using [environment variables](#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](https://www.mongodb.com/cloud) 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: + +```js +// Syntax +APPSMITH_MONGODB_URI=mongodb+srv://:@/ + +// 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](https://www.urlencoder.org/). + + + + +Restart the Appsmith container by using the below command: + +```bash +docker-compose restart appsmith +``` + +## External Redis + +You can add your external Redis to Appsmith using one of the below ways: + +- [Admin Settings](#admin-settings-1) +- [Environment Variables](#environment-variable-1) + +#### Admin settings + +You can use [Admin Settings](/getting-started/setup/instance-configuration#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`: + +```bash +APPSMITH_REDIS_URL=redis://hostname:6379 +``` + +Restart the Appsmith container by using the below command: + +```bash +docker-compose restart appsmith +``` + +## Troubleshooting + +If you are facing issues during deployment, please refer to the guide on [troubleshooting deployment errors](/help-and-support/troubleshooting-guide/deployment-errors). If you continue to face issues, contact the support team using the chat widget at the bottom right of this page. + +## Further reading + +- [Container logs](/getting-started/setup/instance-management/how-to-get-container-logs) +- [Instance Management](/getting-started/setup/instance-management) diff --git a/website/sidebars.js b/website/sidebars.js index ddccb3f123..2b4bcca0d9 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -161,6 +161,7 @@ const sidebars = { ], }, 'getting-started/setup/instance-configuration/custom-mongodb-redis', + 'getting-started/setup/instance-configuration/custom-redis', 'getting-started/setup/instance-configuration/disable-intercom', 'getting-started/setup/instance-configuration/google-maps', 'getting-started/setup/instance-configuration/disable-user-signup',