From a8599a924fee8e6cfb09b2fd96abcb5c066d284e Mon Sep 17 00:00:00 2001 From: Bryan Helmkamp Date: Tue, 21 Apr 2026 15:58:00 -0400 Subject: [PATCH] feat(install): pivot happy path to fabro server start web wizard MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The primary install flow is now to start the server, complete setup in a browser-based wizard, and restart. fabro install is retained as the headless CLI-only alternative. - Auto-open the install URL in the user's browser when fabro server start enters install mode; print a manual-open fallback when open::that fails - Rewrite install.md so agents drive the full start → wait → restart loop - Retarget install.sh Y/n prompt from fabro install to fabro server start - Update README, quick-start, deploy-server, cli reference, and marketing captions to point at fabro server start as the next step after download - Add troubleshooting entries for "wizard didn't open" and "server exited after wizard" Co-Authored-By: Claude Opus 4.7 (1M context) --- README.md | 9 +++- apps/marketing/public/install.md | 53 ++++++++++++++++--- apps/marketing/public/install.sh | 10 ++-- apps/marketing/src/pages/index.astro | 2 + docs/administration/deploy-server.mdx | 15 ++++-- docs/administration/troubleshooting.mdx | 4 ++ docs/getting-started/quick-start.mdx | 4 ++ docs/reference/cli.mdx | 10 +++- .../fabro-cli/src/commands/server/mod.rs | 5 ++ 9 files changed, 94 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index 29aebc14f..618229289 100644 --- a/README.md +++ b/README.md @@ -24,6 +24,8 @@ brew install fabro-sh/tap/fabro-nightly curl -fsSL https://fabro.sh/install.sh | bash ``` +Then run `fabro server start` to finish setup in your browser. The server opens a web wizard, exits when the wizard completes, and starts in configured mode the next time you run it. + Fabro Runs board showing workflows across Working, Pending, Verify, and Merge stages --- @@ -127,15 +129,18 @@ curl -fsSL https://fabro.sh/install.sh | bash Release binaries and the multi-arch Docker image ship with SLSA Build Provenance attestations. See [Verifying Releases](https://docs.fabro.sh/reference/verifying-releases) to check an artifact was built by our GitHub Actions workflow. -Then initialize Fabro in your project: +Then finish setup in your browser and initialize Fabro in your project: ```bash -fabro install # one-time setup +fabro server start # opens a web install wizard in your browser + # (server exits when the wizard finishes — start it again to run Fabro) cd my-project fabro repo init # per project ``` +For headless or scripted environments, `fabro install` runs the same setup as a CLI-only wizard. + --- ## Self-host the Fabro server diff --git a/apps/marketing/public/install.md b/apps/marketing/public/install.md index 70b7e02fb..26e0470a6 100644 --- a/apps/marketing/public/install.md +++ b/apps/marketing/public/install.md @@ -4,11 +4,11 @@ I want you to install Fabro for me. Execute the steps below autonomously. -OBJECTIVE: Install the Fabro CLI binary and verify it works. +OBJECTIVE: Install the Fabro binary, then start the server so the user can finish setup in a web wizard, then restart the server in configured mode. -DONE WHEN: `fabro --version` prints a version string. +DONE WHEN: The Fabro server has been restarted after the wizard and is running in configured (non-install) mode. -## Choose install method +## 1. Install the binary Check whether Homebrew is available: @@ -28,14 +28,53 @@ Otherwise, use the install script: curl -fsSL https://fabro.sh/install.sh | bash ``` -## Verify +## 2. Verify the binary ```bash fabro --version ``` -This must print a version string like `fabro 0.x.y`. If it does, installation is complete. +This must print a version string like `fabro 0.x.y` before continuing. -Tell the user to run `fabro install` in their terminal to complete setup. +## 3. Start the server to open the install wizard -EXECUTE NOW: Complete the above steps to achieve: `fabro --version` prints a version string. +Start the server in the foreground and capture its output: + +```bash +fabro server start +``` + +The server will: + +- Detect that Fabro is unconfigured and enter **install mode** +- Print a URL that looks like `http://127.0.0.1:/install?token=…` +- Attempt to open that URL in the user's default browser + +Your job: + +- Read the server's stderr and find the `http://…/install?token=…` line +- Open that URL in the user's default browser yourself as a safety net (the server also tries). Use `open` on macOS, `xdg-open` on Linux, or `start` on Windows. Duplicate opens are harmless. +- Tell the user: "The Fabro install wizard is open in your browser. Complete it there; I'll restart the server when you're done." +- Keep the `fabro server start` process running and watch for it to exit. The server exits on its own a moment after the user finishes the wizard. + +## 4. Restart the server in configured mode + +When the `fabro server start` process exits, start it again: + +```bash +fabro server start +``` + +This time it will boot in configured (non-install) mode. + +## 5. Confirm completion + +Verify the server is running and no longer in install mode: + +```bash +curl -fsS http://127.0.0.1:/health +``` + +The response should **not** contain `"mode": "install"`. If it does, the wizard wasn't completed — tell the user to finish it and wait for the server to restart again. + +EXECUTE NOW: Complete steps 1–5. You are done when the restarted server reports a non-install health status. diff --git a/apps/marketing/public/install.sh b/apps/marketing/public/install.sh index 21f07572d..6fbbbce25 100755 --- a/apps/marketing/public/install.sh +++ b/apps/marketing/public/install.sh @@ -158,14 +158,14 @@ else fi echo "" >&2 -# --- Prompt to run setup wizard --- +# --- Prompt to start the server and open the install wizard --- if [ -t 2 ] && [ -e /dev/tty ]; then - printf " ${BOLD}Run ${BOLD_CYAN}fabro install${RESET}${BOLD} now to complete setup? [Y/n]${RESET} " >&2 + printf " ${BOLD}Run ${BOLD_CYAN}fabro server start${RESET}${BOLD} now to finish setup in your browser? [Y/n]${RESET} " >&2 read -r answer &2; exec "${INSTALL_DIR}/fabro" install ;; + [nN]*) dim "Skipping. Run ${BOLD_CYAN}fabro server start${RESET}${DIM} whenever you're ready." ;; + *) echo "" >&2; exec "${INSTALL_DIR}/fabro" server start ;; esac else - info "Run ${BOLD_CYAN}fabro install${RESET} to complete setup." + info "Run ${BOLD_CYAN}fabro server start${RESET} to finish setup in your browser." fi diff --git a/apps/marketing/src/pages/index.astro b/apps/marketing/src/pages/index.astro index b86c6541b..ba997edba 100644 --- a/apps/marketing/src/pages/index.astro +++ b/apps/marketing/src/pages/index.astro @@ -152,6 +152,7 @@ const cssExample = `/* All nodes default to fast + ch +

