Skip to main content

​
Steps to Follow

The following steps can be used to enable SSL for a single ClickHouse Server using Let’s Encrypt, a free, automated, and open Certificate Authority (CA) designed to make it easy for anyone to secure their websites with HTTPS. By automating the certificate issuance and renewal process, Let’s Encrypt ensures websites remain secure without requiring manual intervention.
We assume ClickHouse has been installed at the standard package locations in the following guide. We use the domain product-test-server.clickhouse-dev.com for all examples. Substitute your domain accordingly.
  1. Verify you have a DNS A or AAAA record pointing to your server. This can be achieved using the Linux tool dig. For example, the response for product-test-server.clickhouse-dev.com if using the Cloudflare DNS server 1.1.1.1:

Notice the section below confirming the presence of an A record.
  1. Open port 80 on your server. This port will be used for automatic certificate renewal using the ACME protocol with certbot. For AWS, this can be achieved by modifying the instance’s associated Security Group.

  1. Install certbot e.g. using apt

  1. Obtain an SSL certificate

We don’t have a web server running on our server, so use (1) allowing Certbot to use a standalone temporary web server.
Enter the full domain name of your server e.g. product-test-server.clickhouse-dev.com when requested.
Let’s Encrypt has a policy of not issuing certificates for certain types of domains, such as public cloud provider-generated domains (e.g., AWS *.compute.amazonaws.com domains). These domains are considered shared infrastructure and are blocked for security and abuse prevention reasons.
  1. Copy certificates to the ClickHouse directory.

This command sets up a cron job to automate the management of Let’s Encrypt SSL certificates for a ClickHouse server. It runs every minute as the root user, copying the .pem files from the Let’s Encrypt directory to the ClickHouse server’s configuration directory, but only if the files have been updated. After copying, the script adjusts the ownership of the files to the clickhouse user and group, ensuring the server has the required access. It also sets secure read-only permissions (chmod 400) on the copied files to maintain strict file security. This ensures that the ClickHouse server always has access to the latest SSL certificates without requiring manual intervention, maintaining security and minimizing operational overhead.
  1. Configure the use of these certificates in clickhouse-server.

  1. Restart ClickHouse Server

  1. Validate ClickHouse can communicate over SSL

For this last step to work you may need to ensure port 8443 is accessible e.g. included in your Security Group in AWS. Alternatively, if you only want to access ClickHouse from the server, modify your hosts file i.e.
If you open connections from wildcard addresses, make sure that at least one of the following measures is applied:
  • server is protected by firewall and not accessible from untrusted networks;
  • all users are restricted to a subset of network addresses (see users.xml);
  • all users have strong passwords, only secure (TLS) interfaces are accessible, or connections are only made via TLS interfaces.
  • users without passwords have read-only access.
See also: https://www.shodan.io/search?query=clickhouseThe blog Building single page applications with ClickHouse can be used as guidance for securing public instances.
The following should also work if connecting from the local machine on which ClickHouse is running. To connect via product-test-server.clickhouse-dev.com open port 9440 in your:
Last modified on July 3, 2026