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 Ingress and TLS.

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:

Custom domain format

Enter only the domain or hostname—for example, apps.example.com or subdomain.example.com. Do not include a protocol (http:// or https://), a port, a path, or a trailing slash.

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 Instance settings from the left navigation.

  3. Add your custom domain to the Custom Domain field as a plain hostname only (no http://, https://, port, path, or trailing slash).

  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

    Take a note of the hash generated by the command.

    Prompted for a pass phrase? Expand for next steps

    Appsmith uses Caddy as its internal reverse proxy, and Caddy cannot load password-protected (encrypted) private keys. If you skip removing the passphrase, Caddy will fail to start and Appsmith will not be accessible over HTTPS.

    Remove the passphrase before proceeding by running:

    openssl pkey -in privkey.pem -out privkey-decrypted.pem
    mv privkey-decrypted.pem privkey.pem

    You will be prompted once for the existing passphrase. After this, re-run the verification command above to capture the hash.

  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 Instance settings, add your custom domain to the Custom Domain field as a plain hostname only (no http://, https://, port, path, or trailing slash), 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​