---
title: "Local HTTPS and certificate testing"
---

> Documentation Index
> Fetch the complete documentation index at: https://ermahgerd-docs.t-bd7662a5eeb4.workers.ermahgerd.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Local HTTPS and certificate testing

This guide applies only to the disposable Lima profiles. For public DNS and
trusted certificates, use [Public hosting](/self-hosted/public-hosting/) and
[Certificates and domains](/operations/certificates/).

## Use persistent local HTTPS

`make up` enables this profile after provisioning the compact appliance. To
enable it again after an explicit `make https-down`, run:

```sh
make https-up
```

The target obtains tenant wildcard certificates from the private Pebble CA,
enables the persistent service profile, and adds that exact CA root to the
current macOS user's login keychain. macOS resolves nested
`*.ermahgerd.localhost` names to loopback without a custom DNS service. The
control VM forwards its private port 443 to host port 8443, so applications are
available at URLs such as:

```text
https://sum.t-bd7662a5eeb4.workers.ermahgerd.localhost:8443
https://photo-gallery.t-bd7662a5eeb4.workers.ermahgerd.localhost:8443
```

The keychain may request interactive authorization. Restart an already-open
browser if it cached the previous trust result. The target records the CA's
exact fingerprint and refuses to claim an identical certificate it did not
install. It never disables browser certificate verification.

Inspect the profile at any time with:

```sh
make https-status
```

Keep the HTTPS profile active for ordinary local development. Use
`make https-down` only to return to the HTTP profile, before `make destroy`, or
before the isolated `make https-check` rehearsal. It removes only the recorded
CA certificate, restores the normal HTTP service configuration, and disables
the local certificate timers without deleting their state. Stopping and
starting the existing appliance does not require another trust decision because
both its CA and persistent service overrides remain on the control node.

The port forward is part of the current Lima template. A control VM created by
an older checkout must be recreated before `make https-up`; the target detects
that condition before changing services or trust. Running the ordinary
`make site` profile disables certificate automation by design, so rerun
`make https-up` afterward when persistent HTTPS is desired.

The tenant and administrator portals remain on their existing development
listeners. Persistent HTTPS currently covers customer Worker ingress and the
Access redirects protecting those Workers; portal TLS is a separate public
hosting gate.

## Run the local HTTPS check

Start with a healthy appliance and the Local Development examples, including
EmDash and a populated photo gallery. On an existing installation, converge
the platform code before running the check:

```sh
make status
make site
make https-check
```

`make https-check` installs private test services and the same certificate
manager used by a hosted installation on the active control node. The manager uses Certbot
to obtain certificates, briefly switches the existing Worker ingress and Access
gateway to HTTPS test origins, exercises them, then restores the normal origins.
Run it during a development maintenance window: the profile switch restarts
the control API and Access, and normal Worker URLs are unavailable during the
test. Do not run provisioning, deployments, or another live integration check
concurrently. No Worker code is redeployed and no VM is recreated.

The transient check refuses to start while persistent local HTTPS is active.
Run `make https-down` first so the certificate inventories and service profiles
cannot interfere with one another.

The test uses `*.t-bd7662a5eeb4.workers.ermahgerd.test` and
`access.ermahgerd.test`. These names resolve only inside the control VM.
Chromium runs there under a dedicated account with its own certificate trust
store. The test does not disable certificate validation, modify the Mac
keychain, or make its CA a fleet-wide trust authority. Only the reserved
`ermahgerd.test` and `customer.test` zones use the test resolver; other DNS
continues through the existing network.

The preparation step can also be run separately with `make https-prepare`.
It does not switch application origins. Test services and their state persist
on the disposable control VM, but are not included in normal provisioning.

The rehearsal differs from a hosted installation only at the ACME and DNS
boundary: Pebble replaces the public CA, and a tightly scoped manual hook writes
TXT challenges into Pebble's private challenge server. The certificate manager,
organization discovery, Certbot renewal state, deploy hook, atomic HAProxy
publication, validation, reload, and recovery paths are the production-shaped
components.

## Understand the evidence

Results and browser screenshots are collected under `.cache/https-rehearsal/`:

* `report.json`: DNS-01 validation, hostname rejection, HTTP redirects,
  application responses, browser checks, recovery, and overall result.
* `renewal.json`: 300 fresh-connection requests at 10 RPS during certificate
  replacement, including failures, latency percentiles, and certificate serials.
* `browser.json` and PNGs: EmDash public/admin pages, gallery images, and the
  protected Photo Studio after an Access login.

The check requires a wrong DNS challenge to be rejected by the CA, unknown
certificate names to fail TLS, and mismatched TLS SNI/HTTP Host values to
receive 421. It checks traffic after HAProxy reload and control-plane restart,
and while the CA is unavailable. The renewal measurement is a short local
regression check, not an Internet latency promise or an availability SLO.

The EmDash browser check verifies that its admin interface hydrates and browser
WebAuthn APIs are available. It does not enroll a user or reuse your personal
passkey. Plan application authentication explicitly when changing its hostname:
an existing credential is not automatically valid for an unrelated domain.

Ordinary failures restore the original profile automatically. After a killed
process or interrupted run, restore it explicitly and verify the demo:

```sh
make https-restore
make examples-test
make status
```

The temporary service overrides live under `/run`; recovery removes only the
rehearsal's own overrides and reconciles ingress from normal configuration.
Do not delete certificate files while HAProxy is configured to use them.

Source: https://ermahgerd-docs.t-bd7662a5eeb4.workers.ermahgerd.io/self-hosted/local-https/index.mdx