Internal TLS with a private CA¶

LAN-only names like <SERVICE>.<YOUR_LOCAL_DOMAIN> can't get a Let's Encrypt certificate: a private suffix like home.arpa isn't a public domain, so no public CA will validate it. Instead of clicking through browser warnings, I run a small private root CA made with mkcert, issue one wildcard certificate from it, and load that into NPM. Every device that trusts the root CA then gets a clean padlock on every LAN name.

browser ─► AdGuard Home: *.<YOUR_LOCAL_DOMAIN> → NPM's LAN IP
        ─► NPM :443 (wildcard cert signed by your root CA)
        ─► service (plain HTTP on the LAN / Docker network)

The public names (<SERVICE>.<YOUR_DOMAIN>) keep their Let's Encrypt wildcard; see Tunnel + NPM. Both live in the same NPM instance.

1. Create the root CA¶

Do this on a trusted machine (your workstation), not on a server. On Debian 13:

sudo apt install mkcert libnss3-tools   # libnss3-tools lets mkcert add the CA to Firefox/Chromium
mkcert -install                          # creates the CA and trusts it on this machine
mkcert -CAROOT                           # prints where rootCA.pem and rootCA-key.pem live

rootCA.pem is the public certificate you hand to clients. rootCA-key.pem can sign a certificate for any name and every device that trusts the CA will believe it.

2. Issue the wildcard certificate¶

mkcert "*.<YOUR_LOCAL_DOMAIN>"
# → _wildcard.<YOUR_LOCAL_DOMAIN>.pem       (certificate)
# → _wildcard.<YOUR_LOCAL_DOMAIN>-key.pem   (private key)

mkcert certificates are valid for 2 years and 3 months; the root CA for 10 years. Put the leaf expiry date in your calendar now (step 6).

3. Load it into NPM¶

1. SSL Certificates → Add SSL Certificate → Custom Certificate
2. Name it (e.g. local wildcard), upload the -key.pem as Certificate Key and the .pem as Certificate. You can leave Intermediate Certificate empty (mkcert signs leaves straight from the root).

3. For each service, add a proxy host:

   Field	Value
   Domain Names	<SERVICE>.<YOUR_LOCAL_DOMAIN>
   Scheme / Forward Hostname / Port	as for any proxy host
   SSL Certificate	local wildcard
   Force SSL	✅ enabled
   HTTP/2 Support	✅ enabled

After saving, check that the host really answers on 443 with the new cert:

curl -sI https://<SERVICE>.<YOUR_LOCAL_DOMAIN> | head -1
openssl s_client -connect <YOUR_SERVER_IP>:443 -servername <SERVICE>.<YOUR_LOCAL_DOMAIN> </dev/null 2>/dev/null \
  | openssl x509 -noout -issuer -enddate

4. Point the names at NPM¶

One wildcard rewrite in AdGuard Home covers every service: AdGuard Home → DNS rewrites. New service = new NPM proxy host, nothing else.

5. Trust the CA on clients¶

6. Trust the CA inside containers¶

Browsers aren't the only clients. When one container calls another over https://<SERVICE>.<YOUR_LOCAL_DOMAIN> (a git server's webhook to a deploy tool, a monitoring agent to its hub), it fails with x509: certificate signed by unknown authority unless that container trusts your CA too. Each runtime has its own knob:

services:
  some-go-app:
    environment:
      - SSL_CERT_FILE=/etc/ssl/certs/ca-bundle.crt
    volumes:
      # system CA bundle with rootCA.pem appended: cat /etc/ssl/certs/ca-certificates.crt rootCA.pem > ca-bundle.crt
      - ./ca-bundle.crt:/etc/ssl/certs/ca-bundle.crt:ro

  some-debian-app:
    volumes:
      - ./certs/homelab-rootCA.crt:/usr/local/share/ca-certificates/homelab-rootCA.crt:ro

Only the public rootCA.pem goes into containers, never the key.

7. Renewal and expiry¶

• Monitor expiry. Uptime Kuma's HTTPS monitors can alert on certificate expiry; turn that on for at least one local name and one public name.
• Renew the leaf before it expires: run mkcert "*.<YOUR_LOCAL_DOMAIN>" again on the workstation and replace the files in the existing NPM custom certificate, so every proxy host picks it up.
• If you replace the CA or create a new cert entry, re-assign it on every proxy host. Hosts left on an old or deleted certificate keep serving it (or silently fall back to plain HTTP). After any certificate change, run the openssl check above against every local name.
• When the root CA approaches its 10 years, plan a rollover: new CA on all clients first, then the new leaf.

Sources & further reading¶

• mkcert
• Debian mkcert package
• Debian: update-ca-certificates(8)
• Nginx Proxy Manager docs
• Go crypto/x509: SSL_CERT_FILE
• Node.js NODE_EXTRA_CA_CERTS
• RFC 8375: home.arpa