Local HTTPS without the cert dance

Browsers and some OAuth flows want HTTPS even when the server is on your Mac. Secure cookies, mixed-content rules, and callback URLs that refuse http:// turn “just local” into a quarterly ceremony of certificates, trust stores, and Stack Overflow tabs.

Rig can enable trusted local HTTPS for managed services and projects that need it — typically https://{slug}.localhost-style URLs — so you are not hand-rolling PKI every time a provider updates their OAuth policy. Use it when the stack demands it. Stay on HTTP when it does not. Complexity is optional.

When local HTTPS is actually required

You need it when:

OAuth or OIDC callbacks require https redirect URIs even for development.
The app sets Secure cookies and silently fails auth on plain HTTP.
A browser feature (geolocation, camera, certain APIs) is gated to secure contexts.
You are testing service workers, HTTPS-only APIs, or HSTS-related behaviour locally.
A reverse-proxy or SPA assumes TLS termination in front of the app.

You do not need it when:

The app is a plain static site or API you only hit with curl.
Your framework’s local recipe is happily on http://127.0.0.1:3000.
You are debugging process crash loops — TLS will not fix a dead queue.

If HTTP works, keep HTTP. Local HTTPS is a tool, not a badge.

What Rig provides

Docs describe trusted local HTTPS for projects that need it: https://{slug}.localhost-style URLs with trusted certificates, useful for secure cookies and OAuth callbacks. This path is independent of Laravel Valet’s *.test stack — Valet/Herd can keep owning PHP site URLs while Rig owns HTTPS for the Node/API side that needs it.

You should not need to become a part-time certificate authority: no quarterly “export the root, drag into Keychain, trust always, forget why it broke after a Mac migration” loop as the default path.

See Local HTTPS.

How it fits beside Valet, Herd, and Docker

Valet / Herd. They remain the PHP runtime and often the *.test HTTPS story. Rig sits beside them for Vite, queues, and APIs. Do not fight two HTTPS systems for the same hostname — pick the owner of the URL you will bookmark and share.

Docker. Containers may terminate TLS themselves or expect plain HTTP behind a proxy. Align the URL Rig opens with what the container actually speaks. Port maps lie politely; protocols lie loudly.

Live Link. Public preview URLs are a different plane (userig.app/live/...). Local HTTPS solves local browser/OAuth constraints. Live Link solves remote human review. Stop shares when calls end; do not confuse a relay URL with local cert trust.

A practical enablement workflow

Confirm you have a real requirement (OAuth callback, Secure cookies, secure context).
Enable local HTTPS for the project/service in Rig rather than inventing a one-off mkcert ritual — unless your team already standardises on that tooling and you are happy maintaining it.
Update app config: APP_URL, OAuth redirect allowlists, cookie settings, Vite HTTPS/server.origin as needed.
Restart the affected processes from the board so they pick up env and bind correctly.
Hit the HTTPS URL Rig shows; confirm the certificate is trusted in the browser you actually use for auth tests.
Keep the HTTP URL out of OAuth provider consoles so you do not toggle randomly under pressure.

Edge cases and failure modes

Mixed content. An HTTPS page loading HTTP APIs will hurt. Make the API and the SPA agree on scheme.

Wrong host in callbacks. localhost vs 127.0.0.1 vs {slug}.localhost vs *.test are different strings to an OAuth provider. Register the one you will use.

Stale browser trust. After OS migrations or aggressive Keychain cleanups, re-check trust. Prefer Rig’s managed path over undocumented manual roots when you can.

Agents rewriting URLs. Tell MCP-connected editors the canonical HTTPS origin after you enable it, or they will restart services still advertising HTTP in .env.example comments.

Performance anxiety. Local TLS is rarely your bottleneck compared to Vite cold start or Docker Desktop waking up. Do not disable HTTPS for speed folklore if OAuth requires it.

When to stay on HTTP on purpose

Teams lose hours enabling HTTPS for stacks that never needed it. Stay on HTTP when:

Only you curl the API.
No Secure-cookie auth path exists yet.
The “bug” is a crash or port conflict — fix those first (what running means).

Optional complexity that is always on becomes mandatory complexity. Keep the switch intentional.

Checklist before you blame the cert

When auth “works on staging but not locally” after enabling HTTPS:

Confirm the browser address bar host matches the OAuth allowlist character-for-character.
Confirm the process is the one Rig started (running + healthy), not an old HTTP server still bound to another port.
Confirm cookies are scoped to the host you think they are (localhost vs {slug}.localhost vs *.test).
Confirm you are not mixing Live Link’s public URL into a local OAuth config by mistake.
Only then dig into certificate trust UI — most “TLS bugs” in local OAuth are still host-string bugs.

That order keeps you from becoming a PKI operator for a typo in APP_URL.

Local HTTPS should feel like a checkbox for a real constraint — not a second career in public-key infrastructure. Enable it when the browser or the OAuth provider insists. Skip it when they do not.

https://userig.app/blog/local-https-without-the-cert-dance