SSL Configuration

HomeDock OS can issue its own certificate from Let’s Encrypt and renew it without any help from you, and it will also serve a certificate you install yourself in the /DATA/SSLCerts directory. Either way, the same certificate secures HomeDock OS and every application it serves.

HTTPS is not only about the padlock here: OnScreen Apps open on the desktop only when the browser trusts a certificate that covers their subdomains.

Cloud Instances

For Cloud Instance users, SSL certificates are issued automatically upon subscription and are seamlessly reissued whenever the hostname is changed. This automatic handling ensures a smooth, hassle-free HTTPS setup without any manual intervention.

Automatic Certificates

Recommended

HomeDock OS issues its own certificate from Let’s Encrypt and renews it on its own. You do not need certbot, a plugin, a renewal hook or a cron job, and you do not need to open a port. Everything lives in Settings → System, under HTTPS and OnScreen Apps.

You need one thing before you start: a domain you control. A free dynamic DNS name counts, and two of the three supported providers hand you one.

Choosing a provider

The certificate is proved through your DNS provider, so HomeDock OS needs to be able to write a record on your behalf. Three providers are supported, and they are not equivalent — the difference in the last column is the one that catches people out.

Provider	Domain you use	What you supply	Keeps your IP updated
FreeMyIP	A free subdomain of theirs, yourname.freemyip.com	Your update token	Yes
DuckDNS	A free subdomain of theirs, yourname.duckdns.org	Your update token	Yes
Cloudflare	A domain you already own, home.yourdomain.com	An API token with access to the zone	No

Cloudflare has no IP synchronisation. HomeDock OS can issue and renew your certificate through it, but it never touches your A record, and the automatic IP update simply does not run. If your address changes, you update the record yourself. FreeMyIP and DuckDNS keep it pointing at you without being asked.

Caution

For Cloudflare, this must be an API Token scoped to the zone, not the Global API Key. HomeDock OS finds your zone by walking up the labels of the domain you entered until one matches a zone the token can see.

The token is stored on the HomeDock OS machine and is never sent back to your browser. Changing provider asks for it again, because a token only means something to the service that issued it.

How issuance works

Let’s Encrypt has to confirm you control the domain before it signs anything. HomeDock OS uses the DNS-01 challenge: Let’s Encrypt names a value, HomeDock OS publishes it as a TXT record through your provider’s API, and Let’s Encrypt reads it back.

The practical consequence is the reason this path exists. Nothing has to be reachable from the internet. No port is opened, no inbound connection is received, and HomeDock OS does not need to be exposed at all for a certificate to be issued. HTTP-01, which does require an open port 80, is not used.

The certificate covers both your domain and its wildcard — yourdomain.com and *.yourdomain.com — because OnScreen Apps live on subdomains of that name and a certificate naming only the bare domain leaves every one of them uncovered.

_{Turn on Test run before your first real attempt. It runs against the Let's Encrypt staging server, so nothing lands on disk. Let's Encrypt allows five real certificates per week for the same name, and staging runs do not count against that, so it is the right place to get your provider and token right.}

Renewal and IP updates

Both run on their own once a certificate is in place, and neither needs anything from you.

Renewal. HomeDock OS checks the certificate every 12 hours and renews it when 30 days or fewer remain. A renewed certificate is picked up while HomeDock OS is running, with nothing to restart.

IP updates. On FreeMyIP and DuckDNS, HomeDock OS keeps your domain pointing at your current address. The first update goes out about a minute after startup, then every 15 minutes, plus a refresh every 6 hours even when nothing has changed. The first update after each start is always sent, because the record of what was already sent lives in memory and does not survive a restart.

After your first certificate

There is one thing to expect the first time you issue a certificate.

If HomeDock OS was running on plain HTTP, there is no live TLS connection to swap out. The certificate is on disk and valid, but it is not being served until you restart HomeDock OS. HomeDock OS says so plainly rather than leaving you to work it out: the status reads Certificate ready, restart HomeDock OS, and below it, HTTPS will be live on your domain once you restart. HomeDock OS is still serving the previous configuration.

