HTTPS Setup Tutorial

Install TLS/SSL certificate and enable HTTPS

This tutorial leads you through the process of enabling HTTPS for your Structr instance. The HTTPS certificate used is provided by Let’s Encrypt.

Create and use Let's Encrypt certificates

Let’s Encrypt is a free, automated, and open Certificate Authority. From version 3.5 upwards, Structr has support for Let’s Encrypt certificate generation built in, using the ACME protocol.

The only mandatory configuration setting is the letsencrypt.domains list. The Let’s Encrypt client should just work with the default settings for any other parameter. Still, you can use the following configuration parameters in structr.conf to individually configure the client:

Name Description
letsencrypt.wait Wait for this amount of seconds before trying to authorize challenge. Default is 300 seconds (5 minutes).
letsencrypt.challenge.type Challenge type for Let’s Encrypt authorization. Possible values are ‘http’ and ‘dns’.
letsencrypt.domains Space-separated list of domains to fetch and update Let’s Encrypt certificates for
letsencrypt.production.server.url URL of Let’s Encrypt server. Default is ‘acme://letsencrypt.org’
letsencrypt.staging.server.url URL of Let’s Encrypt staging server for testing only. Default is ‘acme://letsencrypt.org/staging’.
letsencrypt.user.key.filename File name of the Let’s Encrypt user key. Default is ‘user.key’.
letsencrypt.domain.key.filename File name of the Let’s Encrypt domain key. Default is ‘domain.key’.
letsencrypt.domain.csr.filename File name of the Let’s Encrypt CSR. Default is ‘domain.csr’.
letsencrypt.domain.chain.filename File name of the Let’s Encrypt domain chain. Default is ‘domain-chain.crt’.
letsencrypt.key.size Encryption key length. Default is 2048.

Structr’s Let’s Encrypt client handles the http and dns challenge and will create a certificate and a Java (PKCS#12) key store file automatically. After successful creation of a key store file, Structr has to be restarted to use the new certificate.

Creating/updating a certificate can be triggered by the following HTTP request to the corresponding maintenance command:

curl -XPOST -HX-User:admin -HX-Password:admin http://localhost:8082/structr/rest/maintenance/letsencrypt -d '{"server":"production","challenge":"http","wait":"10", "reload": true}'

With the parameter server you can choose between staging and production mode. Staging mode is meant for testing and will generate invalid dummy certificates only, while production creates real, valid certificates but is throttled.

Using the parameter challenge, you can overwrite the default challenge method as set in structr.conf. This is convenient to test an alternative challenge type without the need to restart the Structr instance.

By setting a value for the wait parameter, you can let the client wait for the given period (in seconds) in order to have enough time to prepare the DNS TXT record in case of the dns challenge type, or the HTTP response in case of the http challenge.

By setting the reload parameter to true, you can tell structr to reload the SSL certificate after updating it. This removes the necessity of restarting structr. (This only works if HTTPS was previously configured)

Please note that Structr needs to be run with root privileges in order to be able to serve content on the privileged port 80/443.

The built-in Let’s Encrypt client tries to start its own HTTP server listening on port 80 when the http challenge type is used. If Structr’s internal web server is also configured to port 80, this will fail and the challenge response is then served from Structr’s internal virtual file system. The resources under /.well-known/acme-challenge/ will be removed automatically afterwards.

If the type is set to dns, Structr will automatically trigger the onAcmeChallenge method with the parameters type, domain and digest. This can be used to create a DNS TXT record via an external API call to the domain’s DNS provider.

Step-by-step Guide

The use of the configuration tool is highly recommended as all settings can be changed to the desired values before (re-)starting the HTTPS service with the new configuration.

If HTTPS was NOT previously enabled
  1. Set application.https.enabled = true via the configuration tool. This enables HTTPS.
  2. Set application.https.<a data-id="c3ea50e922724cb7a14ac51658248ac4" class="mention">port</a> = 443 via the configuration tool. This sets the HTTPS port to 443 (default is 8083)
  3. Configure Let’s Encrypt Domain setting letsencrypt.domains = your-domain.com via the configuration tool. (Replace your-domain.com with your actual domain)
  4. Create/update certificate from Let’s Encrypt.
    • Either via curl (replace the admin credentials with your credentials and adjust the server+port according to your installation):
    curl -XPOST -HX-User:admin -HX-Password:admin http://localhost:8082/structr/rest/maintenance/letsencrypt -d '{"server":"production","challenge":"http","wait":"10"}'
    • Or via builtin function
    ${{
    $.maintenance('letsencrypt', {server: "production", challenge: "http", wait: "10"});
}}
  5. Restart the HTTP Service via the configuration tool tab Services and the button Restart next to the entry HttpService.default

The structr HTTP service will now reload completely with HTTPS enabled.

If HTTPS was previously enabled
  1. Configure Let’s Encrypt Domain setting letsencrypt.domains = your-domain.com via the configuration tool. (Replace your-domain.com with your actual domain)
  2. Create/update certificate from Let’s Encrypt.
    • Either via curl (replace the admin credentials with your credentials and adjust the server+port according to your installation):
    curl -XPOST -HX-User:admin -HX-Password:admin http://localhost:8082/structr/rest/maintenance/letsencrypt -d '{"server":"production","challenge":"http","wait":"10", "reload": true}'
    • Or via builtin function
    ${{
    $.maintenance('letsencrypt', {server: "production", challenge: "http", wait: "10", reload: true});
}}

The structr HTTP service will now reload the SSL certficate (without completely restarting the service itself).

Self-signed certificate for local development

For local development you can create a self-signed certificate so you can test the structr HTTPS functionality. The certificate can be created using the following command:

keytool -genkey -keyalg RSA -alias localhost -keystore domain.key.keystore -validity 3650 -keysize 2048

This command will ask for a keystore password and some information and then create a file named “domain.key.keystore”. Place this file inside the structr main directory alongside the structr.conf configuration file. Configure the keystore password in structr.conf in the key application.keystore.password and enable HTTPS by setting application.https.enabled = true. Restarting structr will result in a HTTPS-enabled instance.

NOTE: Some browsers will refuse to connect to servers using self-signed certificates citing security risk as the cause. In some browsers the user can accept the risk and still connect.