Skip to content

SSL HTTPS Access

Jump to bottom
esp32x edited this page Nov 25, 2021 · 26 revisions

Secure HTTPS access for the Homebridge UI is enabled by default. The certificate is self-signed so you will see a browser warning unless you replace the certificates with one from a trusted CA. You can connect to the Homebridge UI via https:// on port 443 using:

  • https://<your ip or homebridge.local>

Default SSL Config

The self-signed SSL/TLS certificate and private key are generated on your device the first time you boot the Homebridge Raspberry Pi Image.

SSL is handled by Nginx. The config and SSL certificate paths are below:

Path
Homebridge Nginx Config /etc/nginx/sites-enabled/homebridge.local
Homebridge Nginx SSL Key /etc/nginx/ssl/homebridge.local.key
Homebridge Nginx SSL Cert /etc/nginx/ssl/homebridge.local.crt

Redirect HTTP to HTTPS

If you have already enabled Pi-Hole you should not attempt to redirect http to https using this method.

To setup a redirect from http:// to https:// run sudo hb-config command and select Nginx Options:

hb-config-nginx-options

Ensure all three options are checked, then click Save:

hb-config-nginx-options-redirect

Nginx will now reload and all requests to http:// will be redirected to https://.

hb-config-nginx-configured-success

Custom SSL Cerfificate

If you wish to install your own SSL certificate, the easiest way to do this is to replace the default key and certificate files with your own, then reload nginx:

sudo nginx -s reload

Let's Encrypt / Certbot

The Homebridge team does not provide user support for setting up Certbot. See the Certbot website for further information: https://certbot.eff.org.

If you have Pi-Hole running on port 80 you will not be able to follow these instructions to install a valid certificate using Certbot.

Before you start make sure you have done the following:

  • Use your router to port forward requests from:
    • 80 -> <Raspberry Pi IP>:80
    • 443 -> <Raspberry Pi IP>:443
  • Setup your domain name DNS to point to your public IP address

Install Certbot:

sudo apt-get install certbot python-certbot-nginx

Run Certbot and follow the wizard:

sudo certbot certonly --nginx

Once completed you should see a message like this:

IMPORTANT NOTES:
 - Congratulations! Your certificate and chain have been saved at:
   /etc/letsencrypt/live/YOUR_DOMAIN_HERE/fullchain.pem
   Your key file has been saved at:
   /etc/letsencrypt/live/YOUR_DOMAIN_HERE/privkey.pem

Create a symlink to where Nginx expects to find the SSL certificate for the Homebridge UI:

Replace YOUR_DOMAIN_HERE with the domain name you entered in the previous step.

ln -sf /etc/letsencrypt/live/YOUR_DOMAIN_HERE/fullchain.pem /etc/nginx/ssl/homebridge.local.crt
ln -sf /etc/letsencrypt/live/YOUR_DOMAIN_HERE/privkey.pem /etc/nginx/ssl/homebridge.local.key

Reload Nginx using the following command:

nginx -s reload

If everything worked you should see no warnings from the reload command. You should now be able to access the Homebridge UI by connecting to https://YOUR_DOMAIN_HERE.

The Certbot packages on your system come with a cron job or systemd timer that will renew your certificates automatically before they expire. You will not need to run Certbot again, unless you change your configuration. You can test automatic renewal for your certificates by running this command:

sudo certbot renew --dry-run

You can now setup a redirect from HTTP to HTTPS.

Clone this wiki locally