Configuring HTTPS

Owned by Karen Hogan (Unlicensed)
Last updated: Dec 20, 2021 by Adam Voakes
2 min read

Prep work

There are two or three things you need to provide:

  1. a certificate (pem)

  2. a key (pem/key usually)

  3. and sometimes a password depending on the options used to create the certificate

Customers should have a way to obtain these already but if not, certbot from lets encrypt can be used to get a free certificate for a domain owned by a customer.

Once these are ready you can provide these to the Dashboard.

Using the command-line interface

Configuring via JSON

The easiest way on the CLI is to update the file dashboard.json (or copying the file defaults.json to dashboard.json) and updating the https fields in there.

"https": { "enabled": false, "certificate": "/path/to/certificate", "certificateKey": "/path/to/key", "keyPassword": "" }

Once that’s ready, run:

./configuration-tool --configure --configure-type=json

Configuring via Environment Variables

Alternatively, you can use environment variables to do this:

PI_TOMCAT_USE_HTTPS

Makes tomcat use HTTPS

 

PI_TOMCAT_HTTPS_CERT

The location of the X509 certificate to use for https

April 2021

PI_TOMCAT_HTTPS_CERT_KEY

The location of the X509 certificate key file

April 2021

PI_TOMCAT_HTTPS_CERT_KEY_PASSWORD

The password of the certificate key (if set)

April 2021

./configuration-tool --configure --configure-type=env

IMPORTANT - See Environment Variables for more information. If using a Proxy these will need setting too

Using the graphical interface

  1. First copy the certificate and the key to the Dashboard/tomcat folder in your file system

  2. Start the configuration-tool-GUI you can also find it on the Dashboard folder in your file system, it may be required of you to give permissions for the application to make changes in your device

  3. Navigate into the Tomcat tab

  4. Enable Serve Dashboard over HTTPS

  5. Provide the paths to the Certificate and Key in your Dashboard/tomcat folder in your file system

  6. Insert your certificate password depending on the options used to create the certificate

  7. Click Apply and Run to apply the changes and restart the dashboard

  8. Now your dashboard will be served in HTTPS after it restarts