Skip to content

feat(webapp): allow running the webapp without the stack - #1234

Open
acoseac wants to merge 1 commit into
desec-io:mainfrom
acoseac:docs/webapp-dev-mode
Open

feat(webapp): allow running the webapp without the stack#1234
acoseac wants to merge 1 commit into
desec-io:mainfrom
acoseac:docs/webapp-dev-mode

Conversation

@acoseac

@acoseac acoseac commented Aug 15, 2026

Copy link
Copy Markdown
Contributor

Closes #397

#397 asks for README instructions to start the webapp in dev mode without the docker stack, against a sandbox or production API. That turned out not to be documentable as-is, because it does not currently work:

  • The webapp calls the API at a relative URL (baseURL: '/api/v1/'), so npm run dev has nowhere to send /api. Vite's SPA fallback answers those calls with index.htmlGET http://localhost:8080/api/v1/ returns 200 and a page of HTML, so every API call fails on parsing rather than visibly.
  • Several views read VITE_APP_* variables that only www/Dockerfile sets, and call .split(' ') on them. Without the stack they are undefined, and e.g. /custom-setup/{domain} throws TypeError: Cannot read properties of undefined (reading 'split') on load.

So this makes it work and then documents it.

Dev server proxy

/api is forwarded to a real API, https://desec.io by default, so the webapp can be worked on with nothing else running. DESEC_API_ORIGIN points it elsewhere:

DESEC_API_ORIGIN=https://desec.example.dedyn.io npm run dev

Certificate verification is skipped for an explicitly given origin, since a local stack usually serves a self-signed certificate — without that, proxying to one fails with Error: self-signed certificate. The default public API is always verified.

Environment defaults

.env.development supplies the five VITE_APP_* variables with values matching the public service. Vite reads .env.development in development mode only, so the production build is untouched: I verified the exact env value appears in what the dev server serves and does not appear anywhere in npm run build output.

There's a judgement call here I'm happy to revisit — this commits a working default rather than shipping a .env.development.example to copy. It seemed closer to what the issue asks for (npm run dev just works), but if you'd rather not have tracked defaults, say the word.

Also

The top-level README told contributors to cd webapp/; the directory is www/webapp/. That step has been broken as written.

On the sandbox question

@andreasnuesslein asked in the issue whether a sandbox API existed to point at, and the answer at the time was "not yet". I could not find one referenced anywhere in the repo or docs, so this documents the production API, with an explicit warning that accounts and domains created there are real and that it rate-limits. Happy to switch the default if a sandbox exists now.

Verification

  • npm run dev, GET /api/v1/ through the dev server returns the real API root, byte-identical to querying https://desec.io/api/v1/ directly
  • DESEC_API_ORIGIN override checked against a stand-in HTTPS server with a self-signed certificate, before and after the secure handling
  • /custom-setup/example.com loads with no uncaught errors, checked with a listener installed at document start; the same page on main throws the split TypeError
  • npm test (4 passed) and npm run build both fine

The webapp calls the API at a relative URL, so `npm run dev` on its own
had nowhere to send `/api` and vite's SPA fallback answered those calls
with index.html. Several views additionally read VITE_APP_* variables
that only the Docker build sets, and threw at runtime without them.

Point the dev server's `/api` at a real API, defaulting to the public one
so that the webapp can be worked on without desec-stack, overridable with
DESEC_API_ORIGIN. Supply matching defaults for the VITE_APP_* variables in
.env.development, which vite reads in development mode only, leaving the
production build unchanged.

Also fix the webapp directory in the top-level README, which said
`cd webapp/` rather than `cd www/webapp/`.

Closes desec-io#397
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Update README instructions for Webapp

1 participant