Restart, and the status settles into Certificate valid, OnScreen Apps work. Every renewal after that takes effect on its own, with nothing to restart.

_{Once the certificate is trusted and covers your wildcard, Docker applications start opening as OnScreen Apps on the desktop instead of in a separate tab.}

Bringing Your Own Certificate

Legacy

(Not recommended)

Everything above is optional. If you already hold a certificate from another Certificate Authority, or your machine has no route out to Let’s Encrypt, HomeDock OS will serve a certificate you place on disk yourself.

On this path you own the renewals. Configure a renewal hook that copies each newly renewed certificate into the /DATA/SSLCerts directory, and HomeDock OS will detect and apply it automatically — the 12-hour renewal check described above only manages certificates HomeDock OS issued itself.

Required File Structure

The SSL certificate files in */SSLCerts must follow the exact naming conventions below to be recognized by the HomeDock OS python process:

• Directory*/SSLCerts

  • cert.pem
  • chain.pem
  • fullchain.pem
  • privkey.pem

Note

Make sure each file is named exactly as shown and change the port to 443 prior to restarting. Incorrect names or locations will prevent HomeDock OS from recognizing the certificates and will make it run on plain HTTP or directly not start depending the environment.

Self-Signed Certificates

If you don’t have certificates from a Certificate Authority (like Let’s Encrypt), you can generate self-signed certificates for testing or local use:

Caution

HTTPS MAY NOT WORK on port 80. After adding SSL certificates on any system (Linux, macOS or Windows), self-signed or not, you must change the port to 443 in homedock_server.conf and restart HomeDock OS. You will still need to renew them after 365 days manually and run the following commands again.

The homedock_server.conf file is located at:

• Linux: Usually /home/{username}/HomeDockOS/homedock_server.conf
• macOS: ~/Library/Application Support/cloud.homedock.app/homedock/HomeDockOS-main/homedock_server.conf
• Windows: %APPDATA%\cloud.homedock.app\homedock\HomeDockOS-main\homedock_server.conf

Reaching HomeDock OS through a domain

If you reach HomeDock OS through a domain rather than a local address — a dynamic DNS name such as example.freemyip.com — type it into the Add your own domain field in any of the sections below. It is shared across all three, so filling it in once is enough.

The certificate then covers your domain and its wildcard. That second part matters: apps are served on subdomains such as wg-easy.example.freemyip.com, so a certificate that only names the bare domain leaves every app uncovered, and OnScreen Apps will not open.

Your DNS provider also has to answer for any name under your domain. Most dynamic DNS services do, but check yours before going further:

dig +short anything.example.freemyip.com

If that prints your IP address, wildcard subdomains work. If it prints nothing, OnScreen Apps cannot work on that domain regardless of which certificate you install.

Caution

A self-signed certificate covering your domain is still not trusted by browsers, and a page inside an OnScreen App cannot ask you to accept it — the window will simply fail to load. Adding your domain is necessary but not sufficient: follow Trusting the certificate below, or use a certificate from a real Certificate Authority.

Linux

Add your own domain (optional)

Leave it empty for a local-only certificate. Fill it in if you reach HomeDock OS through a domain, so app subdomains are covered too.

Copy

sudo mkdir -p /DATA/SSLCerts && cd /DATA/SSLCerts && sudo openssl req -x509 -newkey rsa:4096 -keyout privkey.pem -out fullchain.pem -days 365 -nodes -subj "/O=HomeDock OS/OU=HDOS-/CN=homedock.local" -addext "subjectAltName=DNS:localhost,DNS:homedock.localhost,DNS:*.homedock.localhost,DNS:homedock.local,DNS:*.homedock.local,IP:127.0.0.1,IP:::1" && sudo cp fullchain.pem cert.pem && sudo cp fullchain.pem chain.pem

