TLS and Certificates

TLS and Certificates#

LocalDevStack uses mkcert-based local TLS for development.

At first run, it creates a local Root CA and issues development certificates. After that, it scans your vhost configs and (re)generates certificates for all detected domains.

Certificates are generated and persisted under the host-mounted configuration/ tree so they survive rebuilds.

Generated files (host)#

LocalDevStack persists TLS artifacts in this layout:

configuration/
├── rootCA
│   ├── rootCA-key.pem
│   └── rootCA.pem
└── ssl
    ├── apache-client-key.pem
    ├── apache-client.pem
    ├── apache-server-key.pem
    ├── apache-server.pem
    ├── local-key.pem
    ├── local.pem
    ├── nginx-client-key.pem
    ├── nginx-client.p12
    ├── nginx-client.pem
    ├── nginx-proxy-key.pem
    ├── nginx-proxy.pem
    ├── nginx-server-key.pem
    └── nginx-server.pem

Notes:

  • configuration/rootCA/rootCA.pem is your local development CA certificate.

  • The *-server*.pem pairs are used by Nginx/Apache for HTTPS.

  • The *-client*.pem pairs are used when mutual TLS is enabled for a domain.

  • nginx-client.p12 is provided for convenient browser import when mutual TLS is enabled.

Domain discovery#

Certificate generation scans all *.conf files under the shared vhost directory (mounted from your host). From those filenames/configs, LocalDevStack derives domain names and generates SAN certificates covering all detected domains.

This keeps certs aligned with your active vhost set: add/remove a domain, regenerate, done.

Trusting the Root CA#

To trust your local CA on your host system, run:

sudo lds certificate install

This installs configuration/rootCA/rootCA.pem into your OS trust store (where supported).

Manual install is also possible:

  • Import configuration/rootCA/rootCA.pem into your OS trust store using your system UI/tools.

  • This is useful in locked-down environments where automated install is restricted.

Mutual TLS (Client certificates)#

If you enable mutual TLS for any domain:

  • You must install the client certificate in your browser.

  • Recommended: import configuration/ssl/nginx-client.p12 into the browser certificate store.

After importing, the browser will present the client certificate when accessing mTLS-protected domains.

Uninstalling the Root CA#

If you previously trusted the LocalDevStack Root CA and want to remove it from your system trust store, use:

sudo lds certificate uninstall

This removes the installed CA file from the detected OS trust anchor location and then refreshes the system trust store (best-effort).

Remove from all known locations (cleanup mode)#

If you changed distros, moved CA paths, or installed it manually in different locations, use:

sudo lds certificate uninstall --all

This additionally scans common CA anchor locations and removes any leftover rootCA entries it finds, then refreshes the trust store.

Notes#

  • Uninstall requires sudo/admin privileges.

  • Trust store refresh is best-effort; on uncommon distributions you may need to refresh trust manually after removal.

  • This only removes the installed OS trust anchor. It does not delete your generated CA files under configuration/rootCA (those are part of your project persistence).

Troubleshooting#

Browser still shows “Not Secure”#

  • Confirm the Root CA is trusted:

    • Run lds certificate install again, or

    • Manually install configuration/rootCA/rootCA.pem into your OS trust store.

  • Restart the browser after installing the CA (some browsers cache trust decisions).

Certificate mismatch after changing domains#

  • If you renamed/removed domains, regenerate certs so SANs match the current vhost set.

  • Ensure the vhost files under configuration/nginx / configuration/apache reflect the current domains.

Mutual TLS enabled but browser doesn’t prompt / request fails#

  • Import the client cert (recommended): configuration/ssl/nginx-client.p12.

  • Verify the client cert is imported into the correct browser profile.

  • If you have multiple client certs, remove old ones and retry to avoid wrong-certificate selection.