Skip to main content

Configure Instance

This page provides instructions on how to configure your self-hosted Appsmith instance. You can configure a self-hosted Appsmith instance by choosing any one of the below options:

Admin settings

The Admin Settings page allows instance administrators on self-hosted instances to manage instance configurations, including email, authentication, Google Maps integration, as well as user settings and permissions.

info

If you don’t see the Admin Settings icon on the top-right corner, you’re not an Instance Administrator for the Appsmith instance and must be granted instance administrator role by an existing instance administrator.

Admin Settings option is available in the left sidebar
Access admin settings from the top-right corner of the homepage.
info

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

Add Instance Administrator

Users who are granted the Instance Administrator role have full access to all the instance settings. If you want to grant Instance Administrator privileges to a user, add their email address to the Admin email field in the Settings > General section. Doing so automatically assigns them the Instance Administrator role, giving them full access to manage instance settings. For more information about Instance Administrator role, see Instance Administrator Role reference.

Add emails to assign the Instance Administrator role
Add emails to assign the Instance Administrator role

Configure instance

The Admin settings enable the configuration of various settings such as user authentication, email notifications, integrations, and more using the user interface for your self-hosted Appsmith instance.

Use Admin Settings to configure your instance
Configure Your Appsmith Instance
NameTypeDescription
Instance NameGeneralModify the name of self-hosted instance
Admin EmailGeneralSpecify user emails whom you want to make the instance administrators of your self-hosted instance. Add comma-separated user's email to add more than one instance administrator.
Generated Docker Compose FileGeneralGenerate the Docker Compose file, which defines services for your Appsmith instance.
Share anonymous usage dataGeneralChoose whether to share anonymous usage data with Appsmith to help improve the product.
Appsmith WatermarkGeneralUpgrade to Appsmith Commercial Edition to remove the Built on qppsmith_ badge on the app's bottom right corner.
User Session LimitGeneralWhen enabled, limits users to a single active session.
Session TimeoutGeneralSets a defined period of time, after which sessions with no user activity are automatically logged out. The minimum time you can set is 1 minute, and the maximum is 30 days, in DD:HH:MM format. The feature is exclusive to self-hosted, Commercial Edition instances.
Embed SettingsGeneralConfigure to allow users to embed Appsmith in external applications. You may choose to enable embedding on any domain, limit it to certain domains, or disable it completely.
EmailEmailConfigure Email on your Appsmith instance. For more information, see Email.
Google MapsGoogle MapsConfigure to use the Maps widget on your instance. For more information, see Google Maps.
AuthenticationAuthenticationConfigure the authentication type like Google OAuth, GitHub OAuth. If you are on the Appsmith Commercial Edition, you can also configure authentication using popular Single Sign-on (SSO) authentication protocols such as SAML and OpenID Connect.
MongoDB URIAdvancedConfigure to use an external MongoDB database for your self-hosted instance. For more information about how to configure external MongoDB, see Custom MongoDB & Redis.
Redis URLAdvancedConfigure to use an external Redis instance for your self-hosted instance. For more information about how to configure external Redis, see Custom MongoDB & Redis.
Custom DomainAdvancedConfigure to set up a custom domain for your Appsmith instance.
VersionVersionShows the current version of Appsmith.
BrandingBrandingAppsmith custom branding feature is exclusive to self-hosted, Commercial Edition instances. It enables you to personalize workspaces and apps, including the login screen, invite emails, and error pages to match your company's branding. For more information about how to customize and apply branding, see Branding.
Access ControlAccess ControlAccess control is a feature exclusive to Appsmith Commercial Edition users that implements Role Based Access Control by assigning specific permissions to different user roles. For more information, see Access Control.
Audit LogsOthersThe audit log feature in Appsmith is only available to Appsmith Commercial Edition users and provides a record of all significant activities on the platform. For more information, see Audit Logs.

Environment variables

You may also choose to configure your self-hosted Appsmith instance using environment variables. For more information about available environment variables in Appsmith, see Environment Variables reference.

Configure Docker installations

To configure a docker installation, go to your installation folder and edit the stacks/configuration/docker.env file with the environment variables for the service. For example, you wish to add the Google Maps API key. Add/update the environment variable APPSMITH_GOOGLE_MAPS_API_KEY and add the Google API key to it as shown below:

APPSMITH_GOOGLE_MAPS_API_KEY=YOUR_API_KEY

After making changes, be sure to restart the docker containers for the changes to take effect. Run the below command to restart the Appsmith container.

  • Docker run
     docker restart appsmith
  • Docker Compose
     docker-compose restart appsmith

Configure Helm installations

You can modify your Appsmith installation on Kubernetes using a values.yaml file. Follow these steps to update the values:

  1. Go to the root directory of your installation.

  2. Generate the values.yaml file with:

helm show values appsmith/appsmith > values.yaml
  1. Modify the parameter values in the values.yaml file available under the applicationConfig section. For example, if you want to change the email address from which your messages are sent, as shown below:
applicationConfig:
APPSMITH_MAIL_FROM:"test@test.com"
  1. Update the values with:
helm upgrade appsmith appsmith/appsmith -f values.yaml -n appsmith

Configure ECS installations

To configure an ECS installation, follow these steps:

  1. Navigate to the ECS console and select Task Definitions on the sidebar.
  2. Click the Task Definition used by your ECS instance, and hit Create new revision.
  3. On the Task Definition config page, click the Appsmith container definition to edit it. In the Environment Section, enter the environment configuration as key-value pairs, as shown below.

ECS environment image

It's recommended to use AWS Secrets for sensitive information. Follow these steps to create a secret. Use the ARN of the secret as the Environment value and set the option to ValueFrom.

  1. Hit the Update button, and hit Create to make a new task definition.
  2. Navigate back to the ECS console and select your cluster. Click your service to open the service details.
  3. Click Update, and select the latest revision of the Task Definition.
  4. Hit Skip to review and then Update Service. The screen below shows the status.

Instance configuration ECS service restart image

It may take a minute for the new ECS Task to start running.

Further reading