Merge pull request #569 from jeroenubbink/docs/admin-ui-serving

docs(ui): document dev/build/serve workflow; make missing-bundle warning actionable

routstr/core/main.py

@@ -369,7 +369,10 @@ if UI_DIST_PATH.exists() and UI_DIST_PATH.is_dir():
 
 else:
     logger.warning(
-        f"UI dist directory not found at {UI_DIST_PATH}, skipping static file serving"
+        "UI dist directory not found at %s; serving API only. Run `make ui-build` "
+        "to build the static UI served from here, or `make ui-dev` for the Next.js "
+        "dev server with hot reload on :3000 (it targets this backend on :8000).",
+        UI_DIST_PATH,
     )
 
     @app.get("/", include_in_schema=False)

ui/README.md

@@ -1,36 +1,44 @@
-This is a [Next.js](https://nextjs.org) project bootstrapped with [`create-next-app`](https://nextjs.org/docs/app/api-reference/cli/create-next-app).
+# Routstr node admin UI
 
-## Getting Started
+A [Next.js](https://nextjs.org) app (App Router, **static export**) that provides the
+admin dashboard for a `routstr-core` node: login, settings, providers, balances,
+transactions, usage, and logs.
 
-First, run the development server:
+There is no separate web server in production. `next build` produces a fully static
+export (`next.config.ts` sets `output: 'export'`), and the FastAPI backend serves it
+directly from `../ui_out/` (see `routstr/core/main.py`). So the UI and the API are
+served from the **same origin** in production.
 
-```bash
-npm run dev
-# or
-yarn dev
-# or
-pnpm dev
-# or
-bun dev
-```
+## Developing the UI (hot reload)
 
-Open [http://localhost:3000](http://localhost:3000) with your browser to see the result.
+The everyday loop runs two processes side by side — you do **not** rebuild the static
+export while developing:
 
-You can start editing the page by modifying `app/page.tsx`. The page auto-updates as you edit the file.
+1. Start the backend on `:8000` — from the repo root: `make docker-up` (or
+   `uvicorn routstr.core.main:app --reload`).
+2. Start the Next.js dev server on `:3000` — from the repo root: `make ui-dev`
+   (or `cd ui && pnpm dev`). Edits hot-reload instantly.
 
-This project uses [`next/font`](https://nextjs.org/docs/app/building-your-application/optimizing/fonts) to automatically optimize and load [Geist](https://vercel.com/font), a new font family for Vercel.
+Open http://localhost:3000. With no `NEXT_PUBLIC_API_URL` set, the UI falls back to
+`http://127.0.0.1:8000` in development (see `lib/api/services/configuration.ts`), so it
+talks to the local backend out of the box.
 
-## Learn More
+Because dev is cross-origin (`:3000` → `:8000`), it relies on the backend's CORS
+allowing the UI origin. The default `cors_origins` is `["*"]`; if you tighten CORS,
+keep `http://localhost:3000` allowed for development.
 
-To learn more about Next.js, take a look at the following resources:
+## Building the integrated/static UI (what production serves)
 
-- [Next.js Documentation](https://nextjs.org/docs) - learn about Next.js features and API.
-- [Learn Next.js](https://nextjs.org/learn) - an interactive Next.js tutorial.
+To produce the bundle that FastAPI serves from `../ui_out/`:
 
-You can check out [the Next.js GitHub repository](https://github.com/vercel/next.js) - your feedback and contributions are welcome!
+- `make ui-build` — builds with local Node/pnpm (`scripts/build-ui.sh`), then moves
+  `ui/out/*` to `../ui_out/`.
+- `make ui-build-docker` — same, but inside Docker (no local Node needed).
 
-## Deploy on Vercel
+`NEXT_PUBLIC_*` variables are read from the repo-root `.env` at build time and baked in.
+For a same-origin deployment leave `NEXT_PUBLIC_API_URL` empty (relative paths); the UI
+uses `window.location.origin` at runtime. After building, start the backend and open
+http://localhost:8000 — the dashboard is served at `/` and `/admin`.
 
-The easiest way to deploy your Next.js app is to use the [Vercel Platform](https://vercel.com/new?utm_medium=default-template&filter=next.js&utm_source=create-next-app&utm_campaign=create-next-app-readme) from the creators of Next.js.
-
-Check out our [Next.js deployment documentation](https://nextjs.org/docs/app/building-your-application/deploying) for more details.
+If `../ui_out/` does not exist, the backend logs a warning at startup and serves the API
+only (hitting a UI route returns a small JSON fallback instead of the dashboard).