harden install/run: flags, preflight report, offline pip, port-in-use#9
Merged
Conversation
…in-use install.sh: - accepts -h/--help, -y/--yes, -n/--noninteractive, --no-launch, --skip-ollama, --skip-model-pull, --model TAG; flags are sugar over the existing env vars and never override an explicit env setting - prints a one-screen preflight report (OS, Python, Ollama state, model, mode) before any host-mutating step - fixes the Python version parser, which silently misread the patch component as 'minor' on three-component versions like 3.10.0 / 3.14.4 - tracks the repo path inside backend/.venv/.tutor_repo_root and rebuilds the venv automatically if the repo has been moved (virtualenvs are path-sensitive) - captures pip output to a log file and prints offline / proxy / wheelhouse remediation when the log shows DNS or network failure - documents exit codes (0/1/2/3) run.sh: - accepts -h/--help, --host, --port, --model, --open-browser, --no-launch, --skip-ollama, -y, -n; equivalent env vars still work - probes the target port with /dev/tcp before exec'ing uvicorn and exits 4 with an actionable message if a listener is already bound (no new system deps -- no lsof/ss) - --open-browser polls /api/health and only opens the URL once healthy - --no-launch runs the full preflight (venv, Ollama probe, port check) without binding a socket, useful for CI docs: - README gains an 'Install reliability' table linking to the new audit - docs/install-audit.md is the detailed runbook (offline wheelhouse, proxy, venv path sensitivity, gh auth) - docs/install-runtime-workflow.md grows a CLI-flag table, the offline /restricted-network section, and a venv-relocation note tests: - scripts/smoke_flags.sh exercises --help, unknown-flag rejection, --no-launch, and port-in-use detection - CI runs the new smoke step alongside the existing ones
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
2 participants
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.
Summary
Real-world install on a fresh Mac surfaced several quiet failure modes
the previous scripts handled poorly: an off-by-one Python version
parser, an opaque `pip` failure on a network that couldn't resolve
PyPI, a venv that broke after the repo was moved, and no way to pick a
different port when 8001 was in use. This PR makes the obvious failures
fail loudly with a concrete next step, exposes the previously
env-var-only options as proper `--flags`, and adds a runbook that
captures the audit.
(`--yes`, `--noninteractive`, `--no-launch`, `--skip-ollama`,
`--model`, `--host`, `--port`, `--open-browser`). Flags are sugar
over the existing env vars; nothing pre-existing breaks.
versions correctly (the old `${ver##*.}` mis-read patch as minor on
any 3-component version), and rebuilds the venv automatically if the
repo has been moved since the venv was created.
log shows DNS/network signatures -- prints offline-wheelhouse,
proxy, and internal-mirror recipes.
exits 4 with `--port N` guidance rather than letting uvicorn fall
over. `--open-browser` polls `/api/health` and opens once healthy.
rejection, `--no-launch`, and the port-in-use path. Wired into CI.
audit and runbook live in `docs/install-audit.md`.
Test plan
flag list
--no-launch` completes without prompting
exits 0 without binding
message
🤖 Generated by Computer