Then run fabro server start to finish setup in your browser.

/* All nodes default to fast + ch
+

Then run fabro server start to finish setup in your browser.

+ +Setting up server mode instead? Run `fabro server start` to finish setup in a browser-based wizard. See [Running the Fabro Server](/administration/deploy-server) for the full flow. + + ## Initialize your project ```bash diff --git a/docs/reference/cli.mdx b/docs/reference/cli.mdx index 6a091803c..8a1f33e6e 100644 --- a/docs/reference/cli.mdx +++ b/docs/reference/cli.mdx @@ -376,6 +376,10 @@ Demo mode is per-request: send the `X-Fabro-Demo: 1` header to get static demo d When `--no-web` is set, the server still exposes the machine API under `/api/v1` and `/health`, but it returns `404` for `/`, `/auth/*`, SPA client routes, and the web-only helper endpoints under `/api/v1`. +### Install mode + +If `~/.fabro/settings.toml` does not exist yet, `fabro server start` enters install mode: it prints an install URL, attempts to open it in your default browser, and serves a web wizard for configuring LLM providers, the server URL, and GitHub integration. The server exits cleanly when the wizard finishes; start it again (or let a supervisor restart it) to boot in configured mode. See [Running the Fabro Server](/administration/deploy-server) for the full flow, and `fabro install` for the headless CLI-only equivalent. + ## `fabro server stop` Stop the running server daemon. Sends SIGTERM and waits for graceful shutdown, escalating to SIGKILL after the timeout. @@ -855,7 +859,11 @@ For OpenAI, this offers a device code flow — you open a URL in your browser, e ## `fabro install` -Interactive setup wizard that walks you through configuring API keys and validating your environment. Runs `fabro doctor` with live probes after setup to validate the configuration. +Interactive CLI setup wizard that walks you through configuring API keys and validating your environment. Runs `fabro doctor` with live probes after setup to validate the configuration. + + +For most users, the preferred way to set up server mode is to run `fabro server start`, which opens a web-based install wizard in the browser (see [Running the Fabro Server](/administration/deploy-server)). `fabro install` is the headless, CLI-only alternative — useful for remote hosts without a browser, scripted deployments, and CI. + ```bash fabro install diff --git a/lib/crates/fabro-cli/src/commands/server/mod.rs b/lib/crates/fabro-cli/src/commands/server/mod.rs index eb8cfe6fb..87bf6695d 100644 --- a/lib/crates/fabro-cli/src/commands/server/mod.rs +++ b/lib/crates/fabro-cli/src/commands/server/mod.rs @@ -226,6 +226,11 @@ fn announce_install_mode(bind: &Bind, token: &str, styles: &Styles, printer: Pri Some(url) => { fabro_util::printerr!(printer, " Open this URL in your browser to finish setup:"); fabro_util::printerr!(printer, " {url}"); + if let Err(e) = open::that(&url) { + fabro_util::printerr!(printer, ""); + fabro_util::printerr!(printer, " Could not open a browser automatically: {e}"); + fabro_util::printerr!(printer, " Open the URL above manually to continue."); + } } None => { fabro_util::printerr!(