Local SSL certificate

Introduction

Most people don’t need this guide. Apps open at your Hub’s address and the app’s port (for example http://192.168.1.20:8080), and localhost addresses need no certificate. This guide is for the advanced case where you give your apps in Public Web mode an internal name on your local network, such as app.ci.lan. Your browser shows a certificate warning for that name until it trusts the certificate that Traefik presents. The guide covers the two halves of that setup: trusting a certificate on your devices, and making the name resolve to your Hub.

The name you set as your local domain is the domain part of these names. Set one explicitly — the default (localhost) does not need a certificate, since browsers already treat it as a secure context. Hub builds an internal hostname from your local domain for each app that uses the Public Web exposure mode. It doesn’t create a local-domain name for apps in other modes; reach those at the Hub’s address and the app’s port.

Set your local domain in the dashboard settings page (the field is read-only until you turn on Advanced settings there), or as localDomain in your settings.json file. See Custom Settings and Finding Your App’s URL.

This guide uses ci.lan as the example local domain — substitute whatever you configured.

Two things have to be true before https://ci.lan works: your device trusts the Hub’s certificate, and the name resolves to the Hub. The rest of this guide covers each half.

flowchart LR
    subgraph T["Trust the certificate"]
        G["You generate or supply a<br/>certificate for ci.lan"] --> DL["Export the certificate<br/>file"]
        DL --> TS["Import into the OS trust store"]
    end
    subgraph N["Resolve the name"]
        DNS["Pi-hole or AdGuard Home<br/>rewrites ci.lan and *.ci.lan"] --> IP["Hub's LAN IP"]
        H["hosts file entry<br/>on each device"] --> IP
    end
    TS --> OK["https://ci.lan and https://app.ci.lan<br/>open over a trusted connection"]
    IP --> OK

Trusting the certificate

To be able to use the certificate, you need to trust it. This is done by adding the certificate to your operating system’s trust store. First you need the certificate file. Use the certificate you generated or supplied. The Download certificate button in the dashboard settings (below the Local domain input field) is meant to export the Hub’s own certificate, but see the warning at the top of this page.

Windows

1. Open the Start menu and type certmgr.msc and press Enter.
2. In the left pane, click Trusted Root Certification Authorities.
3. In the right pane, click Certificates.
4. On the Action menu, point to All Tasks, and then click Import.
5. Follow the instructions in the Certificate Import Wizard to import the certificate.

macOS

1. Open the Keychain Access app.
2. Click File > Import Items.
3. Select the certificate file and click Open.
4. Double-click the certificate file.
5. Expand the Trust section.
6. Change the When using this certificate option to Always Trust.

Linux

1. Copy the certificate file to /usr/local/share/ca-certificates/.
2. Run sudo update-ca-certificates.

DNS resolution

To be able to access your dashboard and apps using the local domain, you need to make sure that the domain resolves to the IP address of your Companion Hub server.

The most reliable way to do this is by running a DNS server on your network and adding the domain to it. You can use Pi-hole or AdGuard Home for this. Both are available as apps in the Companion Hub App store.

For example using AdGuard Home you can add the domain to the DNS rewrites section of the app.

If you don’t have a DNS server running on your network, you can add the domain to the hosts file on your computer.

Windows

1. Open the Start menu and type Notepad and press Enter.
2. Click File > Open.
3. Navigate to C:\Windows\System32\drivers\etc.
4. Change the file filter to All Files (*.*).
5. Select hosts and click Open.
6. Add the following line to the end of the file: <ip-address> <domain>.
7. Save the file.

macOS / Linux

1. Open the Terminal app.
2. Run sudo nano /etc/hosts.
3. Add the following line to the end of the file: <ip-address> <domain>.
4. Press Ctrl + X to exit.
5. Press Y to save the file.
6. Press Enter to confirm the file name.