From 2322e198bfe42910ce3f81ffd9df0558d4dcf958 Mon Sep 17 00:00:00 2001 From: "Sana (OpenClaw)" Date: Sun, 8 Feb 2026 15:31:34 +0000 Subject: [PATCH 1/3] docs: document NEXT_PUBLIC_API_URL requirement --- .env.example | 4 +++- README.md | 13 ++++++++++++- frontend/.env.example | 2 ++ 3 files changed, 17 insertions(+), 2 deletions(-) diff --git a/.env.example b/.env.example index 03da5e7d..5dd671a2 100644 --- a/.env.example +++ b/.env.example @@ -19,5 +19,7 @@ CORS_ORIGINS=http://localhost:3000 DB_AUTO_MIGRATE=true # --- frontend settings --- -# Public URL used by the browser to reach the API +# REQUIRED: Public URL used by the browser to reach the API. +# If this is missing/blank, frontend API calls (e.g. Activity feed) will break. +# Example (local dev / compose on your machine): NEXT_PUBLIC_API_URL=http://localhost:8000 diff --git a/README.md b/README.md index 4498e820..6b9f0e6a 100644 --- a/README.md +++ b/README.md @@ -34,6 +34,10 @@ OpenClaw Mission Control is under active development. Expect breaking changes an ```bash cp .env.example .env +# REQUIRED: ensure the browser can reach the backend API. +# If you change ports/hosts, update NEXT_PUBLIC_API_URL in .env accordingly. +# (Missing/blank NEXT_PUBLIC_API_URL will break frontend API calls like Activity feed.) + # IMPORTANT: if you are not configuring Clerk, disable it by ensuring # NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY is NOT set. # (The default `frontend/.env.example` contains placeholders that you should delete/blank.) @@ -112,15 +116,22 @@ Notes: ```bash cd frontend -# Configure API URL (and optionally disable Clerk for local dev by removing/blanking Clerk env vars) +# Configure API URL (REQUIRED) and optionally disable Clerk for local dev by removing/blanking Clerk env vars cp .env.example .env.local +# If you run the backend locally on :8000, this should be: +# NEXT_PUBLIC_API_URL=http://localhost:8000 + npm install npm run dev ``` Open http://localhost:3000. +### Cypress E2E (local) + +When running Cypress (`cd frontend && npm run e2e`), make sure `NEXT_PUBLIC_API_URL` is set (either in `frontend/.env.local` or your shell env). In CI we run the frontend on `http://localhost:3000`, so `NEXT_PUBLIC_API_URL` is set to `http://localhost:3000` for the E2E job. + ## Key concepts / high-level architecture - **Mission Control backend** exposes a REST API at `/api/v1/*` and also hosts health endpoints (`/healthz`, `/readyz`). diff --git a/frontend/.env.example b/frontend/.env.example index cd49a500..05c37014 100644 --- a/frontend/.env.example +++ b/frontend/.env.example @@ -1,4 +1,6 @@ +# REQUIRED: base URL for frontend -> backend calls (must be set for Activity feed and other API calls) NEXT_PUBLIC_API_URL=http://localhost:8000 + NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY CLERK_SECRET_KEY=YOUR_SECRET_KEY NEXT_PUBLIC_CLERK_SIGN_IN_FORCE_REDIRECT_URL=/boards From bbbba764e16067194215c017d18d5dc99dc66e18 Mon Sep 17 00:00:00 2001 From: "Sana (OpenClaw)" Date: Sun, 8 Feb 2026 15:41:28 +0000 Subject: [PATCH 2/3] docs: add troubleshooting note for NEXT_PUBLIC_API_URL --- README.md | 2 ++ docs/troubleshooting/README.md | 17 +++++++++++++++++ 2 files changed, 19 insertions(+) create mode 100644 docs/troubleshooting/README.md diff --git a/README.md b/README.md index 6b9f0e6a..fc602be7 100644 --- a/README.md +++ b/README.md @@ -160,6 +160,8 @@ make check ## Troubleshooting +More: [`docs/troubleshooting/README.md`](./docs/troubleshooting/README.md) + ### Frontend keeps redirecting / Clerk errors You likely have `NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY` set (even to a placeholder). To run without Clerk: diff --git a/docs/troubleshooting/README.md b/docs/troubleshooting/README.md new file mode 100644 index 00000000..a6b69079 --- /dev/null +++ b/docs/troubleshooting/README.md @@ -0,0 +1,17 @@ +# Troubleshooting + +## Activity feed is blank / frontend API calls fail + +**Symptoms** +- Activity feed shows no items. +- The browser console/network tab shows failed requests to `/api/v1/*`. + +**Cause** +- `NEXT_PUBLIC_API_URL` is missing/blank/incorrect. The frontend uses this variable to build API URLs. + +**Fix** +- Local dev: set `NEXT_PUBLIC_API_URL=http://localhost:8000` in `frontend/.env.local`. +- Docker Compose (self-host): set `NEXT_PUBLIC_API_URL=http://localhost:8000` in the root `.env` used by compose (or update it to match your actual backend host/port). + +Notes: +- `NEXT_PUBLIC_API_URL` must be reachable from the browser (not just from within containers). From b8cfdabea0b4e0ca5104a59bd4dbc937b39f6596 Mon Sep 17 00:00:00 2001 From: "Sana (OpenClaw)" Date: Sun, 8 Feb 2026 15:47:40 +0000 Subject: [PATCH 3/3] docs: clarify NEXT_PUBLIC_API_URL must be browser-reachable --- README.md | 1 + docs/troubleshooting/README.md | 2 +- frontend/.env.example | 3 ++- 3 files changed, 4 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index fc602be7..ca4cc648 100644 --- a/README.md +++ b/README.md @@ -35,6 +35,7 @@ OpenClaw Mission Control is under active development. Expect breaking changes an cp .env.example .env # REQUIRED: ensure the browser can reach the backend API. +# NEXT_PUBLIC_API_URL must be reachable from the *browser* (host), not an internal Docker network name. # If you change ports/hosts, update NEXT_PUBLIC_API_URL in .env accordingly. # (Missing/blank NEXT_PUBLIC_API_URL will break frontend API calls like Activity feed.) diff --git a/docs/troubleshooting/README.md b/docs/troubleshooting/README.md index a6b69079..49baac8a 100644 --- a/docs/troubleshooting/README.md +++ b/docs/troubleshooting/README.md @@ -14,4 +14,4 @@ - Docker Compose (self-host): set `NEXT_PUBLIC_API_URL=http://localhost:8000` in the root `.env` used by compose (or update it to match your actual backend host/port). Notes: -- `NEXT_PUBLIC_API_URL` must be reachable from the browser (not just from within containers). +- `NEXT_PUBLIC_API_URL` must be reachable from the browser. If you're using Docker Compose, don't set it to an internal service name like `http://backend:8000` unless the browser can resolve it. diff --git a/frontend/.env.example b/frontend/.env.example index 05c37014..9c4a3f7a 100644 --- a/frontend/.env.example +++ b/frontend/.env.example @@ -1,4 +1,5 @@ -# REQUIRED: base URL for frontend -> backend calls (must be set for Activity feed and other API calls) +# REQUIRED: base URL for frontend -> backend calls (must be set for Activity feed and other API calls). +# Must be reachable from the browser (host). NEXT_PUBLIC_API_URL=http://localhost:8000 NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY=YOUR_PUBLISHABLE_KEY