setup.sh: four gaps vs. CF installer pattern (hooks path, license key, port, docs URL) #71

New issue

Closed

opened 2026-04-05 22:56:26 -07:00 by pyr0ball · 1 comment

pyr0ball commented

2026-04-05 22:56:26 -07:00

Owner

Reviewing setup.sh against the CF installer pattern documented in circuitforge-plans/shared/2026-04-05-installer-pattern.md. Four gaps found:

1. Hardcoded developer-machine path in `activate_git_hooks()`

hooks_installer="/Library/Development/CircuitForge/circuitforge-hooks/install.sh"

This path only exists on the dev machine. Self-hosters silently fall through to the .githooks/ fallback, which is fine, but the hardcoded path is surprising. Should probe a relative or standard location, or drop the absolute-path check entirely and go straight to the core.hooksPath fallback.

2. No license key capture

cf-orch installer asks for an optional CFG-XXXX-… key and writes CF_LICENSE_KEY and HEIMDALL_URL to .env, enabling Heimdall validation for paid-tier self-hosters. Peregrine has the same licensing model but setup.sh never captures a key. Paid users have to find and edit .env manually.

Add a skip-able prompt before setup_env():

CircuitForge license key [press Enter to skip]:

If provided, write CF_LICENSE_KEY=<key> and HEIMDALL_URL=https://license.circuitforge.tech into .env.

3. Port mismatch in next-steps and docs

setup.sh line 432 and docs/getting-started/installation.md both direct users to http://localhost:8501, but Docker runs on 8502. The 8501 reference is the legacy bare-metal port.

Fix: echo $STREAMLIT_PORT from .env in the next-steps output, or hard-code 8502.

4. Stale git URL in installation docs

docs/getting-started/installation.md Step 1 still references:

git clone https://git.circuitforge.io/circuitforge/peregrine

Should be:

git clone https://git.opensourcesolarpunk.com/Circuit-Forge/peregrine

5. (Lower priority) No bare-metal / conda path

cf-orch supports both Docker Compose and a conda/pip venv path. Peregrine’s stack is heavier so Docker is the right default, but a bare-metal option would help users on locked-down systems. Not blocking.

Context: discovered while reviewing Peregrine’s installer against the pattern produced during cf-orch installer testing on strahl (2026-04-05/06).

Reviewing `setup.sh` against the CF installer pattern documented in `circuitforge-plans/shared/2026-04-05-installer-pattern.md`. Four gaps found: --- ### 1. Hardcoded developer-machine path in `activate_git_hooks()` ```bash hooks_installer="/Library/Development/CircuitForge/circuitforge-hooks/install.sh" ``` This path only exists on the dev machine. Self-hosters silently fall through to the `.githooks/` fallback, which is fine, but the hardcoded path is surprising. Should probe a relative or standard location, or drop the absolute-path check entirely and go straight to the `core.hooksPath` fallback. --- ### 2. No license key capture `cf-orch` installer asks for an optional `CFG-XXXX-…` key and writes `CF_LICENSE_KEY` and `HEIMDALL_URL` to `.env`, enabling Heimdall validation for paid-tier self-hosters. Peregrine has the same licensing model but `setup.sh` never captures a key. Paid users have to find and edit `.env` manually. Add a skip-able prompt before `setup_env()`: ``` CircuitForge license key [press Enter to skip]: ``` If provided, write `CF_LICENSE_KEY=<key>` and `HEIMDALL_URL=https://license.circuitforge.tech` into `.env`. --- ### 3. Port mismatch in next-steps and docs `setup.sh` line 432 and `docs/getting-started/installation.md` both direct users to `http://localhost:8501`, but Docker runs on **8502**. The 8501 reference is the legacy bare-metal port. Fix: echo `$STREAMLIT_PORT` from `.env` in the next-steps output, or hard-code 8502. --- ### 4. Stale git URL in installation docs `docs/getting-started/installation.md` Step 1 still references: ```bash git clone https://git.circuitforge.io/circuitforge/peregrine ``` Should be: ```bash git clone https://git.opensourcesolarpunk.com/Circuit-Forge/peregrine ``` --- ### 5. (Lower priority) No bare-metal / conda path `cf-orch` supports both Docker Compose and a conda/pip venv path. Peregrine’s stack is heavier so Docker is the right default, but a bare-metal option would help users on locked-down systems. Not blocking. --- Context: discovered while reviewing Peregrine’s installer against the pattern produced during `cf-orch` installer testing on `strahl` (2026-04-05/06).

pyr0ball referenced this issue from a commit

2026-04-05 23:33:59 -07:00

fix: rename setup.sh → install.sh; four installer gaps from #71

pyr0ball closed this issue

2026-04-05 23:33:59 -07:00

pyr0ball commented

2026-04-05 23:34:15 -07:00

Author

Owner

Fixed in commit 3458122. All four items addressed:

Hardcoded hooks path — removed the /Library/Development/CircuitForge/circuitforge-hooks/install.sh check entirely; activate_git_hooks() now goes straight to the .githooks/ + core.hooksPath fallback, which is what self-hosters always hit anyway.
License key capture — added capture_license_key(), called after setup_env() creates .env. Prompts for an optional CFG-XXXX-… key, validates the format, writes CF_LICENSE_KEY= and HEIMDALL_URL=https://license.circuitforge.tech into .env. Silently skipped in non-interactive mode.
Port in next-steps — reads STREAMLIT_PORT from .env at the end of main() instead of hardcoding 8501. Also updated .env.example default from 8501 → 8502 (Docker default).
Stale git URL — updated docs/getting-started/installation.md clone URL to git.opensourcesolarpunk.com/Circuit-Forge/peregrine.

Bonus (from user): renamed setup.sh → install.sh to standardise with the cf-orch installer pattern. Updated all references across manage.sh, Makefile, CONTRIBUTING.md, README.md, and docs/.

Fixed in commit `3458122`. All four items addressed: 1. **Hardcoded hooks path** — removed the `/Library/Development/CircuitForge/circuitforge-hooks/install.sh` check entirely; `activate_git_hooks()` now goes straight to the `.githooks/` + `core.hooksPath` fallback, which is what self-hosters always hit anyway. 2. **License key capture** — added `capture_license_key()`, called after `setup_env()` creates `.env`. Prompts for an optional `CFG-XXXX-…` key, validates the format, writes `CF_LICENSE_KEY=` and `HEIMDALL_URL=https://license.circuitforge.tech` into `.env`. Silently skipped in non-interactive mode. 3. **Port in next-steps** — reads `STREAMLIT_PORT` from `.env` at the end of `main()` instead of hardcoding `8501`. Also updated `.env.example` default from `8501` → `8502` (Docker default). 4. **Stale git URL** — updated `docs/getting-started/installation.md` clone URL to `git.opensourcesolarpunk.com/Circuit-Forge/peregrine`. **Bonus (from user):** renamed `setup.sh` → `install.sh` to standardise with the cf-orch installer pattern. Updated all references across `manage.sh`, `Makefile`, `CONTRIBUTING.md`, `README.md`, and `docs/`.