@swiss-ai-hub/web 0.290.11 → 0.291.0

package/README.md

@@ -109,43 +109,45 @@ you get cryptic errors like _"Vue instance ... was created in a different applic
 requirement applies to PrimeVue, whose theme system relies on a global singleton (two instances → unstyled components).
 
 The fix is to force the whole dependency tree onto one Vue version using your package manager's override mechanism. Add
-this to your project's `package.json`:
+the **`vue`** override to your project's `package.json` — this is the one that actually breaks if omitted. Note the key
+differs per package manager (npm/pnpm use `overrides`, Yarn uses `resolutions`):
 
 ```jsonc
-// npm or yarn
-{
-  "overrides": {
-    "vue": "3.5.17",
-    "@vueuse/router": { "vue-router": "4.6.4" }
-  }
-}
+// npm
+{ "overrides": { "vue": "3.5.17" } }
+```
+
+```jsonc
+// Yarn
+{ "resolutions": { "vue": "3.5.17" } }
 ```
 
 ```jsonc
 // pnpm
-{
-  "pnpm": {
-    "overrides": {
-      "vue": "3.5.17",
-      "@vueuse/router>vue-router": "4.6.4"
-    }
-  }
-}
+{ "pnpm": { "overrides": { "vue": "3.5.17" } } }
 ```
 
 Then reinstall from a clean state so the lockfile is regenerated, and confirm a single Vue instance:
 
 ```bash
-rm -rf node_modules package-lock.json   # or pnpm-lock.yaml
+rm -rf node_modules package-lock.json   # or yarn.lock / pnpm-lock.yaml
 npm install
 npm ls @vue/runtime-core                # must print exactly one version: 3.5.17
 ```
 
