gawells/Stalwart-webui
0
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 1 Wiki Activity

docs(dev): add troubleshooting section, fix stale "one command" claim

Browse Source 
Add a Troubleshooting section to DEVELOPMENT.md covering the case that
just happened: npm run dev only reads .env.development.local at
startup, so regenerating a token or restarting the Docker container
while it's already running silently leaves the UI unable to reach the
backend until it's restarted.

README.md's "one command" claim for spinning up the test server was
stale since dev-server-init.sh became a separate one-time step.
This commit is contained in:
Steven RYDELL
2026-08-01 18:39:33 +02:00
parent adca6d8730
commit 18264a5b76
2 changed files with 20 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
DEVELOPMENT.md
+19
View File
@@ -122,6 +122,25 @@ npm run dev:server
bash ./scripts/dev-server-init.sh # re-run: fresh volume needs bootstrapping again
```
## Troubleshooting
- **UI shows a login screen instead of the admin panel, or the page fails
to load data**: `npm run dev` only reads `.env.development.local` at
startup. If you regenerate a token, or restart the Docker container,
while `npm run dev` is already running, stop it (Ctrl+C) and start it
again — it won't pick up the new token or reconnect on its own.
- **`Failed to fetch` / connection refused in the browser console**: the
test server isn't running or isn't ready yet. Check with
`docker ps --filter name=stalwart-webui-dev` and
`npm run dev:server:logs`; wait for `Network listener started ...
localPort = 8080` before retrying.
- **401s after everything was working**: your token expired. Re-run
`scripts/dev-token.sh` (or `.ps1`) and restart `npm run dev`.
- **`scripts/dev-server-init.sh` fails with connection errors**: the
container needs a few seconds after `npm run dev:server` before it
accepts requests — the script retries for ~30s, but if your machine is
slow, just re-run it.
## Notes for AI agents
- This whole workflow (steps 1–4) is scriptable end-to-end without a
README.md
+1 -1
View File
@@ -118,7 +118,7 @@ Every tagged release of this fork publishes a `webui.zip` build via CI (see [`.g
Prerequisites:
- Node.js 18 or later
- A running Stalwart instance (for JMAP API calls) — see [DEVELOPMENT.md](DEVELOPMENT.md) for how to spin up a disposable local test server with Docker in one command, no manual Stalwart setup required.
- A running Stalwart instance (for JMAP API calls) — see [DEVELOPMENT.md](DEVELOPMENT.md) for how to spin up a disposable local test server with Docker, no manual Stalwart setup required.
Install dependencies: