Skip to main content

Custom Domain and SSL

This page explains how to configure SSL for your custom domain on a self-hosted Appsmith instance, ensuring secure HTTPS connections for your applications.

info

For Kubernetes installations, see Configure TLS for Kubernetes.

Prerequisites​

Before configuring SSL for your custom domain, ensure you have the following:

  1. A self-hosted Appsmith instance installed. If not already installed, refer to the installation guides. This guide assumes you are working with an existing installation.
  2. A custom domain purchased from a domain provider, such as:
  3. Ports 80 and 443 must be open and accessible. If using custom ports, ensure they are also open and accessible.
  4. Access to Admin Settings in your Appsmith instance.

Configure SSL​

You can use your custom domain with the HTTP protocol, even if you haven’t set up an SSL certificate. To ensure secure connections using HTTPS, it’s recommended to configure SSL. You can choose from the following two methods:

SSL using Let’s Encrypt certificate​

Attention

Let's Encrypt does not support provisioning a certificate for ephemeral domain names since they are high-risk.

Follow these steps to generate and maintain an SSL certificate for your custom domain using Let’s Encrypt:

  1. Go to the Admin Settings in your Appsmith instance.

  2. Click Advanced Settings from the left navigation.

  3. Add your custom domain name to the Custom Domain field.

  4. Click the SAVE & RESTART button.

When Appsmith restarts, it will generate an SSL certificate for your custom domain. Access your Appsmith instance via HTTPS on port 443.

SSL using custom certificate​

Follow these steps to configure SSL using a custom SSL Certificate:

  1. Rename the certificate file as fullchain.pem and the key file as privkey.pem.

  2. Verify that the private key file is valid by running the following command in the terminal:

    openssl pkey -in privkey.pem -pubout -outform pem | sha256sum

    When prompted enter the pass phrase. Take a note of the hash generated by the command.

  3. Verify the public key in the certificate using this command:

    openssl x509 -in fullchain.pem -pubkey -noout -outform pem | sha256sum

    Verify the hash generated by above command with the hash generated by the command in step 2. Both checks produce matching hashes, confirming the integrity of the certificate and key pair.

  4. Copy these files into the subdirectory <MOUNTING-DIRECTORY>/ssl/. Ensure that you change <MOUNTING-DIRECTORY> by the mounting volume directory available in the docker-compose.yml. For example, the default value is ./stacks.

  5. Go to the Admin Settings in your Appsmith instance. Under Advanced Settings - add your custom domain name to the Custom Domain field, and click the SAVE & RESTART button. You can also set up the custom domain using a custom domain environment variable.

  6. Open the terminal, go to the Appsmith installation directory, and restart the container using the below command:

    docker-compose restart appsmith

    The container uses the certificate present in the <MOUNTING-DIRECTORY>/ssl folder.

Troubleshooting​

You may face SSL/TLS certificate error while configuring SSL, follow the below guide to troubleshoot:

If you continue to face issues, contact the support team using the chat widget at the bottom right of this page.

See also​