Skip to content

Local HTTPS dev ​

bun run dev serves the stack over HTTPS on names under local.onramp.us, with each seeded org's customer portal on its own hostname, since the portal finds its org from the hostname. Public DNS answers 127.0.0.1 for local.onramp.us and every name under it.

CheckoutAppPortals (vendor 0, vendor 1)
main checkouthttps://local.onramp.us:3000portal.local.onramp.us:3000, customer.…
linked worktreehttps://<branch>.local.onramp.usportal.<branch>.local.onramp.us, customer.…

<branch> is the worktree's branch as a DNS label (feature/ONRAMP-123 becomes feature-onramp-123), or its folder name on a detached HEAD. The launcher prints the URLs once Vite is up, and dev.log keeps them (grep -m1 'App:' dev.log). bun run dev:neon and bun run dev:localhost keep the main checkout's URLs in any checkout.

Worktrees run side by side because a dev router on port 443 (devtools/dev-router/) reads the hostname each browser connection asks for and passes the still-encrypted connection to that worktree's Vite, which listens on a port from 3200 up. The router holds no certificates and answers only this machine. bun run dev starts it when it isn't running, and it exits ten minutes after the last worktree stack stops. A worktree's own database has its seeded portal domains pointed at its hostnames on each run.

The preflight (devtools/dev-ready/local-https.ts) sets the machine up on macOS and Linux the first time, then does nothing:

  1. downloads mkcert v1.4.4 into ~/.onramp/bin (pinned and checksum-verified, no Homebrew) unless one is already on PATH
  2. on Linux, installs the NSS tools Chrome and Firefox trust certificates through (apt-get, dnf or pacman)
  3. runs mkcert -install, which adds a local-only root CA to your trust store
  4. maps a hostname to 127.0.0.1 in /etc/hosts only when DNS doesn't already answer that, as behind a resolver that drops private addresses
  5. on Linux, lets your user listen on port 443 (net.ipv4.ip_unprivileged_port_start=443 in /etc/sysctl.d/60-onramp-dev.conf), but only alongside another of these steps; otherwise worktree URLs carry the router's fallback port, :3443

Steps 2–5 need root, so it asks for your password once, in the terminal (macOS may also ask you to approve the certificate). Run from an agent or anywhere without a terminal, it stops with one line instead. Each checkout's cert is issued into its own .dev-certs/ by devtools/setup-https.mjs, with no root needed, and re-issued whenever its names change.

bun run dev:localhost serves http://localhost:3000 with none of this. The org app works there, since browsers treat localhost as a secure context; the customer portals don't, because they need their hostnames.

Why it is required ​

  • Web Crypto API — crypto.randomUUID(), crypto.subtle.* (encryption, signing, hashing) only run in secure contexts. Without HTTPS the browser blocks them.
  • Service Workers + PWA features — required for offline modes, push notifications, background sync. Currently un-testable on plain HTTP.
  • Clipboard API — navigator.clipboard.writeText / readText need a secure origin. Copy-link flows fail silently in non-Chromium browsers without it.
  • Cookies that mirror prod — Secure and SameSite=None cookies don't work on plain HTTP. Auth/session bugs that only show in prod often reproduce locally once we go HTTPS.
  • Mixed-content parity — prod blocks http:// subresources from https:// pages. Catching that locally avoids late-breaking surprises.
  • OAuth / SSO redirect testing — most providers (Google, Microsoft, HubSpot, Salesforce) require HTTPS callback URLs even for dev.
  • Realistic CORS + cookie behavior — third-party iframes and CRM webhooks behave differently under HTTPS.
  • HTTP/2 — Vite's HTTPS mode enables HTTP/2 multiplexing, which trims dev-server overhead on pages with many module requests.

Troubleshooting ​

  • NET::ERR_CERT_AUTHORITY_INVALID — the browser started before the CA was trusted. Restart it.
  • Firefox on Linux, "Secure connection failed" — NSS tools were missing when the CA was installed. mkcert -install again (the preflight installs the tools first on a fresh machine).
  • "Wrong host" warning — the hostname is not in the cert. Add it to /etc/hosts on a 127.0.0.1 line and restart bun run dev; the preflight notices the changed host list and re-issues.
  • A worktree URL refuses the connection — its stack isn't running, or its branch changed since it started (the URL follows the branch on the next bun run dev).
  • Local HTTPS isn't set up on this machine yet … needs your password once — the preflight ran without a terminal to ask in. Run bun run dev once in a terminal.

Internal documentation — gated behind Cloudflare Access.