From 81d9e4af507d89c69e9769d54a792c80e998b3b1 Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Fri, 2 Oct 2026 12:40:57 +0000 Subject: [PATCH 1/2] Add a first-run setup wizard, with .env values that answer it; fix startup on a fresh database A fresh install walks its first admin through the first namespace, the model provider and storage in the web app, after the admin account (still behind the one-time setup code). LENS_ADMIN_*, LENS_NAMESPACE and LENS_LLM_* in .env answer it instead; environment values win and show locked. Installs that already had accounts never see it. Define the seq table with the schema: SurrealDB 3 refused to read it before anything wrote to it, so the API failed to start on a fresh database whose archive.yaml had no namespaces. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01WjEWJZ9XYFxL19mNfXgfPK --- CHANGELOG.md | 13 + docs/authentication.md | 5 +- docs/configuration.md | 23 + docs/get-started.md | 4 +- fastapi_backend/.env.example | 10 + fastapi_backend/app/api/v1/router.py | 2 + fastapi_backend/app/api/v1/routes/auth.py | 9 +- fastapi_backend/app/api/v1/routes/setup.py | 74 +++ fastapi_backend/app/core/runtime.py | 5 +- fastapi_backend/app/domain/settings.py | 36 +- fastapi_backend/app/domain/setup.py | 138 +++++ fastapi_backend/app/domain/store.py | 6 + fastapi_backend/app/schemas/auth.py | 2 + fastapi_backend/app/schemas/setup.py | 67 +++ fastapi_backend/tests/api/test_auth.py | 4 +- fastapi_backend/tests/api/test_setup.py | 164 ++++++ nextjs-frontend/__tests__/setupAction.test.ts | 2 +- .../__tests__/setupWizard.test.tsx | 139 +++++ nextjs-frontend/app/(app)/layout.tsx | 3 + nextjs-frontend/app/(setup)/layout.tsx | 23 + nextjs-frontend/app/(setup)/welcome/page.tsx | 16 + nextjs-frontend/app/openapi-client/sdk.gen.ts | 90 ++- .../app/openapi-client/types.gen.ts | 295 +++++++++- .../components/actions/setup-action.ts | 4 +- .../components/settings/section.tsx | 4 + .../components/setup/setup-wizard.tsx | 525 ++++++++++++++++++ nextjs-frontend/lib/auth/status.ts | 18 +- nextjs-frontend/openapi.json | 480 +++++++++++++++- 28 files changed, 2138 insertions(+), 23 deletions(-) create mode 100644 fastapi_backend/app/api/v1/routes/setup.py create mode 100644 fastapi_backend/app/domain/setup.py create mode 100644 fastapi_backend/app/schemas/setup.py create mode 100644 fastapi_backend/tests/api/test_setup.py create mode 100644 nextjs-frontend/__tests__/setupWizard.test.tsx create mode 100644 nextjs-frontend/app/(setup)/layout.tsx create mode 100644 nextjs-frontend/app/(setup)/welcome/page.tsx create mode 100644 nextjs-frontend/components/setup/setup-wizard.tsx diff --git a/CHANGELOG.md b/CHANGELOG.md index ddf835383..973d773a2 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,6 +4,19 @@ The backend (`fastapi_backend`) and the frontend (`nextjs-frontend`) are version ## Unreleased +- **First-run setup wizard.** A fresh install now walks its first admin through setup in the web app: after the + admin account (still with the one-time setup code, so a stranger can't claim a public server) come the first + namespace, the model provider (with a connection test) and storage (the upload limit, and a folder to watch). + Every step and the whole wizard can be skipped; installs that already had accounts never see it + (docs/configuration.md#first-run-setup). + - Or answer it in `.env`: `LENS_ADMIN_EMAIL` / `LENS_ADMIN_PASSWORD` create the first admin at startup, + `LENS_NAMESPACE` the first namespace, `LENS_LLM_BASE_URL` / `LENS_LLM_MODEL` / `LENS_LLM_API_KEY` set the + model provider, and `LENS_SETUP_WIZARD=off` turns the wizard off. Environment values win over the app, and + the wizard and Settings show them locked; a key from the environment is never shown. +- **Fix: a fresh database with no namespaces in archive.yaml no longer stops the API from starting** with + "table 'seq' does not exist" (SurrealDB 3). The counters table is defined with the rest of the schema now, so + nothing reads it before it exists. + - **Fix: Chat answers no longer break off with "The answer stopped before it finished".** With some model servers an answer ended mid-stream with nothing saved, so the question sat unanswered in the conversation. Now each one ends in an answer, or an error that's shown and saved with the conversation. diff --git a/docs/authentication.md b/docs/authentication.md index d61c1f535..ffae55e00 100644 --- a/docs/authentication.md +++ b/docs/authentication.md @@ -3,7 +3,8 @@ ## People and roles There is no public sign-up. The first admin is created with a one-time **setup code** that the API prints in its log -on first start (or `lens users add you@example.com --admin`). Admins then add people and give them roles per +on first start (or `lens users add you@example.com --admin`, or `LENS_ADMIN_EMAIL` and `LENS_ADMIN_PASSWORD` in +`.env`). On a fresh install the web app then opens a short setup wizard ([Configuration](configuration.md#first-run-setup)). Admins then add people and give them roles per namespace: viewer, editor or owner. Passwords are hashed with scrypt and need at least 10 characters. Failed sign-ins are throttled per email and address @@ -31,7 +32,7 @@ Sign out ──► POST /api/v1/auth/logout (ends the session on the API too) | Endpoint | | |---|---| -| `GET /api/v1/auth/status` | `{setup_required}`: the sign-in page shows the setup form when true | +| `GET /api/v1/auth/status` | `{setup_required, wizard_pending}`: the sign-in page shows the setup form while the first admin is missing; admins are taken to the setup wizard while it is pending | | `POST /api/v1/auth/setup` | first admin, with the setup code | | `POST /api/v1/auth/login` · `/refresh` · `/logout` | token pairs | | `GET /api/v1/auth/me` | the account, roles by namespace, and how the caller authenticated | diff --git a/docs/configuration.md b/docs/configuration.md index a964c4d9a..2b5113e64 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -27,11 +27,34 @@ with AES-GCM and are write-only: the API reports whether one is set, never its v | `ARCHIVE_ALLOWED_HOSTS` | | break-glass override of allowed Host headers if a bad setting locks everyone out | | `RUN_BACKGROUND` | follows `workers.inline` | run job workers and folder watching inside the API process | | `LENS_SETUP_CODE` | random | fix the first-run setup code (automation) | +| `LENS_ADMIN_EMAIL` / `LENS_ADMIN_PASSWORD` / `LENS_ADMIN_NAME` | | create the first admin at startup, with no setup code ([First-run setup](#first-run-setup)) | +| `LENS_NAMESPACE` | | create the first namespace at startup | +| `LENS_LLM_BASE_URL` / `LENS_LLM_MODEL` / `LENS_LLM_API_KEY` / `LENS_LLM_VISION_MODEL` | | the model provider; wins over Settings, which show these locked | +| `LENS_SETUP_WIZARD` | | `off`: never show the setup wizard | | `FRONTEND_URL` | `http://localhost:3000` | links in emails | | `CORS_ORIGINS` | `["http://localhost:3000"]` | origins allowed to call the API from a browser | | `OPENAPI_URL` | `/openapi.json` | `""` disables `/docs` and the schema | | `MAIL_SERVER`, `MAIL_PORT`, `MAIL_USERNAME`, `MAIL_PASSWORD`, `MAIL_FROM`, `MAIL_STARTTLS`, `MAIL_SSL_TLS`, `USE_CREDENTIALS`, `VALIDATE_CERTS` | | SMTP for password reset and for telling owners about requests for access; without `MAIL_SERVER` the links are logged | +## First-run setup + +A fresh install (no accounts when the API first starts) walks its first admin through setup in the web app: + +1. **Admin account**, with the one-time setup code from the log (`make setup-code`), so a stranger who finds a new + public server can't claim it. Skipped when `LENS_ADMIN_EMAIL` and `LENS_ADMIN_PASSWORD` create the admin at + startup; then you sign in with those. +2. **Namespace**: the first one, with its knowledge graph shared or isolated. Already done when archive.yaml or + `LENS_NAMESPACE` names namespaces, or an install script made one. +3. **Model provider**: an OpenAI-compatible server (OpenAI, Ollama, llama.cpp, LM Studio, vLLM), its model and key, + with a test. +4. **Storage**: where data lives (shown; set in archive.yaml and `SURREAL_URL`), the largest upload, and optionally a + folder inside `sources.local_roots` to watch. + +Every step can be skipped, and the whole wizard too; all of it stays in Settings. Values from the environment win and +show locked. Installs that already had accounts never see the wizard. The API side is `GET /api/v1/setup`, +`POST /api/v1/setup/namespace`, `PUT /api/v1/setup/llm`, `PUT /api/v1/setup/storage` and `POST /api/v1/setup/finish` +(admins); `GET /api/v1/auth/status` says whether it is still pending (`wizard_pending`). + ## Frontend environment | Variable | | diff --git a/docs/get-started.md b/docs/get-started.md index 026d35dad..68d67fbe8 100644 --- a/docs/get-started.md +++ b/docs/get-started.md @@ -34,7 +34,9 @@ On first start the API log prints a setup code: No accounts yet. Create the first admin in the web app with setup code: … ``` -Open the web app, choose **Set up**, and create the admin account with it. +Open the web app, choose **Set up**, and create the admin account with it. A short wizard then asks for the first +namespace, the model provider and storage; skip any of it and change it later in Settings +([Configuration](configuration.md#first-run-setup) lists the `.env` values that answer it instead). Put audio under `./local-audio/podcasts` and `./local-audio/interviews` (or set `AUDIO_DIR`), or import transcripts from the web app. Namespaces and folders are configured in `fastapi_backend/docker/archive.yaml`. diff --git a/fastapi_backend/.env.example b/fastapi_backend/.env.example index 462bea041..bfcb43013 100644 --- a/fastapi_backend/.env.example +++ b/fastapi_backend/.env.example @@ -42,5 +42,15 @@ USE_CREDENTIALS=False FRONTEND_URL=http://localhost:3000 CORS_ORIGINS=["http://localhost:3000"] +# --- First run (docs/configuration.md#first-run-setup). Without these, the web app's setup wizard asks. --- +# LENS_SETUP_CODE=choose-one # the first admin's one-time setup code (default: random, in the log) +# LENS_ADMIN_EMAIL=you@example.com # create the first admin at startup (with LENS_ADMIN_PASSWORD) +# LENS_ADMIN_PASSWORD= +# LENS_NAMESPACE=archive # create the first namespace at startup +# LENS_LLM_BASE_URL=http://localhost:11434/v1 # the model provider; these win over Settings and show locked +# LENS_LLM_MODEL=llama3.1 +# LENS_LLM_API_KEY= +# LENS_SETUP_WIZARD=off # never show the wizard + # Uncomment to disable /docs and /openapi.json # OPENAPI_URL="" diff --git a/fastapi_backend/app/api/v1/router.py b/fastapi_backend/app/api/v1/router.py index ae7beba5a..76c30bf2a 100644 --- a/fastapi_backend/app/api/v1/router.py +++ b/fastapi_backend/app/api/v1/router.py @@ -25,6 +25,7 @@ requests, search, searches, + setup, sources, speakers, templates, @@ -40,6 +41,7 @@ for module in ( users, admin, + setup, namespaces, hierarchy, recordings, diff --git a/fastapi_backend/app/api/v1/routes/auth.py b/fastapi_backend/app/api/v1/routes/auth.py index ac085ddb8..48ea489f7 100644 --- a/fastapi_backend/app/api/v1/routes/auth.py +++ b/fastapi_backend/app/api/v1/routes/auth.py @@ -11,6 +11,7 @@ from app.config import settings from app.core.security import create_access_token from app.domain import auth, store +from app.domain import setup as first_run from app.email import send_reset_password_email from app.schemas.auth import ( ApiToken, @@ -43,8 +44,12 @@ def _pair(db: Db, cfg: Cfg, request: Request, user: dict) -> TokenPair: @router.get("/status") def status(request: Request, db: Db) -> AuthStatus: - """Whether the archive still needs its first admin (the sign-in page shows the setup form instead).""" - return AuthStatus(setup_required=request.app.state.archive.setup_code is not None and auth.account_count(db) == 0) + """Whether the archive still needs its first admin (the sign-in page shows the setup form instead), and whether + the first-run wizard is still to be finished (the web app takes admins there).""" + return AuthStatus( + setup_required=request.app.state.archive.setup_code is not None and auth.account_count(db) == 0, + wizard_pending=first_run.pending(db), + ) @router.post("/setup") diff --git a/fastapi_backend/app/api/v1/routes/setup.py b/fastapi_backend/app/api/v1/routes/setup.py new file mode 100644 index 000000000..944bacbb3 --- /dev/null +++ b/fastapi_backend/app/api/v1/routes/setup.py @@ -0,0 +1,74 @@ +"""The first-run setup wizard (admins): the first namespace, the model provider and storage, then finishing it. + +The first admin is created before this, with the setup code (POST /auth/setup) or from the environment. Fields the +environment sets are left out of every save and reported as locked (domain/setup.py). +""" + +from __future__ import annotations + +from fastapi import APIRouter, HTTPException, Request + +from app.api.deps import AdminReader, AdminWriter, Db +from app.domain import auth, setup +from app.schemas.setup import SetupFinish, SetupLlm, SetupNamespace, SetupSaved, SetupStorage, SetupView + +router = APIRouter(prefix="/setup", tags=["setup"]) + + +@router.get("") +def get_setup(user: AdminReader, request: Request, db: Db) -> SetupView: + """What is set already, and which fields .env or archive.yaml locks.""" + return SetupView.model_validate(setup.view(db, request.app.state.archive.base)) + + +@router.post("/namespace") +def save_namespace(body: SetupNamespace, user: AdminWriter, request: Request, db: Db) -> SetupSaved: + """Create the first namespace (or set the graph mode of one that exists).""" + if setup.view(db, request.app.state.archive.base)["namespace"]["locked"]: + raise HTTPException(409, "the namespaces are set in archive.yaml or LENS_NAMESPACE") + try: + setup.save_namespace(db, body.name, body.graph) + except ValueError as e: + raise HTTPException(400, str(e)) from None + auth.audit(db, user.as_audit(), "namespace.create", body.name.strip().lower(), ["setup"]) + request.app.state.graph_cache.clear() + return SetupSaved(saved=["namespace"]) + + +@router.put("/llm") +def save_llm(body: SetupLlm, user: AdminWriter, request: Request, db: Db) -> SetupSaved: + """The model provider: an OpenAI-compatible server's address, the model, and its key (empty: unchanged).""" + values: dict = {"base_url": (body.base_url or "").strip() or None, "model": (body.model or "").strip() or None} + if body.api_key: + values["api_key"] = body.api_key + try: + saved = setup.save_llm(db, request.app.state.archive.base, values, user.email) + except ValueError as e: + raise HTTPException(400, str(e)) from None + if saved: + auth.audit(db, user.as_audit(), "settings.save", "llm", saved) + return SetupSaved(saved=saved) + + +@router.put("/storage") +def save_storage(body: SetupStorage, user: AdminWriter, request: Request, db: Db) -> SetupSaved: + """The upload limit, and optionally a folder on this machine (inside sources.local_roots) to watch.""" + try: + wid = setup.save_storage(db, request.app.state.archive.base, body.max_upload_mb, body.folder, body.namespace, user.email) + except KeyError: + raise HTTPException(400, "no such namespace") from None + except ValueError as e: + raise HTTPException(400, str(e)) from None + if body.max_upload_mb is not None: + auth.audit(db, user.as_audit(), "settings.save", "uploads", ["max_mb"]) + if wid is not None: + auth.audit(db, user.as_audit(), "watch.create", f"watch_path:{wid}") + return SetupSaved(saved=[k for k in ("max_upload_mb", "folder") if getattr(body, k) is not None], watch=wid) + + +@router.post("/finish") +def finish(body: SetupFinish, user: AdminWriter, db: Db) -> SetupSaved: + """Finish (or skip) the wizard; the web app stops showing it. Everything stays changeable in Settings.""" + setup.finish(db, user.email, body.skipped) + auth.audit(db, user.as_audit(), "setup.finish", None, ["skipped"] if body.skipped else None) + return SetupSaved() diff --git a/fastapi_backend/app/core/runtime.py b/fastapi_backend/app/core/runtime.py index 1a15201fc..45aaa8ba2 100644 --- a/fastapi_backend/app/core/runtime.py +++ b/fastapi_backend/app/core/runtime.py @@ -9,7 +9,7 @@ from typing import Any from app.config import settings as env -from app.domain import auth, jobs, settings, sources, store, templates +from app.domain import auth, jobs, settings, setup, sources, store, templates log = logging.getLogger("lens") @@ -32,6 +32,9 @@ def prepare(self) -> None: templates.seed(self.db) # Pay for the embedded engine's full-text repair at startup rather than in someone's first search. self.db.ready_fulltext() + if auth.account_count(self.db) == 0: + setup.mark_fresh(self.db) # a fresh install: the web app walks the first admin through setup + setup.apply_env(self.db) if auth.account_count(self.db) == 0: self.setup_code = os.environ.get("LENS_SETUP_CODE") or secrets.token_urlsafe(9) log.warning("No accounts yet. Create the first admin in the web app with setup code: %s", self.setup_code) diff --git a/fastapi_backend/app/domain/settings.py b/fastapi_backend/app/domain/settings.py index 83a87ee15..bb253a7f8 100644 --- a/fastapi_backend/app/domain/settings.py +++ b/fastapi_backend/app/domain/settings.py @@ -69,7 +69,32 @@ ("video", "face_engine"): {"opencv", "insightface", "none"}, ("video", "object_engine"): {"yolox", "ultralytics", "off"}, } -ENV_OVERRIDES = {("server", "allowed_hosts"): "ARCHIVE_ALLOWED_HOSTS"} +# Settings the environment (.env) sets, which win over archive.yaml and the app and show as locked there: the +# break-glass allowed hosts, and the model provider so an install can be configured without the setup wizard. +ENV_OVERRIDES = { + ("server", "allowed_hosts"): "ARCHIVE_ALLOWED_HOSTS", + ("llm", "base_url"): "LENS_LLM_BASE_URL", + ("llm", "model"): "LENS_LLM_MODEL", + ("llm", "api_key"): "LENS_LLM_API_KEY", + ("llm", "vision_model"): "LENS_LLM_VISION_MODEL", +} + + +def env_value(section, key): + """The environment's value for a setting in ENV_OVERRIDES, parsed; None when it isn't set.""" + raw = os.environ.get(ENV_OVERRIDES.get((section, key)) or "", "").strip() + if not raw: + return None + if isinstance(store.DEFAULTS.get(section, {}).get(key), list): + return [x.strip() for x in raw.split(",") if x.strip()] + return raw + + +def locked(section): + """The keys of a section the environment sets.""" + return [k for (s, k) in ENV_OVERRIDES if s == section and env_value(s, k) is not None] + + # The types uploads.extensions may name: what the folder scans import, a few more that ffmpeg reads, and documents and # images. UPLOAD_TYPES = frozenset([*store.MEDIA_EXT, ".aif", ".aiff", ".wma", ".mpg", ".mpeg", ".3gp", *store.DOCUMENT_EXT, *store.IMAGE_EXT]) @@ -143,9 +168,10 @@ def effective(db, base, reveal=True): cfg[sec][k] = unseal(base, sealed, f"setting:{sec}.{k}") except Exception: # noqa: BLE001 - key changed since it was saved cfg[sec][k] = None - for (sec, key), env in ENV_OVERRIDES.items(): - if os.environ.get(env): - cfg[sec][key] = [x.strip() for x in os.environ[env].split(",") if x.strip()] + for sec, key in ENV_OVERRIDES: + v = env_value(sec, key) + if v is not None: + cfg[sec][key] = {"secret": True, "set": True} if not reveal and key in SECRETS.get(sec, ()) else v return cfg @@ -178,7 +204,7 @@ def view(db, base): "values": vals, "updated_at": (meta.get(sec) or {}).get("updated_at"), "updated_by": (meta.get(sec) or {}).get("updated_by"), - "locked": [k for (s, k), env in ENV_OVERRIDES.items() if s == sec and os.environ.get(env)], + "locked": locked(sec), } out["bootstrap"] = { "database": db.url, diff --git a/fastapi_backend/app/domain/setup.py b/fastapi_backend/app/domain/setup.py new file mode 100644 index 000000000..9edffde73 --- /dev/null +++ b/fastapi_backend/app/domain/setup.py @@ -0,0 +1,138 @@ +"""First-run setup: what a fresh install still needs, from the environment (.env) or the web wizard. + +A fresh install (no accounts when the API first starts) is marked with setup:wizard. The web app then walks the first +admin through the rest (the first namespace, the model provider, storage) until they finish or skip it; installs that +already had accounts never see the wizard. Whatever the environment sets is applied at startup and wins: the wizard +shows those fields locked. + + LENS_ADMIN_EMAIL, LENS_ADMIN_PASSWORD, LENS_ADMIN_NAME the first admin, created at startup (no setup code needed) + LENS_NAMESPACE the first namespace, created at startup + LENS_LLM_BASE_URL, LENS_LLM_MODEL, LENS_LLM_API_KEY the model provider (settings.ENV_OVERRIDES) + LENS_SETUP_WIZARD=off never show the wizard (everything comes from .env) + +The first admin still needs the one-time setup code (or the environment), so a stranger can't claim a public server. +""" + +from __future__ import annotations + +import logging +import os + +from . import auth, settings, sources, store + +R = store.R +WIZARD = ("setup", "wizard") +log = logging.getLogger("lens") + + +def _off(): + return os.environ.get("LENS_SETUP_WIZARD", "").strip().lower() in ("off", "false", "0", "no", "done") + + +def pending(db): + """Whether the web wizard is still to be finished.""" + if _off(): + return False + row = db.one("SELECT done_at FROM $r", r=R(*WIZARD)) + return bool(row) and not row.get("done_at") + + +def mark_fresh(db): + """Called at startup while no accounts exist: this install gets the wizard (once; finishing it is kept).""" + if not db.one("SELECT id FROM $r", r=R(*WIZARD)): + db.q("UPSERT $r CONTENT $d", r=R(*WIZARD), d={"created_at": store.now()}) + + +def finish(db, user=None, skipped=False): + db.q("UPDATE $r SET done_at = $t, done_by = $u, skipped = $s", r=R(*WIZARD), t=store.now(), u=user, s=skipped) + + +def env_admin(): + email, password = os.environ.get("LENS_ADMIN_EMAIL", "").strip(), os.environ.get("LENS_ADMIN_PASSWORD", "") + return (email, password, os.environ.get("LENS_ADMIN_NAME", "").strip() or None) if email and password else None + + +def env_namespace(): + return os.environ.get("LENS_NAMESPACE", "").strip().lower() or None + + +def apply_env(db): + """Create what the environment names and doesn't exist yet: the first admin, the first namespace.""" + admin = env_admin() + if admin and auth.account_count(db) == 0: + try: + uid = auth.create_account(db, admin[0], admin[1], admin[2], admin=True) + except ValueError as e: + log.error("LENS_ADMIN_EMAIL / LENS_ADMIN_PASSWORD: %s; create the first admin in the web app instead", e) + else: + auth.audit(db, {"id": uid, "email": admin[0]}, "setup", detail=["environment"]) + log.info("Created the first admin %s from the environment", admin[0]) + name = env_namespace() + if name: + if not store.NS_RX.match(name): + log.error("LENS_NAMESPACE %r: namespace names use lowercase letters, digits, - and _", name) + else: + store.ns_id(db, name) + + +def view(db, cfg): + """The wizard's starting point: what is set already, and which fields the environment or archive.yaml locks.""" + shown = settings.effective(db, cfg, reveal=False) + llm = {k: shown["llm"].get(k) for k in ("base_url", "model", "api_key", "vision_model")} + if not isinstance(llm["api_key"], dict): + llm["api_key"] = {"secret": True, "set": False} + names = [r["name"] for r in db.rows("SELECT name FROM space ORDER BY name")] + admin = env_admin() + return { + "pending": pending(db), + "admin": {"from_env": bool(admin)}, + "namespace": { + "existing": names, + # archive.yaml or LENS_NAMESPACE named the namespaces: the wizard shows them instead of asking + "locked": bool(env_namespace() or cfg["namespaces"]), + }, + "llm": {"values": llm, "locked": settings.locked("llm")}, + "storage": { + "data_dir": cfg["data_dir"], + "database": db.url, + "embedded": db.embedded, + "local_roots": cfg["sources"].get("local_roots") or [], + "max_upload_mb": shown["uploads"]["max_mb"], + "watches": len(db.values("SELECT VALUE id FROM watch_path")), + }, + } + + +def save_namespace(db, name, graph="shared"): + name = (name or "").strip().lower() + if not store.NS_RX.match(name): + raise ValueError("namespace names use lowercase letters, digits, - and _") + if graph not in ("shared", "isolated"): + raise ValueError("graph is shared or isolated") + sid = store.ns_id(db, name) + db.q("UPDATE $r SET graph = $g", r=R("space", sid), g=graph) + return sid + + +def save_llm(db, cfg, values, user=None): + """Save the model provider, leaving out what the environment sets (it would win anyway).""" + keep = {k: v for k, v in values.items() if k not in settings.locked("llm")} + if keep: + settings.save(db, cfg, "llm", keep, user) + return sorted(keep) + + +def save_storage(db, cfg, max_upload_mb=None, folder=None, namespace=None, user=None): + """The upload limit, and optionally a folder on this machine (inside sources.local_roots) watched into a + namespace. Returns the watch's id, if one was made.""" + if max_upload_mb is not None: + settings.save(db, cfg, "uploads", {"max_mb": max_upload_mb}, user) + if not folder: + return None + if not namespace: + raise ValueError("choose the namespace the folder's files go into") + sid = store.ns_id(db, namespace, create=False) + src = next((s["id"] for s in sources.list_sources(db) if s.get("type") == "local"), None) + if src is None: + src = sources.create(db, cfg, "Folders on this machine", "local", {}, {}, user) + return sources.create_watch(db, cfg, src, folder, sid, user) diff --git a/fastapi_backend/app/domain/store.py b/fastapi_backend/app/domain/store.py index 23f730a45..e0c829435 100644 --- a/fastapi_backend/app/domain/store.py +++ b/fastapi_backend/app/domain/store.py @@ -492,6 +492,12 @@ def close(self): SCHEMA = [ + # counters (next_id), the migration marker and the settings version. Defined up front: SurrealDB 3 refuses to + # SELECT from a table nobody has written to yet ("table 'seq' does not exist"), which a fresh database with no + # namespaces in archive.yaml would otherwise hit in migrate() before anything had created it. + "DEFINE TABLE IF NOT EXISTS seq SCHEMALESS", + # first-run setup (domain/setup.py): setup:wizard while the web wizard is still to be finished + "DEFINE TABLE IF NOT EXISTS setup SCHEMALESS", # No composite indexes: on SurrealDB 2.x a (space, x) index makes "space = $s" lookups return nothing, so # uniqueness is enforced on single ":" key fields instead. "DEFINE TABLE IF NOT EXISTS space SCHEMALESS", diff --git a/fastapi_backend/app/schemas/auth.py b/fastapi_backend/app/schemas/auth.py index e518d501a..2f7d19e78 100644 --- a/fastapi_backend/app/schemas/auth.py +++ b/fastapi_backend/app/schemas/auth.py @@ -19,6 +19,8 @@ class UserPublic(ResponseModel): class AuthStatus(ResponseModel): setup_required: bool + # a fresh install whose setup wizard (namespace, model provider, storage) the first admin hasn't finished + wizard_pending: bool = False class LoginRequest(RequestModel): diff --git a/fastapi_backend/app/schemas/setup.py b/fastapi_backend/app/schemas/setup.py new file mode 100644 index 000000000..93e409b5a --- /dev/null +++ b/fastapi_backend/app/schemas/setup.py @@ -0,0 +1,67 @@ +from __future__ import annotations + +from typing import Any, Literal + +from pydantic import Field + +from app.schemas.common import RequestModel, ResponseModel + + +class SetupAdmin(ResponseModel): + from_env: bool + + +class SetupNamespaceView(ResponseModel): + existing: list[str] + locked: bool + + +class SetupLlmView(ResponseModel): + values: dict[str, Any] + locked: list[str] + + +class SetupStorageView(ResponseModel): + data_dir: str + database: str + embedded: bool + local_roots: list[str] + max_upload_mb: int + watches: int + + +class SetupView(ResponseModel): + pending: bool + admin: SetupAdmin + namespace: SetupNamespaceView + llm: SetupLlmView + storage: SetupStorageView + + +class SetupNamespace(RequestModel): + name: str = Field(min_length=1, max_length=41) + graph: Literal["shared", "isolated"] = "shared" + + +class SetupLlm(RequestModel): + base_url: str | None = Field(default=None, max_length=500) + model: str | None = Field(default=None, max_length=200) + # empty: leave the saved key as it is + api_key: str | None = Field(default=None, max_length=2000) + + +class SetupStorage(RequestModel): + max_upload_mb: int | None = None + # a folder inside sources.local_roots to watch into `namespace` + folder: str | None = Field(default=None, max_length=4096) + namespace: str | None = None + + +class SetupFinish(RequestModel): + skipped: bool = False + + +class SetupSaved(ResponseModel): + ok: bool = True + saved: list[str] = [] + watch: int | None = None diff --git a/fastapi_backend/tests/api/test_auth.py b/fastapi_backend/tests/api/test_auth.py index b51f20cb6..be9bba7e0 100644 --- a/fastapi_backend/tests/api/test_auth.py +++ b/fastapi_backend/tests/api/test_auth.py @@ -8,7 +8,7 @@ def test_first_run_setup(app, client): r = client.get("/api/v1/auth/status") - assert r.json() == {"setup_required": True} + assert r.json() == {"setup_required": True, "wizard_pending": True} assert client.get("/api/v1/auth/me").status_code == 401 bad = {"code": "nope", "email": "ada@x.io", "password": "admin password 1"} assert client.post("/api/v1/auth/setup", json=bad).status_code == 403 @@ -20,7 +20,7 @@ def test_first_run_setup(app, client): me = client.get("/api/v1/auth/me", headers={"Authorization": f"Bearer {pair['access_token']}"}).json() assert me["user"]["email"] == "ada@x.io" and me["via"] == "access" and set(me["roles"]) == {"pods", "calls"} assert client.post("/api/v1/auth/setup", json={"code": code, "email": "b@x.io", "password": "another password"}).status_code == 403 - assert client.get("/api/v1/auth/status").json() == {"setup_required": False} + assert client.get("/api/v1/auth/status").json() == {"setup_required": False, "wizard_pending": True} def test_login_refresh_logout(client, db): diff --git a/fastapi_backend/tests/api/test_setup.py b/fastapi_backend/tests/api/test_setup.py new file mode 100644 index 000000000..5f5e1770d --- /dev/null +++ b/fastapi_backend/tests/api/test_setup.py @@ -0,0 +1,164 @@ +"""First-run setup: the web wizard after the first admin, what the environment sets (and locks), and a fresh database +with no namespaces in archive.yaml.""" + +from __future__ import annotations + +import uuid + +import pytest +from fastapi.testclient import TestClient + +from app.domain import auth, store +from tests.conftest import TEST_URL +from tests.helpers import login, make_user + +ENV = ("LENS_ADMIN_EMAIL", "LENS_ADMIN_PASSWORD", "LENS_ADMIN_NAME", "LENS_NAMESPACE", "LENS_SETUP_WIZARD") +LLM_ENV = ("LENS_LLM_BASE_URL", "LENS_LLM_MODEL", "LENS_LLM_API_KEY", "LENS_LLM_VISION_MODEL") + + +@pytest.fixture(autouse=True) +def clean_env(monkeypatch): + for k in ENV + LLM_ENV: + monkeypatch.delenv(k, raising=False) + + +def bare_cfg(folder): + """archive.yaml with no namespaces, like a fresh install.""" + cfg = store.load_config( + str(folder / "missing.yaml"), + overrides={ + "data_dir": str(folder / "data"), + "database": {"url": TEST_URL, "database": "t" + uuid.uuid4().hex[:10]}, + "server": {"allowed_hosts": ["127.0.0.1", "localhost", "testserver"]}, + "sources": {"local_roots": [str(folder / "inbox")]}, + }, + ) + assert cfg["namespaces"] == {} + return cfg + + +@pytest.fixture +def fresh(folder): + """Open a fresh archive (no namespaces) with whatever the environment says, as the API does at startup.""" + from app.main import create_app + + opened = [] + + def make(): + cfg = bare_cfg(folder) + db = store.connect(cfg) + opened.append(db) + auth._FAILS.clear() + app = create_app(cfg, db, background=False) + return app, TestClient(app, base_url="http://127.0.0.1") + + yield make + for db in opened: + db.close() + + +def test_fresh_database_without_namespaces_starts(folder): + db = store.connect(bare_cfg(folder)) + try: + assert db.values("SELECT VALUE n FROM $r", r=store.R("seq", "migrations")) == [2] + assert store.space_names(db) == {} + finally: + db.close() + + +def test_wizard_after_first_admin(fresh, folder): + app, client = fresh() + assert client.get("/api/v1/auth/status").json() == {"setup_required": True, "wizard_pending": True} + assert client.get("/api/v1/setup").status_code == 401 + + code = app.state.archive.setup_code + r = client.post("/api/v1/auth/setup", json={"code": code, "email": "ada@x.io", "password": "admin password 1"}) + assert r.status_code == 200, r.text + h = {"Authorization": f"Bearer {r.json()['access_token']}"} + assert client.get("/api/v1/auth/status").json() == {"setup_required": False, "wizard_pending": True} + + view = client.get("/api/v1/setup", headers=h).json() + assert view["pending"] and not view["admin"]["from_env"] + assert view["namespace"] == {"existing": [], "locked": False} + assert view["llm"]["locked"] == [] and view["llm"]["values"]["api_key"] == {"secret": True, "set": False} + assert view["storage"]["local_roots"] == [str(folder / "inbox")] and view["storage"]["watches"] == 0 + + assert client.post("/api/v1/setup/namespace", json={"name": "Bad Name!"}, headers=h).status_code == 400 + assert client.post("/api/v1/setup/namespace", json={"name": "family", "graph": "isolated"}, headers=h).status_code == 200 + ns = client.get("/api/v1/namespaces", headers=h).json() + assert [(n["name"], n["graph"]) for n in ns] == [("family", "isolated")] + + r = client.put("/api/v1/setup/llm", json={"base_url": "http://ollama:11434/v1", "model": "llama3", "api_key": "sk-1"}, headers=h) + assert r.json()["saved"] == ["api_key", "base_url", "model"] + llm = client.get("/api/v1/setup", headers=h).json()["llm"]["values"] + assert llm["base_url"] == "http://ollama:11434/v1" and llm["model"] == "llama3" and llm["api_key"] == {"secret": True, "set": True} + # an empty key keeps the saved one + client.put("/api/v1/setup/llm", json={"base_url": "http://ollama:11434/v1", "model": "qwen3", "api_key": ""}, headers=h) + assert app.state.settings.current()["llm"]["api_key"] == "sk-1" + + (folder / "inbox" / "tapes").mkdir(parents=True) + bad = {"folder": "/etc", "namespace": "family"} + assert client.put("/api/v1/setup/storage", json=bad, headers=h).status_code == 400 + r = client.put( + "/api/v1/setup/storage", json={"max_upload_mb": 2048, "folder": str(folder / "inbox" / "tapes"), "namespace": "family"}, headers=h + ) + assert r.status_code == 200, r.text + assert r.json()["watch"] and client.get("/api/v1/setup", headers=h).json()["storage"] == { + **view["storage"], + "max_upload_mb": 2048, + "watches": 1, + } + + assert client.post("/api/v1/setup/finish", json={}, headers=h).status_code == 200 + assert client.get("/api/v1/auth/status").json()["wizard_pending"] is False + assert "setup.finish" in [e["action"] for e in client.get("/api/v1/audit", headers=h).json()] + + +def test_only_admins_use_the_wizard(fresh): + app, client = fresh() + make_user(app.state.db, "ada@x.io", "admin password 1", admin=True) + make_user(app.state.db, "ed@x.io", "editor password 1") + h = login(client, "ed@x.io", "editor password 1") + assert client.get("/api/v1/setup", headers=h).status_code == 403 + assert client.post("/api/v1/setup/finish", json={}, headers=h).status_code == 403 + + +def test_existing_installs_never_see_the_wizard(app, client): + # the shared fixture's archive starts with no accounts, so it is fresh; one that had accounts when it started isn't + assert client.get("/api/v1/auth/status").json()["wizard_pending"] is True + db = app.state.db + db.q("DELETE $r", r=store.R("setup", "wizard")) + make_user(db, "ada@x.io", "admin password 1", admin=True) + app.state.archive.prepare() + assert client.get("/api/v1/auth/status").json() == {"setup_required": False, "wizard_pending": False} + + +def test_environment_sets_and_locks(fresh, monkeypatch): + monkeypatch.setenv("LENS_ADMIN_EMAIL", "ops@x.io") + monkeypatch.setenv("LENS_ADMIN_PASSWORD", "ops password 123") + monkeypatch.setenv("LENS_NAMESPACE", "media") + monkeypatch.setenv("LENS_LLM_BASE_URL", "http://vllm:8000/v1") + monkeypatch.setenv("LENS_LLM_API_KEY", "sk-env") + app, client = fresh() + # the admin exists, so there is no setup code to find in the log; the wizard still runs for what's left + assert app.state.archive.setup_code is None + assert client.get("/api/v1/auth/status").json() == {"setup_required": False, "wizard_pending": True} + h = login(client, "ops@x.io", "ops password 123") + view = client.get("/api/v1/setup", headers=h).json() + assert view["admin"]["from_env"] and view["namespace"] == {"existing": ["media"], "locked": True} + assert sorted(view["llm"]["locked"]) == ["api_key", "base_url"] + assert view["llm"]["values"]["base_url"] == "http://vllm:8000/v1" + assert view["llm"]["values"]["api_key"] == {"secret": True, "set": True} # never the key itself + assert "sk-env" not in client.get("/api/v1/settings", headers=h).text + + assert client.post("/api/v1/setup/namespace", json={"name": "other"}, headers=h).status_code == 409 + r = client.put("/api/v1/setup/llm", json={"base_url": "http://elsewhere/v1", "model": "llama3", "api_key": "sk-x"}, headers=h) + assert r.json()["saved"] == ["model"] + cfg = app.state.settings.current()["llm"] + assert (cfg["base_url"], cfg["model"], cfg["api_key"]) == ("http://vllm:8000/v1", "llama3", "sk-env") + + +def test_wizard_off(fresh, monkeypatch): + monkeypatch.setenv("LENS_SETUP_WIZARD", "off") + _, client = fresh() + assert client.get("/api/v1/auth/status").json() == {"setup_required": True, "wizard_pending": False} diff --git a/nextjs-frontend/__tests__/setupAction.test.ts b/nextjs-frontend/__tests__/setupAction.test.ts index cea4e4258..39ba23ef1 100644 --- a/nextjs-frontend/__tests__/setupAction.test.ts +++ b/nextjs-frontend/__tests__/setupAction.test.ts @@ -42,7 +42,7 @@ describe("setup action", () => { expect(signIn).toHaveBeenCalledWith("credentials", { email: "ada@example.com", password: "long enough pw", - redirectTo: "/", + redirectTo: "/welcome", }); }); diff --git a/nextjs-frontend/__tests__/setupWizard.test.tsx b/nextjs-frontend/__tests__/setupWizard.test.tsx new file mode 100644 index 000000000..264b9a6b0 --- /dev/null +++ b/nextjs-frontend/__tests__/setupWizard.test.tsx @@ -0,0 +1,139 @@ +import { QueryClient, QueryClientProvider } from "@tanstack/react-query"; +import { fireEvent, render, screen, waitFor } from "@testing-library/react"; +import "@testing-library/jest-dom"; +import type { ReactNode } from "react"; + +import { Admin, Setup, type SetupView } from "@/app/openapi-client"; +import { SetupWizard } from "@/components/setup/setup-wizard"; +import { TooltipProvider } from "@/components/ui/tooltip"; + +jest.mock("@/app/openapi-client", () => ({ + Setup: { + getSetup: jest.fn(), + saveNamespace: jest.fn(), + saveLlm: jest.fn(), + saveStorage: jest.fn(), + finish: jest.fn(), + }, + Admin: { testLlm: jest.fn() }, +})); +jest.mock("next-auth/react", () => ({ useSession: () => ({ data: { accessToken: "t" } }) })); +const replace = jest.fn(); +jest.mock("next/navigation", () => ({ useRouter: () => ({ replace, refresh: jest.fn() }) })); +jest.mock("@/lib/hooks/session", () => ({ useArchive: () => ({ me: { user: { email: "ada@x.io" } } }) })); + +const ok = (data: unknown) => Promise.resolve({ data, response: { ok: true, status: 200 } }); +const m = (f: unknown) => f as jest.Mock; + +const VIEW = (over: Partial = {}): SetupView => ({ + pending: true, + admin: { from_env: false }, + namespace: { existing: [], locked: false }, + llm: { values: { base_url: null, model: null, api_key: { secret: true, set: false } }, locked: [] }, + storage: { + data_dir: "/data", + database: "surrealkv:///data/surrealdb", + embedded: true, + local_roots: ["/media"], + max_upload_mb: 4096, + watches: 0, + }, + ...over, +}); + +function wrap(ui: ReactNode) { + const qc = new QueryClient({ defaultOptions: { queries: { retry: false }, mutations: { retry: false } } }); + return render( + + {ui} + , + ); +} + +beforeEach(() => jest.clearAllMocks()); + +describe("SetupWizard", () => { + it("walks through namespace, model provider and storage, then finishes", async () => { + m(Setup.getSetup).mockImplementation(() => ok(VIEW())); + m(Setup.saveNamespace).mockImplementation(() => ok({ ok: true })); + m(Setup.saveLlm).mockImplementation(() => ok({ ok: true })); + m(Admin.testLlm).mockImplementation(() => ok({ ok: true, reply: "OK", ms: 120, model: "llama3" })); + m(Setup.saveStorage).mockImplementation(() => ok({ ok: true })); + m(Setup.finish).mockImplementation(() => ok({ ok: true })); + wrap(); + + const name = await screen.findByLabelText("Name"); + fireEvent.change(name, { target: { value: "Bad Name" } }); + expect(screen.getByRole("button", { name: "Create and continue" })).toBeDisabled(); + fireEvent.change(name, { target: { value: "family" } }); + fireEvent.click(screen.getByRole("button", { name: "Create and continue" })); + await waitFor(() => + expect(Setup.saveNamespace).toHaveBeenCalledWith( + expect.objectContaining({ body: { name: "family", graph: "shared" } }), + ), + ); + + fireEvent.change(await screen.findByLabelText("Base URL"), { target: { value: "http://localhost:11434/v1" } }); + fireEvent.change(screen.getByLabelText("Model"), { target: { value: "llama3" } }); + fireEvent.click(screen.getByRole("button", { name: "Test connection" })); + expect(await screen.findByText(/llama3 answered “OK”/)).toBeInTheDocument(); + fireEvent.click(screen.getByRole("button", { name: "Save and continue" })); + await waitFor(() => expect(m(Setup.saveLlm).mock.calls.length).toBe(2)); + expect(m(Setup.saveLlm).mock.calls[1][0].body).toEqual({ + base_url: "http://localhost:11434/v1", + model: "llama3", + api_key: null, + }); + + fireEvent.change(await screen.findByLabelText(/Largest upload/), { target: { value: "2048" } }); + fireEvent.click(screen.getByRole("button", { name: "Save and finish" })); + await waitFor(() => + expect(Setup.finish).toHaveBeenCalledWith(expect.objectContaining({ body: { skipped: false } })), + ); + expect(m(Setup.saveStorage).mock.calls[0][0].body).toEqual({ max_upload_mb: 2048, folder: null, namespace: null }); + await waitFor(() => expect(replace).toHaveBeenCalledWith("/")); + }); + + it("shows what .env sets as locked", async () => { + m(Setup.getSetup).mockImplementation(() => + ok( + VIEW({ + namespace: { existing: ["media"], locked: true }, + llm: { + values: { base_url: "http://vllm:8000/v1", model: null, api_key: { secret: true, set: true } }, + locked: ["base_url", "api_key"], + }, + }), + ), + ); + wrap(); + expect(await screen.findByText("media")).toBeInTheDocument(); + fireEvent.click(screen.getByRole("button", { name: "Continue" })); + const base = await screen.findByLabelText("Base URL"); + expect(base).toBeDisabled(); + expect(base).toHaveValue("http://vllm:8000/v1"); + expect(base).toHaveAccessibleDescription(/LENS_LLM_BASE_URL/); + expect(screen.getByLabelText(/API key/)).toBeDisabled(); + expect(screen.getByLabelText("Model")).toBeEnabled(); + }); + + it("counts a namespace seeded before the wizard as set up", async () => { + m(Setup.getSetup).mockImplementation(() => ok(VIEW({ namespace: { existing: ["media"], locked: false } }))); + wrap(); + expect(await screen.findByText(/already has one/)).toBeInTheDocument(); + expect(screen.queryByRole("button", { name: "Create and continue" })).not.toBeInTheDocument(); + fireEvent.click(screen.getByRole("button", { name: "Continue" })); + expect(await screen.findByLabelText("Base URL")).toBeInTheDocument(); + expect(Setup.saveNamespace).not.toHaveBeenCalled(); + }); + + it("can skip the whole wizard", async () => { + m(Setup.getSetup).mockImplementation(() => ok(VIEW())); + m(Setup.finish).mockImplementation(() => ok({ ok: true })); + wrap(); + fireEvent.click(await screen.findByRole("button", { name: "Skip setup" })); + await waitFor(() => + expect(Setup.finish).toHaveBeenCalledWith(expect.objectContaining({ body: { skipped: true } })), + ); + }); +}); diff --git a/nextjs-frontend/app/(app)/layout.tsx b/nextjs-frontend/app/(app)/layout.tsx index e18c6f4e5..a90563d63 100644 --- a/nextjs-frontend/app/(app)/layout.tsx +++ b/nextjs-frontend/app/(app)/layout.tsx @@ -5,11 +5,14 @@ import { auth } from "@/auth"; import { AppShell } from "@/components/app-shell/app-shell"; import { SessionGuard } from "@/components/app-shell/session-guard"; import { AppProviders } from "@/components/providers"; +import { isWizardPending } from "@/lib/auth/status"; /** Every page in this group requires a session (proxy.ts also enforces it). */ export default async function AppLayout({ children }: { children: React.ReactNode }) { const session = await auth(); if (!session || session.error) redirect("/login"); + // A fresh install: the first admin finishes (or skips) the setup wizard before the app opens. + if (session.user?.admin && (await isWizardPending())) redirect("/welcome"); return ( // Polling keeps the access token fresh for client-side calls (e.g. SSE streams). diff --git a/nextjs-frontend/app/(setup)/layout.tsx b/nextjs-frontend/app/(setup)/layout.tsx new file mode 100644 index 000000000..7a56db9f2 --- /dev/null +++ b/nextjs-frontend/app/(setup)/layout.tsx @@ -0,0 +1,23 @@ +import { redirect } from "next/navigation"; +import { SessionProvider } from "next-auth/react"; + +import { auth } from "@/auth"; +import { SessionGuard } from "@/components/app-shell/session-guard"; +import { AppProviders } from "@/components/providers"; + +/** The first-run wizard: signed in, with the app's providers, but no app shell around it. */ +export default async function SetupLayout({ children }: { children: React.ReactNode }) { + const session = await auth(); + if (!session || session.error) redirect("/login"); + + return ( + + + +
+
{children}
+
+
+
+ ); +} diff --git a/nextjs-frontend/app/(setup)/welcome/page.tsx b/nextjs-frontend/app/(setup)/welcome/page.tsx new file mode 100644 index 000000000..78064f0ed --- /dev/null +++ b/nextjs-frontend/app/(setup)/welcome/page.tsx @@ -0,0 +1,16 @@ +import type { Metadata } from "next"; +import { redirect } from "next/navigation"; + +import { auth } from "@/auth"; +import { SetupWizard } from "@/components/setup/setup-wizard"; +import { isWizardPending } from "@/lib/auth/status"; + +export const metadata: Metadata = { title: "Set up Lens" }; +export const dynamic = "force-dynamic"; + +/** The first-run setup wizard (admins of a fresh install): namespace, model provider, storage. */ +export default async function WelcomePage() { + const session = await auth(); + if (!session?.user?.admin || !(await isWizardPending())) redirect("/"); + return ; +} diff --git a/nextjs-frontend/app/openapi-client/sdk.gen.ts b/nextjs-frontend/app/openapi-client/sdk.gen.ts index 7118e928c..c471bd843 100644 --- a/nextjs-frontend/app/openapi-client/sdk.gen.ts +++ b/nextjs-frontend/app/openapi-client/sdk.gen.ts @@ -73,6 +73,20 @@ import type { GetHealthResponses, ReindexSearchData, ReindexSearchResponses, + GetSetupData, + GetSetupResponses, + SaveNamespaceData, + SaveNamespaceResponses, + SaveNamespaceErrors, + SaveLlmData, + SaveLlmResponses, + SaveLlmErrors, + SaveStorageData, + SaveStorageResponses, + SaveStorageErrors, + FinishData, + FinishResponses, + FinishErrors, ListNamespacesData, ListNamespacesResponses, CreateNamespaceData, @@ -737,7 +751,8 @@ export type Options(options?: Options) { return (options?.client ?? client).get({ @@ -1100,6 +1115,79 @@ export class Admin { } } +export class Setup { + /** + * Get Setup + * What is set already, and which fields .env or archive.yaml locks. + */ + public static getSetup(options?: Options) { + return (options?.client ?? client).get({ + url: "/api/v1/setup", + ...options, + }); + } + + /** + * Save Namespace + * Create the first namespace (or set the graph mode of one that exists). + */ + public static saveNamespace(options: Options) { + return (options.client ?? client).post({ + url: "/api/v1/setup/namespace", + ...options, + headers: { + "Content-Type": "application/json", + ...options.headers, + }, + }); + } + + /** + * Save Llm + * The model provider: an OpenAI-compatible server's address, the model, and its key (empty: unchanged). + */ + public static saveLlm(options: Options) { + return (options.client ?? client).put({ + url: "/api/v1/setup/llm", + ...options, + headers: { + "Content-Type": "application/json", + ...options.headers, + }, + }); + } + + /** + * Save Storage + * The upload limit, and optionally a folder on this machine (inside sources.local_roots) to watch. + */ + public static saveStorage(options: Options) { + return (options.client ?? client).put({ + url: "/api/v1/setup/storage", + ...options, + headers: { + "Content-Type": "application/json", + ...options.headers, + }, + }); + } + + /** + * Finish + * Finish (or skip) the wizard; the web app stops showing it. Everything stays changeable in Settings. + */ + public static finish(options: Options) { + return (options.client ?? client).post({ + url: "/api/v1/setup/finish", + ...options, + headers: { + "Content-Type": "application/json", + ...options.headers, + }, + }); + } +} + export class Namespaces { /** * List Namespaces diff --git a/nextjs-frontend/app/openapi-client/types.gen.ts b/nextjs-frontend/app/openapi-client/types.gen.ts index 460fa2c7e..b5bd6a942 100644 --- a/nextjs-frontend/app/openapi-client/types.gen.ts +++ b/nextjs-frontend/app/openapi-client/types.gen.ts @@ -356,7 +356,11 @@ export type AuthStatus = { * Setup Required */ setup_required: boolean; - [key: string]: unknown | boolean; + /** + * Wizard Pending + */ + wizard_pending?: boolean; + [key: string]: unknown | boolean | undefined; }; /** @@ -7517,6 +7521,96 @@ export type SegmentUpdate = { speaker?: number | null; }; +/** + * SetupAdmin + */ +export type SetupAdmin = { + /** + * From Env + */ + from_env: boolean; + [key: string]: unknown | boolean; +}; + +/** + * SetupFinish + */ +export type SetupFinish = { + /** + * Skipped + */ + skipped?: boolean; +}; + +/** + * SetupLlm + */ +export type SetupLlm = { + /** + * Base Url + */ + base_url?: string | null; + /** + * Model + */ + model?: string | null; + /** + * Api Key + */ + api_key?: string | null; +}; + +/** + * SetupLlmView + */ +export type SetupLlmView = { + /** + * Values + */ + values: { + [key: string]: unknown; + }; + /** + * Locked + */ + locked: Array; + [key: string]: + | unknown + | { + [key: string]: unknown; + } + | Array; +}; + +/** + * SetupNamespace + */ +export type SetupNamespace = { + /** + * Name + */ + name: string; + /** + * Graph + */ + graph?: "shared" | "isolated"; +}; + +/** + * SetupNamespaceView + */ +export type SetupNamespaceView = { + /** + * Existing + */ + existing: Array; + /** + * Locked + */ + locked: boolean; + [key: string]: unknown | Array | boolean; +}; + /** * SetupRequest */ @@ -7539,6 +7633,89 @@ export type SetupRequest = { name?: string | null; }; +/** + * SetupSaved + */ +export type SetupSaved = { + /** + * Ok + */ + ok?: boolean; + /** + * Saved + */ + saved?: Array; + /** + * Watch + */ + watch?: number | null; + [key: string]: unknown | boolean | Array | number | null | undefined; +}; + +/** + * SetupStorage + */ +export type SetupStorage = { + /** + * Max Upload Mb + */ + max_upload_mb?: number | null; + /** + * Folder + */ + folder?: string | null; + /** + * Namespace + */ + namespace?: string | null; +}; + +/** + * SetupStorageView + */ +export type SetupStorageView = { + /** + * Data Dir + */ + data_dir: string; + /** + * Database + */ + database: string; + /** + * Embedded + */ + embedded: boolean; + /** + * Local Roots + */ + local_roots: Array; + /** + * Max Upload Mb + */ + max_upload_mb: number; + /** + * Watches + */ + watches: number; + [key: string]: unknown | string | boolean | Array | number; +}; + +/** + * SetupView + */ +export type SetupView = { + /** + * Pending + */ + pending: boolean; + admin: SetupAdmin; + namespace: SetupNamespaceView; + llm: SetupLlmView; + storage: SetupStorageView; + [key: string]: unknown | boolean | SetupAdmin | SetupNamespaceView | SetupLlmView | SetupStorageView; +}; + /** * Share */ @@ -10393,6 +10570,122 @@ export type ReindexSearchResponses = { export type ReindexSearchResponse = ReindexSearchResponses[keyof ReindexSearchResponses]; +export type GetSetupData = { + body?: never; + path?: never; + query?: never; + url: "/api/v1/setup"; +}; + +export type GetSetupResponses = { + /** + * Successful Response + */ + 200: SetupView; +}; + +export type GetSetupResponse = GetSetupResponses[keyof GetSetupResponses]; + +export type SaveNamespaceData = { + body: SetupNamespace; + path?: never; + query?: never; + url: "/api/v1/setup/namespace"; +}; + +export type SaveNamespaceErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type SaveNamespaceError = SaveNamespaceErrors[keyof SaveNamespaceErrors]; + +export type SaveNamespaceResponses = { + /** + * Successful Response + */ + 200: SetupSaved; +}; + +export type SaveNamespaceResponse = SaveNamespaceResponses[keyof SaveNamespaceResponses]; + +export type SaveLlmData = { + body: SetupLlm; + path?: never; + query?: never; + url: "/api/v1/setup/llm"; +}; + +export type SaveLlmErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type SaveLlmError = SaveLlmErrors[keyof SaveLlmErrors]; + +export type SaveLlmResponses = { + /** + * Successful Response + */ + 200: SetupSaved; +}; + +export type SaveLlmResponse = SaveLlmResponses[keyof SaveLlmResponses]; + +export type SaveStorageData = { + body: SetupStorage; + path?: never; + query?: never; + url: "/api/v1/setup/storage"; +}; + +export type SaveStorageErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type SaveStorageError = SaveStorageErrors[keyof SaveStorageErrors]; + +export type SaveStorageResponses = { + /** + * Successful Response + */ + 200: SetupSaved; +}; + +export type SaveStorageResponse = SaveStorageResponses[keyof SaveStorageResponses]; + +export type FinishData = { + body: SetupFinish; + path?: never; + query?: never; + url: "/api/v1/setup/finish"; +}; + +export type FinishErrors = { + /** + * Validation Error + */ + 422: HttpValidationError; +}; + +export type FinishError = FinishErrors[keyof FinishErrors]; + +export type FinishResponses = { + /** + * Successful Response + */ + 200: SetupSaved; +}; + +export type FinishResponse = FinishResponses[keyof FinishResponses]; + export type ListNamespacesData = { body?: never; path?: never; diff --git a/nextjs-frontend/components/actions/setup-action.ts b/nextjs-frontend/components/actions/setup-action.ts index e14b8b701..2740d33c1 100644 --- a/nextjs-frontend/components/actions/setup-action.ts +++ b/nextjs-frontend/components/actions/setup-action.ts @@ -25,7 +25,7 @@ function sentence(s: string): string { return t ? t[0].toUpperCase() + t.slice(1) + (/[.!?]$/.test(t) ? "" : ".") : t; } -/** Creates the first admin with the one-time code from the server log, then signs in. */ +/** Creates the first admin with the one-time code from the server log, signs in, and opens the setup wizard. */ export async function setup(_prev: FormState, formData: FormData): Promise { const validated = setupSchema.safeParse({ code: formData.get("code") ?? "", @@ -55,6 +55,6 @@ export async function setup(_prev: FormState, formData: FormData): Promise = { "server.allowed_hosts": "ARCHIVE_ALLOWED_HOSTS", + "llm.base_url": "LENS_LLM_BASE_URL", + "llm.model": "LENS_LLM_MODEL", + "llm.api_key": "LENS_LLM_API_KEY", + "llm.vision_model": "LENS_LLM_VISION_MODEL", }; const CONFIRM_BASE = "CHANGE ALL IDENTIFIERS"; diff --git a/nextjs-frontend/components/setup/setup-wizard.tsx b/nextjs-frontend/components/setup/setup-wizard.tsx new file mode 100644 index 000000000..4538bfbdd --- /dev/null +++ b/nextjs-frontend/components/setup/setup-wizard.tsx @@ -0,0 +1,525 @@ +"use client"; + +import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query"; +import { Check, Lock } from "lucide-react"; +import { useRouter } from "next/navigation"; +import { useEffect, useState, type ReactNode } from "react"; + +import { Admin, Setup, type LlmTestResult, type SetupView } from "@/app/openapi-client"; +import { AuthAlert, AuthBrand } from "@/components/auth/auth-card"; +import { SegmentedChoice } from "@/components/settings/controls"; +import { Button } from "@/components/ui/button"; +import { Field, Input } from "@/components/ui/field"; +import { Skeleton } from "@/components/ui/states"; +import { ApiError, data, useApiClient } from "@/lib/api/browser"; +import { useArchive } from "@/lib/hooks/session"; +import { cn } from "@/lib/utils"; + +const STEPS = [ + { id: "admin", label: "Admin account" }, + { id: "namespace", label: "Namespace" }, + { id: "llm", label: "Model provider" }, + { id: "storage", label: "Storage" }, +] as const; +type StepId = (typeof STEPS)[number]["id"]; + +/** The .env variable that sets each locked field (fastapi_backend/app/domain/settings.py, ENV_OVERRIDES). */ +const LLM_ENV: Record = { + base_url: "LENS_LLM_BASE_URL", + model: "LENS_LLM_MODEL", + api_key: "LENS_LLM_API_KEY", +}; +const NS = /^[a-z0-9][a-z0-9_-]{0,40}$/; + +function errorText(e: unknown): string { + return e instanceof ApiError ? e.message : "Something went wrong. Please try again."; +} + +/** + * First-run setup for a fresh install (the admin already exists): the first namespace, the model provider and + * storage, one step at a time. Each step can be skipped, and the whole wizard too; everything stays in Settings. + * Fields .env sets are shown locked, since the environment wins. + */ +export function SetupWizard() { + const client = useApiClient(); + const router = useRouter(); + const queryClient = useQueryClient(); + const { me } = useArchive(); + const view = useQuery({ + queryKey: ["setup"], + queryFn: () => data(Setup.getSetup({ client })), + }); + const [step, setStep] = useState("namespace"); + const [done, setDone] = useState>(new Set(["admin"])); + // A namespace seeded before the wizard (archive.yaml, LENS_NAMESPACE, an install script) counts as set up. + const seeded = Boolean(view.data?.namespace.existing.length); + useEffect(() => { + if (seeded) setDone((d) => (d.has("namespace") ? d : new Set(d).add("namespace"))); + }, [seeded]); + + const finish = useMutation({ + mutationFn: (skipped: boolean) => data(Setup.finish({ client, body: { skipped } })), + onSuccess: () => { + queryClient.invalidateQueries(); + router.replace("/"); + router.refresh(); + }, + }); + + const next = (from: StepId, saved: boolean) => { + if (saved) setDone((d) => new Set(d).add(from)); + queryClient.invalidateQueries({ queryKey: ["setup"] }); + const i = STEPS.findIndex((s) => s.id === from); + if (i === STEPS.length - 1) finish.mutate(false); + else setStep(STEPS[i + 1].id); + }; + + return ( +
+
+ + +
+
+

Welcome to Lens

+

+ A few choices get this server ready. Each step can be skipped and changed later in Settings; values set in the + server's .env are shown locked. +

+
+ +
    + {STEPS.map((s, i) => { + const on = s.id === step; + const ok = done.has(s.id); + return ( +
  1. + +
  2. + ); + })} +
+ +
+ {view.isPending ? ( + + ) : view.error ? ( + {errorText(view.error)} + ) : step === "namespace" ? ( + next("namespace", saved)} /> + ) : step === "llm" ? ( + next("llm", saved)} /> + ) : ( + next("storage", saved)} /> + )} + {finish.error && {errorText(finish.error)}} +
+ +

+ Signed in as {me?.user.email ?? "the first admin"} + {view.data?.admin.from_env ? " (created from LENS_ADMIN_EMAIL in .env)" : ""}. +

+
+ ); +} + +function StepHead({ title, children }: { title: string; children: ReactNode }) { + return ( +
+

{title}

+

{children}

+
+ ); +} + +function Actions({ + onSkip, + onSave, + saveText = "Save and continue", + pending, + disabled, +}: { + onSkip: () => void; + onSave?: () => void; + saveText?: string; + pending?: boolean; + disabled?: boolean; +}) { + return ( +
+ + {onSave && ( + + )} +
+ ); +} + +function LockedHint({ env }: { env: string }) { + return ( + + Set by {env} in .env + + ); +} + +function NamespaceStep({ view, onNext }: { view: SetupView; onNext: (saved: boolean) => void }) { + const client = useApiClient(); + const ns = view.namespace; + const [name, setName] = useState("archive"); + const [graph, setGraph] = useState("shared"); + const save = useMutation({ + mutationFn: () => data(Setup.saveNamespace({ client, body: { name: name.trim(), graph: graph as "shared" } })), + onSuccess: () => onNext(true), + }); + const valid = NS.test(name.trim()); + + if (ns.locked || ns.existing.length > 0) + return ( + <> + + Namespaces keep recordings, speakers and people's access apart.{" "} + {ns.locked ? ( + <> + This server's are set in archive.yaml or LENS_NAMESPACE, so there + is nothing to choose here. + + ) : ( + "This server already has one, so you're set. Add more any time under Admin → Namespaces." + )} + +
    + {ns.existing.map((n) => ( +
  • + {n} +
  • + ))} +
+
+ +
+ + ); + + return ( + <> + + A namespace holds a set of recordings, documents and images, with its own people and access. You can add more + later. + + + {({ id, describedBy, invalid }) => ( + setName(e.target.value.toLowerCase())} + autoComplete="off" + spellCheck={false} + /> + )} + + + {() => ( + + )} + + {save.error && {errorText(save.error)}} + onNext(false)} + onSave={() => save.mutate()} + saveText="Create and continue" + pending={save.isPending} + disabled={!valid} + /> + + ); +} + +function LlmStep({ view, onNext }: { view: SetupView; onNext: (saved: boolean) => void }) { + const client = useApiClient(); + const v = view.llm.values as { base_url?: string | null; model?: string | null; api_key?: { set?: boolean } }; + const locked = new Set(view.llm.locked); + const [baseUrl, setBaseUrl] = useState(v.base_url ?? ""); + const [model, setModel] = useState(v.model ?? ""); + const [apiKey, setApiKey] = useState(""); + const [tested, setTested] = useState(null); + useEffect(() => setTested(null), [baseUrl, model, apiKey]); + + const body = () => ({ base_url: baseUrl, model, api_key: apiKey || null }); + const save = useMutation({ mutationFn: () => data(Setup.saveLlm({ client, body: body() })) }); + const test = useMutation({ + mutationFn: async () => { + await data(Setup.saveLlm({ client, body: body() })); + return data(Admin.testLlm({ client })); + }, + onSuccess: setTested, + }); + const allLocked = ["base_url", "model", "api_key"].every((k) => locked.has(k)); + + const field = ( + key: "base_url" | "model", + label: string, + value: string, + set: (s: string) => void, + hint: ReactNode, + ) => ( + : hint}> + {({ id, describedBy }) => ( + set(e.target.value)} + disabled={locked.has(key)} + autoComplete="off" + spellCheck={false} + /> + )} + + ); + + return ( + <> + + Summaries, chat and descriptions use any OpenAI-compatible server: OpenAI, or one you run yourself such as + Ollama, llama.cpp, LM Studio or vLLM. Transcription runs on this server and needs none. + + {field("base_url", "Base URL", baseUrl, setBaseUrl, "For example http://localhost:11434/v1 (Ollama)")} + {field("model", "Model", model, setModel, "The model's name on that server, for example llama3.1")} + + ) : v.api_key?.set ? ( + "A key is saved; leave this empty to keep it" + ) : ( + "Local servers usually need none. Stored encrypted and never shown again." + ) + } + > + {({ id, describedBy }) => ( + setApiKey(e.target.value)} + disabled={locked.has("api_key")} + autoComplete="off" + /> + )} + + {tested && + (tested.ok ? ( + + {tested.model} answered “{tested.reply}” in {tested.ms} ms. + + ) : ( + The model didn't answer: {tested.error} + ))} + {(save.error || test.error) && {errorText(save.error || test.error)}} +
+ +
+ + +
+
+ + ); +} + +function StorageStep({ + view, + pending, + onNext, +}: { + view: SetupView; + pending: boolean; + onNext: (saved: boolean) => void; +}) { + const client = useApiClient(); + const s = view.storage; + const [maxMb, setMaxMb] = useState(String(s.max_upload_mb)); + const [folder, setFolder] = useState(""); + const [namespace, setNamespace] = useState(view.namespace.existing[0] ?? ""); + const save = useMutation({ + mutationFn: () => + data( + Setup.saveStorage({ + client, + body: { + max_upload_mb: Number(maxMb), + folder: folder.trim() || null, + namespace: folder.trim() ? namespace : null, + }, + }), + ), + onSuccess: () => onNext(true), + }); + const mb = Number(maxMb); + const validMb = Number.isInteger(mb) && mb >= 1 && mb <= 1_000_000; + + return ( + <> + + Where this server keeps its data, how large an upload may be, and optionally a folder on this machine to import + from as files arrive. + +
+
Data folder
+
{s.data_dir}
+
Database
+
+ {s.embedded ? "embedded, in the data folder" : s.database} +
+
+

+ These are set where the server starts (archive.yaml,{" "} + SURREAL_URL in .env), so the web app can't move them. +

+ + {({ id, describedBy, invalid }) => ( + setMaxMb(e.target.value.replace(/[^0-9]/g, ""))} + className="max-w-[200px]" + /> + )} + + {s.local_roots.length > 0 ? ( + <> + + New files there are imported. It must be inside{" "} + {s.local_roots.map((r, i) => ( + + {i > 0 && ", "} + {r} + + ))} + . + + } + > + {({ id, describedBy }) => ( + setFolder(e.target.value)} + autoComplete="off" + spellCheck={false} + /> + )} + + {folder.trim() && view.namespace.existing.length > 1 && ( + + {() => ( + ({ value: n, label: n }))} + /> + )} + + )} + {folder.trim() && view.namespace.existing.length === 0 && ( + Create a namespace first (step 2) to watch a folder. + )} + + ) : ( +

+ To watch folders on this machine, list them under sources.local_roots in + archive.yaml. Cloud storage (S3, Drive, Dropbox, SFTP…) can be added later under Sources. +

+ )} + {save.error && {errorText(save.error)}} + onNext(false)} + onSave={() => save.mutate()} + saveText="Save and finish" + pending={save.isPending || pending} + disabled={!validMb || (Boolean(folder.trim()) && !namespace)} + /> + + ); +} diff --git a/nextjs-frontend/lib/auth/status.ts b/nextjs-frontend/lib/auth/status.ts index 537d92e02..d8152c883 100644 --- a/nextjs-frontend/lib/auth/status.ts +++ b/nextjs-frontend/lib/auth/status.ts @@ -1,12 +1,22 @@ import { Auth } from "@/app/openapi-client"; import { createApiClient } from "@/lib/api/client"; -/** Whether the archive still needs its first admin. False when the API can't be reached. */ -export async function isSetupRequired(): Promise { +async function status() { try { const { data } = await Auth.status({ client: createApiClient() }); - return data?.setup_required ?? false; + return data; } catch { - return false; + return undefined; } } + +/** Whether the archive still needs its first admin. False when the API can't be reached. */ +export async function isSetupRequired(): Promise { + return (await status())?.setup_required ?? false; +} + +/** Whether a fresh install's setup wizard is still to be finished (admins are taken to /welcome). False when the API + * can't be reached. */ +export async function isWizardPending(): Promise { + return (await status())?.wizard_pending ?? false; +} diff --git a/nextjs-frontend/openapi.json b/nextjs-frontend/openapi.json index ef168c22e..a705e34e7 100644 --- a/nextjs-frontend/openapi.json +++ b/nextjs-frontend/openapi.json @@ -11,7 +11,7 @@ "auth" ], "summary": "Status", - "description": "Whether the archive still needs its first admin (the sign-in page shows the setup form instead).", + "description": "Whether the archive still needs its first admin (the sign-in page shows the setup form instead), and whether\nthe first-run wizard is still to be finished (the web app takes admins there).", "operationId": "status", "responses": { "200": { @@ -989,6 +989,196 @@ } } }, + "/api/v1/setup": { + "get": { + "tags": [ + "setup" + ], + "summary": "Get Setup", + "description": "What is set already, and which fields .env or archive.yaml locks.", + "operationId": "get_setup", + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SetupView" + } + } + } + } + } + } + }, + "/api/v1/setup/namespace": { + "post": { + "tags": [ + "setup" + ], + "summary": "Save Namespace", + "description": "Create the first namespace (or set the graph mode of one that exists).", + "operationId": "save_namespace", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SetupNamespace" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SetupSaved" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/v1/setup/llm": { + "put": { + "tags": [ + "setup" + ], + "summary": "Save Llm", + "description": "The model provider: an OpenAI-compatible server's address, the model, and its key (empty: unchanged).", + "operationId": "save_llm", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SetupLlm" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SetupSaved" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/v1/setup/storage": { + "put": { + "tags": [ + "setup" + ], + "summary": "Save Storage", + "description": "The upload limit, and optionally a folder on this machine (inside sources.local_roots) to watch.", + "operationId": "save_storage", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SetupStorage" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SetupSaved" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, + "/api/v1/setup/finish": { + "post": { + "tags": [ + "setup" + ], + "summary": "Finish", + "description": "Finish (or skip) the wizard; the web app stops showing it. Everything stays changeable in Settings.", + "operationId": "finish", + "requestBody": { + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SetupFinish" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "Successful Response", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/SetupSaved" + } + } + } + }, + "422": { + "description": "Validation Error", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/HTTPValidationError" + } + } + } + } + } + } + }, "/api/v1/namespaces": { "get": { "tags": [ @@ -13134,6 +13324,11 @@ "setup_required": { "type": "boolean", "title": "Setup Required" + }, + "wizard_pending": { + "type": "boolean", + "title": "Wizard Pending", + "default": false } }, "additionalProperties": true, @@ -24268,6 +24463,145 @@ "title": "SegmentUpdate", "description": "Send ``text``, ``speaker`` (a speaker id in the same namespace, or null), or both." }, + "SetupAdmin": { + "properties": { + "from_env": { + "type": "boolean", + "title": "From Env" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "from_env" + ], + "title": "SetupAdmin" + }, + "SetupFinish": { + "properties": { + "skipped": { + "type": "boolean", + "title": "Skipped", + "default": false + } + }, + "additionalProperties": false, + "type": "object", + "title": "SetupFinish" + }, + "SetupLlm": { + "properties": { + "base_url": { + "anyOf": [ + { + "type": "string", + "maxLength": 500 + }, + { + "type": "null" + } + ], + "title": "Base Url" + }, + "model": { + "anyOf": [ + { + "type": "string", + "maxLength": 200 + }, + { + "type": "null" + } + ], + "title": "Model" + }, + "api_key": { + "anyOf": [ + { + "type": "string", + "maxLength": 2000 + }, + { + "type": "null" + } + ], + "title": "Api Key" + } + }, + "additionalProperties": false, + "type": "object", + "title": "SetupLlm" + }, + "SetupLlmView": { + "properties": { + "values": { + "additionalProperties": true, + "type": "object", + "title": "Values" + }, + "locked": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Locked" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "values", + "locked" + ], + "title": "SetupLlmView" + }, + "SetupNamespace": { + "properties": { + "name": { + "type": "string", + "maxLength": 41, + "minLength": 1, + "title": "Name" + }, + "graph": { + "type": "string", + "enum": [ + "shared", + "isolated" + ], + "title": "Graph", + "default": "shared" + } + }, + "additionalProperties": false, + "type": "object", + "required": [ + "name" + ], + "title": "SetupNamespace" + }, + "SetupNamespaceView": { + "properties": { + "existing": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Existing" + }, + "locked": { + "type": "boolean", + "title": "Locked" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "existing", + "locked" + ], + "title": "SetupNamespaceView" + }, "SetupRequest": { "properties": { "code": { @@ -24303,6 +24637,150 @@ ], "title": "SetupRequest" }, + "SetupSaved": { + "properties": { + "ok": { + "type": "boolean", + "title": "Ok", + "default": true + }, + "saved": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Saved", + "default": [] + }, + "watch": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Watch" + } + }, + "additionalProperties": true, + "type": "object", + "title": "SetupSaved" + }, + "SetupStorage": { + "properties": { + "max_upload_mb": { + "anyOf": [ + { + "type": "integer" + }, + { + "type": "null" + } + ], + "title": "Max Upload Mb" + }, + "folder": { + "anyOf": [ + { + "type": "string", + "maxLength": 4096 + }, + { + "type": "null" + } + ], + "title": "Folder" + }, + "namespace": { + "anyOf": [ + { + "type": "string" + }, + { + "type": "null" + } + ], + "title": "Namespace" + } + }, + "additionalProperties": false, + "type": "object", + "title": "SetupStorage" + }, + "SetupStorageView": { + "properties": { + "data_dir": { + "type": "string", + "title": "Data Dir" + }, + "database": { + "type": "string", + "title": "Database" + }, + "embedded": { + "type": "boolean", + "title": "Embedded" + }, + "local_roots": { + "items": { + "type": "string" + }, + "type": "array", + "title": "Local Roots" + }, + "max_upload_mb": { + "type": "integer", + "title": "Max Upload Mb" + }, + "watches": { + "type": "integer", + "title": "Watches" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "data_dir", + "database", + "embedded", + "local_roots", + "max_upload_mb", + "watches" + ], + "title": "SetupStorageView" + }, + "SetupView": { + "properties": { + "pending": { + "type": "boolean", + "title": "Pending" + }, + "admin": { + "$ref": "#/components/schemas/SetupAdmin" + }, + "namespace": { + "$ref": "#/components/schemas/SetupNamespaceView" + }, + "llm": { + "$ref": "#/components/schemas/SetupLlmView" + }, + "storage": { + "$ref": "#/components/schemas/SetupStorageView" + } + }, + "additionalProperties": true, + "type": "object", + "required": [ + "pending", + "admin", + "namespace", + "llm", + "storage" + ], + "title": "SetupView" + }, "Share": { "properties": { "id": { From 0bb9a82f0256745acfbda35747acf9f2b04a895d Mon Sep 17 00:00:00 2001 From: Adeel Ahmad Date: Fri, 2 Oct 2026 12:49:42 +0000 Subject: [PATCH 2/2] Pass the first-run variables through docker-compose.prod.yml; LENS_NAMESPACE only while there is none The prod stack lists its environment explicitly, so LENS_ADMIN_*, LENS_NAMESPACE, LENS_LLM_*, LENS_SETUP_WIZARD and LENS_SETUP_CODE never reached the backend and worker. LENS_NAMESPACE no longer re-creates a namespace deleted later. Co-Authored-By: Claude Opus 5.5 (1M context) Claude-Session: https://claude.ai/code/session_01WjEWJZ9XYFxL19mNfXgfPK --- docker-compose.prod.yml | 11 +++++++++++ docs/configuration.md | 2 +- fastapi_backend/app/domain/setup.py | 7 ++++--- fastapi_backend/tests/api/test_setup.py | 11 +++++++++++ 4 files changed, 27 insertions(+), 4 deletions(-) diff --git a/docker-compose.prod.yml b/docker-compose.prod.yml index f3ecb000c..8501714d7 100644 --- a/docker-compose.prod.yml +++ b/docker-compose.prod.yml @@ -23,6 +23,17 @@ x-backend: &backend MAIL_USERNAME: ${MAIL_USERNAME:-} MAIL_PASSWORD: ${MAIL_PASSWORD:-} MAIL_FROM: ${MAIL_FROM:-} + # first run (docs/configuration.md#first-run-setup): unset, the web app's setup wizard asks + LENS_SETUP_CODE: ${LENS_SETUP_CODE:-} + LENS_SETUP_WIZARD: ${LENS_SETUP_WIZARD:-} + LENS_ADMIN_EMAIL: ${LENS_ADMIN_EMAIL:-} + LENS_ADMIN_PASSWORD: ${LENS_ADMIN_PASSWORD:-} + LENS_ADMIN_NAME: ${LENS_ADMIN_NAME:-} + LENS_NAMESPACE: ${LENS_NAMESPACE:-} + LENS_LLM_BASE_URL: ${LENS_LLM_BASE_URL:-} + LENS_LLM_MODEL: ${LENS_LLM_MODEL:-} + LENS_LLM_API_KEY: ${LENS_LLM_API_KEY:-} + LENS_LLM_VISION_MODEL: ${LENS_LLM_VISION_MODEL:-} volumes: - archive-data:/data - ${AUDIO_DIR:-./local-audio}:/audio:ro diff --git a/docs/configuration.md b/docs/configuration.md index 2b5113e64..2bcade252 100644 --- a/docs/configuration.md +++ b/docs/configuration.md @@ -28,7 +28,7 @@ with AES-GCM and are write-only: the API reports whether one is set, never its v | `RUN_BACKGROUND` | follows `workers.inline` | run job workers and folder watching inside the API process | | `LENS_SETUP_CODE` | random | fix the first-run setup code (automation) | | `LENS_ADMIN_EMAIL` / `LENS_ADMIN_PASSWORD` / `LENS_ADMIN_NAME` | | create the first admin at startup, with no setup code ([First-run setup](#first-run-setup)) | -| `LENS_NAMESPACE` | | create the first namespace at startup | +| `LENS_NAMESPACE` | | create the first namespace at startup, while there is none | | `LENS_LLM_BASE_URL` / `LENS_LLM_MODEL` / `LENS_LLM_API_KEY` / `LENS_LLM_VISION_MODEL` | | the model provider; wins over Settings, which show these locked | | `LENS_SETUP_WIZARD` | | `off`: never show the setup wizard | | `FRONTEND_URL` | `http://localhost:3000` | links in emails | diff --git a/fastapi_backend/app/domain/setup.py b/fastapi_backend/app/domain/setup.py index 9edffde73..53e20a9d6 100644 --- a/fastapi_backend/app/domain/setup.py +++ b/fastapi_backend/app/domain/setup.py @@ -6,7 +6,7 @@ shows those fields locked. LENS_ADMIN_EMAIL, LENS_ADMIN_PASSWORD, LENS_ADMIN_NAME the first admin, created at startup (no setup code needed) - LENS_NAMESPACE the first namespace, created at startup + LENS_NAMESPACE the first namespace, created at startup while there is none LENS_LLM_BASE_URL, LENS_LLM_MODEL, LENS_LLM_API_KEY the model provider (settings.ENV_OVERRIDES) LENS_SETUP_WIZARD=off never show the wizard (everything comes from .env) @@ -57,7 +57,8 @@ def env_namespace(): def apply_env(db): - """Create what the environment names and doesn't exist yet: the first admin, the first namespace.""" + """Create what the environment names while the archive has none: the first admin, the first namespace. Only then, + so one deleted later doesn't come back on the next start.""" admin = env_admin() if admin and auth.account_count(db) == 0: try: @@ -68,7 +69,7 @@ def apply_env(db): auth.audit(db, {"id": uid, "email": admin[0]}, "setup", detail=["environment"]) log.info("Created the first admin %s from the environment", admin[0]) name = env_namespace() - if name: + if name and not store.space_names(db): if not store.NS_RX.match(name): log.error("LENS_NAMESPACE %r: namespace names use lowercase letters, digits, - and _", name) else: diff --git a/fastapi_backend/tests/api/test_setup.py b/fastapi_backend/tests/api/test_setup.py index 5f5e1770d..faa38274e 100644 --- a/fastapi_backend/tests/api/test_setup.py +++ b/fastapi_backend/tests/api/test_setup.py @@ -158,6 +158,17 @@ def test_environment_sets_and_locks(fresh, monkeypatch): assert (cfg["base_url"], cfg["model"], cfg["api_key"]) == ("http://vllm:8000/v1", "llama3", "sk-env") +def test_env_namespace_only_while_there_is_none(fresh, monkeypatch): + from app.domain import setup + + app, _ = fresh() + db = app.state.db + store.ns_id(db, "family") + monkeypatch.setenv("LENS_NAMESPACE", "media") + setup.apply_env(db) # the next start: a namespace exists, so LENS_NAMESPACE adds nothing + assert sorted(store.space_names(db).values()) == ["family"] + + def test_wizard_off(fresh, monkeypatch): monkeypatch.setenv("LENS_SETUP_WIZARD", "off") _, client = fresh()