Local SSL certificate

Required Runtipi version: >= 1.5.0

Introduction

With Runtipi you can access your dashboard and apps locally using a secure connection. Runtipi creates a local certificate authority (CA) and a separate server certificate covering your local domain and its wildcard subdomains.

The default domain for the certificate is tipi.lan. You can change this domain in the settings page of the dashboard. Or by giving the localDomain value in your settings.json file. See the custom settings section for more information.

Trusting the certificate

Trust the root CA certificate downloaded from the dashboard by adding it to your operating system’s trust store. The root is stored as data/traefik/tls/ca.pem; do not import the server certificate (cert.pem) or share either private key. First you need to export the certificate from the Runtipi dashboard. You can do this by clicking the Download certificate button in the settings page of the dashboard. (below the Local domain input field)

Runtipi checks certificates at startup. Server certificates last at most one year and never outlive their root. Renewing a server certificate or changing the local domain preserves the root. Upgrades also preserve a valid legacy CA, so existing client trust continues to work.

A new root normally lasts ten years. If a root is invalid, its key is missing or mismatched, or it has less than one day remaining, Runtipi replaces it and logs a warning. Download and trust the replacement root on every client; trust cannot carry over from an expired or replaced root. Restart Runtipi before a server certificate expires to renew it.

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 Runtipi server.

The easiest 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 Runtipi 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.