Skip to Content
DocumentationGuidesLocal SSL certificate

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.

Current builds don’t generate a local certificate for you. The Download certificate button in the dashboard settings (GET /api/system/certificate) reads <ROOT_FOLDER_HOST>/traefik/tls/cert.pem, which is a legacy path — Traefik’s directory now lives under <ROOT_FOLDER_HOST>/state/traefik/tls/ (mounted at /etc/traefik/tls inside the traefik container) — so the download comes back empty. Generate or supply your own certificate, place the certificate and key under <ROOT_FOLDER_HOST>/state/traefik/tls/ with a matching dynamic TLS config file in <ROOT_FOLDER_HOST>/state/traefik/dynamic/, and import your certificate into your OS trust store using the steps below.

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 <ROOT_FOLDER_HOST>/state/settings.json. 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.

Trusting the certificate

To use your certificate without browser warnings, add it to your operating system’s trust store. Use the certificate file (.crt or .pem) that you generated or supplied. The Download certificate button on the Settings tab (below Local domain) 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, type certmgr.msc, and press Enter.
  2. In the left pane, select Trusted Root Certification Authorities.
  3. In the right pane, select Certificates.
  4. Open Action → All Tasks → Import.
  5. Follow the instructions in the Certificate Import Wizard to import the certificate.

macOS

  1. Open Keychain Access.
  2. Select File → Import Items.
  3. Select the certificate file and select Open.
  4. Double-click the imported certificate.
  5. Expand the Trust section.
  6. Set When using this certificate to Always Trust.

Linux

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

DNS resolution

To open your dashboard and apps using the local domain, the domain must resolve to the LAN IP address of your Companion Hub machine.

The most reliable approach is running a local DNS server on your network and adding a wildcard rewrite for the domain. You can install Pi-hole (pi-hole) or AdGuard Home (adguard-home) from the Companion App Store.

Resolution methodDNS server on your networkhosts file on each device
Covers every device on the LAN at once✓–
One wildcard entry (*.ci.lan) covers all apps✓One line per domain
Needs extra softwarePi-hole or AdGuard Home from the App Store–
Two ways to make ci.lan resolve to your Hub.

For example, in AdGuard Home, add your domain under Filters → DNS rewrites:

Add both the base domain (ci.lan) and the wildcard domain (*.ci.lan) under DNS rewrites so your installed apps resolve alongside the dashboard.


Screenshot of AdGuard Home showing the DNS rewrites section

If you do not run a DNS server on your network, add the domain to the hosts file on each client device.

⚠️

With a hosts file, you must add an entry on every device that accesses your Hub and list every hostname explicitly (for example, ci.lan, app1.ci.lan, and app2.ci.lan), because hosts files do not support wildcards.

Windows

  1. Open the Start menu, type Notepad, right-click it, and select Run as administrator.
  2. Select File → Open and navigate to C:\Windows\System32\drivers\etc.
  3. Change the file filter to All Files (*.*), select hosts, and select Open.
  4. Append <ip-address> <domain> to the end of the file (for example, 192.168.1.20 ci.lan).
  5. Save the file.

macOS / Linux

  1. Open Terminal.
  2. Run sudo nano /etc/hosts.
  3. Append <ip-address> <domain> to the end of the file (for example, 192.168.1.20 ci.lan).
  4. Press Ctrl+X, then Y, and press Enter to save.
Last updated on