Repository navigation
Description
Summary
./scripts/install-dev.sh does not complete on a fresh Linux box at 26.10.0a5. Four independent defects line up on the way from the bootstrapper to the first ./dev start; each one is masked on macOS, and each one is small. This epic tracks them together because a developer meets them in sequence, and the fixes belong to the same two scripts.
Observed on Ubuntu 24.04 (arm64, OrbStack VM), upgrading a 26.9.1 checkout to 26.10.0a5 and then on a wiped volumes/. Every step below was reproduced; the root causes were traced to the commits named.
What a fresh Linux box hits, in order
| # | Step | Symptom | Cause | Introduced by |
|---|---|---|---|---|
| 1 | "Checking the bootstrapper Python version" | Failed to inspect Python interpreter … pyenv: python3.13: command not found ×6, then the script continues with PYTHON_VERSION="", reports Python "already installed" and fails later in pants |
scripts/python.sh / pyscript.sh run uv run --python=3.13.18; a uv older than 0.13.6 (2026-10-26) has no 3.13.18 download, falls back to PATH, and aborts on pyenv's python3.13 shim (exit 127). No set -e at the top of install-dev.sh, so the empty version propagates |
#5536 coupled the bootstrapper to the project Python; #16048 bumped it to 3.13.18 one day after uv and pyenv shipped it |
| 2 | install_python |
pyenv install 3.13.18 fails on a pyenv older than v2.8.14 (2026-10-26); the hint at install-dev.sh:668–669 says to edit PYTHON_VERSION in the script, which pants.toml now owns |
Hint text predates #5536 | #5536 |
| 3 | ./scripts/delete-dev.sh then install-dev.sh |
mgr seed apply fails 13 items (user, project, resource_group_for_domain) and writes 57 runtime_variant_presets rows that point at variant ids no row has |
delete-dev.sh:152 runs rm -rf volumes without $sudo; the halfstack bind mounts are owned by the containers' uids (postgres 70, redis 999, mode 700), the rm prints Permission denied, the script has no set -e, and the next install reuses the old database. Masked since 2024 because schema oneshot skips an initialized database and fixture populate tolerated existing rows; seed apply is the first step that refuses them |
#1852 added the rm without the $sudo that aeca1e9 had introduced for docker-owned paths; visible since #15802 |
| 4 | ./dev start all |
tmux: command not found |
install-dev.sh installs git jq gcc make g++ and the Python build libraries, not tmux; dev calls tmux with no command -v check |
#10504 added ./dev |
macOS is unaffected by 1–3 in practice: developers there had a uv-managed 3.13.7 already (so PATH was never scanned), and Docker Desktop maps bind-mount ownership to the user (so rm -rf volumes works). CI never runs delete-dev.sh (integration.yml runs install-dev.sh once on a fresh runner).
Tasks
-
scripts/delete-dev.sh:$sudo rm -rf volumes(the variable is already defined at line 70 and unused). Backport to 26.9. -
scripts/install-dev.sh: make the bootstrapper check at line 369 fatal and name the remedy (uv self update); read the version for the message frompants.tomlwithgrep, not through the wrapper that just failed. -
scripts/install-dev.sh:668–669: the hint says to update pyenv, not to editPYTHON_VERSION. -
pants.toml:80–86comment: listscripts/python.sh,scripts/pyscript.sh,tools/build-macros.pyas files a Python bump touches, and "developers:uv self update,pyenv update". -
scripts/install-dev.sh: addtmuxto the apt/brew package lists;dev: print "install tmux" whencommand -v tmuxfails. - Separate issue (filed next):
mgr seed applyon a database created before the seed files fails and writes orphan rows; a customer site cannot recreate its database. Found through Enhance testing and CI #3 above; the fix needs a design decision (refuse vs. adopt by name), so it is not a task of this epic.
Out of scope
- Decoupling the bootstrapper Python from the project Python again (the pre-deps(BA-2143): Upgrade the base Python version to 3.13.7 #5536
bootstrap-static-python.shdesign). Worth revisiting if the next bump breaks developers even with the fatal check in place. - Reverting feat(BA-8272): apply seeds in install-dev and the installer, and deprecate fixture populate #15802. It is where Enhance testing and CI #3 became visible, not what breaks the database.
References
install-dev.shfails on an existing database:example-users.jsonpins the default scaling group's UUID #15301 / fix(BA-8331): Reconcile the account seed's declared ids with the database #15302: the same leftover-database symptom on the fixture path, closed as superseded by feat(BA-8272): apply seeds in install-dev and the installer, and deprecate fixture populate #15802 with "delete-dev.shcovers the scenario", which Enhance testing and CI #3 shows it does not on Linux.- Seed the global entities on a fresh install like the other default rows #15955: the stated contract that migrations give an existing database its default rows and
seed applygives a fresh one. - uv 0.13.6 changelog: "Add CPython 3.11.18, 3.12.16, 3.13.18, 3.14.10, and 3.15.2 (Sync latest Python releases, Python 3.11.18, 3.12.16, 3.13.18, 3.14.10, 3.15.2 astral-sh/uv#22938)"; pyenv v2.8.14 added the 3.13.18 definition (Add CPython 3.12.16, 3.13.18, 3.14.10, 3.15.2 pyenv/pyenv#3604).
JIRA Issue: BA-8775
Activity
[-]Epic: install-dev on a fresh Linux box fails from the bootstrapper to the first ./dev start[/-][+]`install-dev` on a fresh Linux box fails from the bootstrapper to the first `./dev start`[/+]