-> **Why these entries?** `vue` pins the framework runtime to a single instance shared by your app, the layer, and every
-> Nuxt module -- this is the one that actually breaks if omitted. The scoped `@vueuse/router > vue-router` entry
-> resolves a harmless peer-range mismatch (`@vueuse/router` expects vue-router 4, Nuxt's router is 5); it is scoped so
-> it only affects that one nested dependency and never the router Nuxt itself uses. The versions match the
-> [peer dependencies](#peer-dependencies) the layer is built and tested against.
+The same single-instance requirement applies to **PrimeVue** (its theme system is a global singleton); pinning the
+`primevue` peer to one version is enough — it does not need an override.
+
+> **Optional — silence a `vue-router` peer warning.** `@vueuse/router` declares a `vue-router@^4` peer, but some
+> transitive dependencies may pull in `vue-router` 5.x, which can surface a peer-range warning on install. It is
+> harmless (the layer does not depend on that resolution), but if you want it gone, pin `vue-router` to `4.6.4` **scoped
+> to `@vueuse/router`** so it never affects the router Nuxt itself uses:
+>
+> ```jsonc
+> // npm:  "overrides":  { "@vueuse/router": { "vue-router": "4.6.4" } }
+> // Yarn: "resolutions": { "@vueuse/router/vue-router": "4.6.4" }
+> // pnpm: "pnpm": { "overrides": { "@vueuse/router>vue-router": "4.6.4" } }
+> ```
 
 ## Quick start
 
@@ -170,8 +172,9 @@ Replace the generated `nuxt.config.ts` with:
 export default defineNuxtConfig({
   extends: ['@swiss-ai-hub/web'],
 
-  // These defaults match infra/docker-compose.dev.yml + `make run-api`.
-  // In production, override via NUXT_PUBLIC_* environment variables.
+  // These dev defaults match infra/docker-compose.dev.yml + `make run-api`.
+  // For production, leave these declared (the keys must exist) but blank, and
+  // inject values at runtime via /config.js -- see Runtime configuration below.
   runtimeConfig: {
     public: {
       env: 'dev',
@@ -405,12 +408,19 @@ ______________________________________________________________________
 npx nuxi generate
 ```
 
-This produces a fully static site in `.output/public/`. Runtime configuration values are baked in during build, but you
-can override them at runtime using `NUXT_PUBLIC_*` environment variables (Nuxt rewrites them on the client at startup).
+This produces a fully static SPA in `.output/public/` (the layer is client-only -- `ssr: false`). Because the output is
+static, there is **no Node server at runtime to read environment variables**. Instead, the layer ships a small
+runtime-config mechanism (see [Runtime configuration](#runtime-configuration)) so you build **one** image and configure
+it per environment at container start -- including which backend API it talks to.
 
 ### Dockerfile example
 
+This mirrors how Swiss AI Hub ships the admin UI: build the static site, serve it with nginx, and generate `/config.js`
+from a template at startup so the same image works in any environment.
+
 ```dockerfile
+# 1. Build the static SPA. ENV must be unset (or anything other than 'dev') so
+#    the layer emits the <script src="/config.js"> tag that loads runtime config.
 FROM node:22-alpine AS build
 WORKDIR /app
 COPY package.json package-lock.json ./
@@ -418,24 +428,100 @@ RUN npm ci
 COPY . .
 RUN npx nuxi generate
 
+# 2. Serve with nginx; render /config.js from env vars on container start.
 FROM nginx:alpine
+RUN apk add --no-cache gettext   # provides envsubst
 COPY --from=build /app/.output/public /usr/share/nginx/html
+COPY config.template.js /usr/share/nginx/html/config.template.js
+CMD ["/bin/sh", "-c", "envsubst < /usr/share/nginx/html/config.template.js > /usr/share/nginx/html/config.js && nginx -g 'daemon off;'"]
+```
+
+nginx must serve `/config.js` uncached and never fall back to `index.html` for it -- declare it **before** the SPA
+catch-all:
+
+```nginx
+location = /config.js {
+  add_header Cache-Control "no-store" always;
+  default_type application/javascript;
+  try_files $uri =404;
+}
+location / { try_files $uri /index.html; }
 ```
 
 ______________________________________________________________________
 
 ## Runtime configuration
 
-All configuration is provided through `runtimeConfig.public` in `nuxt.config.ts`. In production, override them via
-environment variables -- Nuxt automatically maps `NUXT_PUBLIC_*` variables to the corresponding config keys:
+The layer reads all runtime configuration from `runtimeConfig.public`, populated in **two phases**:
+
+1. **Build-time defaults** -- whatever you put in `runtimeConfig.public` in your `nuxt.config.ts`. Used directly in dev,
+   baked into the static build.
+2. **Runtime overrides (production)** -- a `window.__AIHUB_CONFIG__` object loaded synchronously from `/config.js`
+   **before** the app boots. A plugin shipped in this layer (`plugins/0.runtime-config.client.ts`) maps it into
+   `runtimeConfig.public`. This is how a single static build is configured per environment without rebuilding.
+
+`/config.js` is rendered by `envsubst` from your `config.template.js` at container start (see the Dockerfile above). The
+layer injects the `<script src="/config.js">` tag automatically for any non-dev build, and the mapping plugin runs in
+every app that extends the layer -- so you only supply the template:
+
+```js
+// config.template.js -- envsubst replaces ${...} at container start.
+// Include only the keys your deployment needs; unset ones resolve to defaults.
+window.__AIHUB_CONFIG__ = {
+  API_BASE_URL: '${API_BASE_URL}',
+  OAUTH_CLIENT_ID: '${OAUTH_CLIENT_ID}',
+  OAUTH_AUTHORITY_URL: '${OAUTH_AUTHORITY_URL}',
+  WEBUI_URL: '${WEBUI_URL}',
+  WS_ENDPOINT: '${WS_ENDPOINT}',
+}
+```
 
-| Config key          | Environment variable             | Default (dev)                                 | Description                          |
-| ------------------- | -------------------------------- | --------------------------------------------- | ------------------------------------ |
-| `env`               | `NUXT_PUBLIC_ENV`                | `dev`                                         | Environment identifier               |
-| `oidc.clientId`     | `NUXT_PUBLIC_OIDC_CLIENT_ID`     | `aihub-frontend`                              | OIDC client ID for Keycloak          |
-| `oidc.authorityUrl` | `NUXT_PUBLIC_OIDC_AUTHORITY_URL` | `http://localhost:8180/realms/aihub`          | Keycloak realm URL                   |
-| `webui.url`         | `NUXT_PUBLIC_WEBUI_URL`          | `http://localhost:8080`                       | Open-WebUI URL (chat link)           |
-| `ws.endpoint`       | `NUXT_PUBLIC_WS_ENDPOINT`        | `ws://localhost:8000/api/v1/active/events/ws` | WebSocket for real-time agent events |
+| `runtimeConfig.public` key | `window.__AIHUB_CONFIG__` key | Default                 | Description                                                        |
+| -------------------------- | ----------------------------- | ----------------------- | ------------------------------------------------------------------ |
+| `apiBaseUrl`               | `API_BASE_URL`                | `/api/v1` (same origin) | Backend API base URL -- see [below](#pointing-at-your-backend-api) |
+| `oidc.clientId`            | `OAUTH_CLIENT_ID`             | --                      | OIDC client ID (Keycloak)                                          |
+| `oidc.authorityUrl`        | `OAUTH_AUTHORITY_URL`         | --                      | OIDC authority / realm URL                                         |
+| `webui.url`                | `WEBUI_URL`                   | --                      | Open-WebUI URL (chat link)                                         |
+| `ws.endpoint`              | `WS_ENDPOINT`                 | --                      | WebSocket endpoint for real-time agent events                      |
+| `env`                      | --                            | --                      | Set to `dev` locally (uses build-time values, skips `/config.js`)  |
+
+> **Declare the groups you want populated.** The mapping plugin only writes into config groups your app already declared
+> in `runtimeConfig.public` (e.g. `oidc: {}`, `webui: {}`, `ws: {}`); in production set their build-time values to empty
+> strings and let `/config.js` fill them. `apiBaseUrl` is the exception -- it is always applied when `API_BASE_URL` is
+> present.
+
+### Pointing at your backend API
+
+The admin UI talks to the Swiss AI Hub backend through a single base URL, `runtimeConfig.public.apiBaseUrl`. It defaults
+to the **same origin** as the UI (`/api/v1`) -- the simplest setup: put the UI and the API behind one reverse proxy
+(what the platform's Traefik does) and no API configuration is needed at all.
+
+If your UI is served from a **different origin** than the API, set the base URL explicitly:
+
+- **Dev / build-time** -- set it in `nuxt.config.ts`, or (recommended for local dev) keep `/api/v1` and proxy it with
+  Nitro:
+
+  ```ts
+  export default defineNuxtConfig({
+    extends: ['@swiss-ai-hub/web'],
+    // Option A: point straight at the API origin
+    runtimeConfig: { public: { apiBaseUrl: 'https://aihub.example.com/api/v1' } },
+    // Option B (same-origin dev): keep /api/v1 and proxy it
+    nitro: { devProxy: { '/api/v1': { target: 'http://localhost:8000/api/v1', changeOrigin: true, ws: true } } },
+  })
+  ```
+
+- **Production (static image)** -- inject `API_BASE_URL` at container start via `config.template.js`. One image, any
+  backend:
+
+  ```bash
+  docker run -e API_BASE_URL=https://aihub.example.com/api/v1 my-aihub-frontend
+  ```
+
+> **Cross-origin caveats.** A different API origin must allow your UI's origin via CORS, and your Keycloak client must
+> list it as an allowed web/redirect origin. Same-origin (`/api/v1` behind one proxy) avoids both. Do **not** call
+> `client.setConfig({ baseURL: ... })` in your own `app.vue` unless you deliberately want to hard-override this
+> mechanism.
 
 ## Peer dependencies
 

package/package.json

@@ -3,7 +3,7 @@
   "license": "AGPL-3.0-or-later",
   "author": "bbv Software Services AG (https://www.bbv.ch)",
   "type": "module",
-  "version": "0.290.11",
+  "version": "0.291.0",
   "description": "Swiss AI Hub - Admin & Management UI (Nuxt 3 layer)",
   "main": "./nuxt.config.ts",
   "repository": {