1f15330961
Most contributors don't need HTTPS=1 locally — plain HTTP is the
default and the right choice for everything except Wahoo OAuth
callback testing. WebAuthn (passkeys), magic links, sessions, the
Terms gate, SSE all work over HTTP because the WebAuthn spec treats
localhost as a secure context regardless of scheme. CI proves the
point: the e2e suite runs over plain HTTP and passes cleanly.
The original HTTPS=1 plumbing landed in 20b91ef (2026-04-05) bundled
into a Wahoo import fix, with no inline rationale. Once you've
forgotten the reason it tends to leak into the default workflow,
which then breaks the local e2e suite (Playwright always uses HTTP
baseURL; an https ORIGIN env mismatches what it sends) and creates
unnecessary divergence from CI.
Documenting the single legitimate use case so the next contributor
(or future-me) doesn't have to re-derive it from git blame:
- apps/journal/vite.config.ts — expanded the comment near the
basic-ssl plugin to spell out:
* What works on HTTP (everything except Wahoo)
* What needs HTTPS=1 (Wahoo OAuth specifically)
* The norm: don't add new HTTPS-only paths without writing them
down here too, so the assumption stays auditable
- apps/journal/.env.example — new tracked file showing the env vars
the journal app reads, with `ORIGIN=https://localhost:3000`
marked as HTTPS-only and accompanied by an explanation of the
ORIGIN/Playwright mismatch trap. Future contributors don't have
to discover this through a failing e2e run.
- CLAUDE.md — new "Local HTTPS dev (rare)" subsection under
Development Commands. Includes the exact command for Wahoo testing
(`HTTPS=1 ORIGIN=https://localhost:3000 pnpm --filter
@trails-cool/journal dev`), the turbo-doesn't-pass-HTTPS gotcha,
and the rule of thumb: don't set ORIGIN in your .env unless you
also always run with HTTPS=1.
No code/behavior changes; documentation only.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
55 lines
3 KiB
Text
55 lines
3 KiB
Text
# Journal local-dev environment.
|
|
# Copy to `.env` (gitignored) and edit. Most contributors don't need
|
|
# anything in this file — the journal app boots on plain HTTP at
|
|
# http://localhost:3000 with sensible defaults.
|
|
|
|
# ────────────────────────────────────────────────────────────────────
|
|
# DO NOT SET unless you know you need it
|
|
# ────────────────────────────────────────────────────────────────────
|
|
#
|
|
# `ORIGIN` is what the WebAuthn ceremony uses as `expectedOrigin`.
|
|
# When unset it defaults to `http://localhost:3000`, which is what
|
|
# Playwright sends and what the browser sees in plain-HTTP dev.
|
|
#
|
|
# The ONLY reason to set this is if you're running the dev server
|
|
# over HTTPS (see HTTPS=1 below) and want passkey registration to
|
|
# succeed against the HTTPS origin. If you set it to `https://...`
|
|
# without also running the server over HTTPS, you'll get
|
|
# "Unexpected registration response origin" errors in dev and the
|
|
# local e2e suite (which always hits HTTP) will fail registration.
|
|
#
|
|
# ORIGIN=https://localhost:3000
|
|
|
|
# Flagship marker. Renders the project marketing block on the
|
|
# anonymous home and gates a few "this is the canonical instance"
|
|
# behaviors. Self-hosted instances leave this unset; flagship CI
|
|
# sets it to `true`. Either is fine for local dev — set it if you
|
|
# want to see the full marketing layout, leave it unset if you
|
|
# want the self-host home view.
|
|
# IS_FLAGSHIP=true
|
|
|
|
# ────────────────────────────────────────────────────────────────────
|
|
# Wahoo OAuth (only needed when actively testing the Wahoo import)
|
|
# ────────────────────────────────────────────────────────────────────
|
|
#
|
|
# Wahoo's OAuth flow is the one feature that genuinely needs HTTPS
|
|
# locally: the provider rejects `http://` redirect URIs. To exercise
|
|
# the connect/disconnect/import flow end-to-end, you need:
|
|
#
|
|
# 1. Local HTTPS dev server: run `HTTPS=1 pnpm --filter
|
|
# @trails-cool/journal dev` (the basic-ssl plugin in
|
|
# vite.config.ts wires up the cert; see the comment there for
|
|
# the ALPN workaround).
|
|
# 2. ORIGIN=https://localhost:3000 (uncomment above).
|
|
# 3. Wahoo client credentials below, and a redirect URI of
|
|
# `https://localhost:3000/api/sync/callback/wahoo` registered
|
|
# in your Wahoo developer dashboard.
|
|
#
|
|
# WAHOO_CLIENT_ID=
|
|
# WAHOO_CLIENT_SECRET=
|
|
# WAHOO_WEBHOOK_TOKEN=
|
|
|
|
# Integration test secret (only needed if running the integration
|
|
# test suite that drives the API directly). Generate with
|
|
# `openssl rand -hex 32`.
|
|
# INTEGRATION_SECRET=
|