Repository navigation
feat(setup): first-run setup wizard answered by .env, and startup on a fresh database - #19
Merged
Merged
Conversation
…artup 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) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WjEWJZ9XYFxL19mNfXgfPK
…MESPACE 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) <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01WjEWJZ9XYFxL19mNfXgfPK
This was referenced Oct 2, 2026
adeelahmad
marked this pull request as ready for review
October 2, 2026 13:07
4 of 8 tasks
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Requested by Adeel · project thread
Description
Before: a fresh install only asked for the first admin (with the setup code from the log). The namespace, model provider and storage had to be found in archive.yaml or Settings. If archive.yaml had no namespaces, the API failed to start on SurrealDB 3 with "table 'seq' does not exist".
After: once the first admin exists, the web app walks them through a short wizard at
/welcome. It covers the namespace, the model provider (with a connection test) and storage (where data lives, the largest upload, and an optional folder insidesources.local_rootsto watch). Every step can be skipped, and so can the whole wizard..envcan answer it instead. Values from the environment win, and the wizard and Settings show them locked. A fresh database with no namespaces now starts.How
app/domain/setup.py: when the API first starts with no accounts, it writes asetup:wizardmarker. Installs that already had accounts never see the wizard. At startup it also appliesLENS_ADMIN_EMAIL/LENS_ADMIN_PASSWORD/LENS_ADMIN_NAMEandLENS_NAMESPACE.LENS_SETUP_WIZARD=offturns the wizard off.settings.ENV_OVERRIDESnow also coversLENS_LLM_BASE_URL/_MODEL/_API_KEY/_VISION_MODEL, and these win over saved settings. A key from the environment is masked in every view./api/v1/setup(GET,POST /namespace,PUT /llm,PUT /storage,POST /finish).GET /auth/statusgainswizard_pending.(setup)/welcomepage andcomponents/setup/setup-wizard.tsx. Admins are redirected there from the app layout while the wizard is pending. The setup form now lands on/welcomeafter creating the admin.DEFINE TABLE IF NOT EXISTS seqis now part of the schema. I reproduced the failure against a real SurrealDB 3.2.4 server, then confirmed the fix on the same server.Motivation and Context
Frictionless first run from the browser, alongside
.envconfiguration for automated installs.Notes for the packaging PRs (#10 Proxmox, #11 Synology, #12 Cloudron, #13 QNAP)
Nothing breaks. They keep the same setup-code mechanism (
LENS_SETUP_CODE, the log line,/setup), and after the admin is created the user lands in the wizard. Optional follow-ups once this merges:medianamespace is no longer needed to get around the 'seq' bug. Keeping it is fine, because a namespace that already exists counts as set up and the wizard just shows it. Dropping it lets the user pick the name.LENS_ADMIN_EMAIL/LENS_ADMIN_PASSWORD(no setup code),LENS_NAMESPACE,LENS_LLM_*, andLENS_SETUP_WIZARD=off.Screenshots (if appropriate):
Driven end to end in Chromium against a fresh embedded database: setup code → admin → namespace → model provider → storage → home. Screenshots are in the project thread.
Steps to reproduce (if appropriate):
Start with an empty data folder and an archive.yaml with no namespaces, open the web app, and create the admin with the setup code.
Types of changes
Checklist:
Tests:
tests/api/test_setup.py(6 tests, passing on in-memory and on a SurrealDB 3.2.4 server) and__tests__/setupWizard.test.tsx(4 tests). The full backend suite passes excepttest_office_and_text_files_become_documents, which fails because LibreOffice can't load the file in this container. That test is unrelated to this change. All 503 frontend tests pass. ruff, mypy, tsc and eslint are clean.🤖 Generated with Claude Code
https://claude.ai/code/session_01WjEWJZ9XYFxL19mNfXgfPK
Generated by Claude Code