The certificates will and should be stored in:

• Directory/DATA/SSLCerts

  • cert.pem
  • chain.pem
  • fullchain.pem
  • privkey.pem

macOS

Add your own domain (optional)

Leave it empty for a local-only certificate. Fill it in if you reach HomeDock OS through a domain, so app subdomains are covered too.

Copy

mkdir -p ~/HomeDock/SSLCerts && cd ~/HomeDock/SSLCerts && openssl req -x509 -newkey rsa:4096 -keyout privkey.pem -out fullchain.pem -days 365 -nodes -subj "/O=HomeDock OS/OU=HDOS-/CN=homedock.local" -addext "subjectAltName=DNS:localhost,DNS:homedock.localhost,DNS:*.homedock.localhost,DNS:homedock.local,DNS:*.homedock.local,IP:127.0.0.1,IP:::1" && cp fullchain.pem cert.pem && cp fullchain.pem chain.pem

The certificates will and should be stored in:

• Directory~/HomeDock/SSLCerts

  • cert.pem
  • chain.pem
  • fullchain.pem
  • privkey.pem

Windows

PowerShell (Run as Administrator)

First, install OpenSSL if not already installed and add it to the PowerShell PATH to make it work:

winget install -e --id ShiningLight.OpenSSL.Light
$env:PATH += ";C:\Program Files\OpenSSL-Win64\bin"

Then generate the certificates:

Add your own domain (optional)

Leave it empty for a local-only certificate. Fill it in if you reach HomeDock OS through a domain, so app subdomains are covered too.

Copy

New-Item -ItemType Directory -Force -Path "C:\HomeDock\SSLCerts" | Out-Null; cd C:\HomeDock\SSLCerts; openssl req -x509 -newkey rsa:4096 -keyout privkey.pem -out fullchain.pem -days 365 -nodes -subj "/O=HomeDock OS/OU=HDOS-/CN=homedock.local" -addext "subjectAltName=DNS:localhost,DNS:homedock.localhost,DNS:*.homedock.localhost,DNS:homedock.local,DNS:*.homedock.local,IP:127.0.0.1,IP:::1"; Copy-Item fullchain.pem cert.pem; Copy-Item fullchain.pem chain.pem

The certificates will and should be stored in:

• DirectoryC:\HomeDock\SSLCerts

  • cert.pem
  • chain.pem
  • fullchain.pem
  • privkey.pem

Trusting the certificate

Accepting the browser warning only covers the address you accepted it on. Every app lives on its own subdomain, which counts as a separate address, and a page loading inside an OnScreen App is never allowed to show that warning — so it fails silently and the window stays empty.

Installing the certificate as trusted removes the warning everywhere at once, app subdomains included. Copy fullchain.pem from your HomeDock OS machine to each device you browse from, then:

• macOS: open it in Keychain Access, place it in the System keychain, then open it and set Trust → When using this certificate to Always Trust.
• Windows: open it and choose Install Certificate → Local Machine → Place all certificates in the following store → Trusted Root Certification Authorities.
• iOS / iPadOS: mail or AirDrop the file to the device and install the profile, then enable it under Settings → General → About → Certificate Trust Settings. That second step is easy to miss and nothing works without it.
• Android: install it under Settings → Security → Encryption & credentials → Install a certificate → CA certificate.

Note

Firefox keeps its own certificate store and ignores the system one. Either import the certificate under Settings → Privacy & Security → Certificates → View Certificates → Authorities, or set security.enterprise_roots.enabled to true in about:config.

_{Until the certificate is trusted, self-signed certificates show a browser warning on every address, and OnScreen Apps fail to load rather than showing it. A self-signed certificate also expires after 365 days, and you renew it by running these commands again and re-trusting the result on every device. If your machine can reach the internet, Automatic Certificates avoids all of that: HomeDock OS issues a browser-trusted certificate from Let's Encrypt and renews it for you.}