feat: migrate MUIOGO to uv and add bootstrap installers (#472) by utsinboots · Pull Request #482 · EAPD-DRB/MUIOGO

utsinboots · 2026-06-12T23:48:38Z

Summary

Related to #472

This PR migrates MUIOGO to a uv-managed project and adds one-liner bootstrap installers for Windows and macOS/Linux, so users can go from a clean machine to a running MUIOGO environment in a single command.

##Changes

pyproject.toml

Added [build-system] (setuptools >= 64)
Added [project] block with name, version, requires-python = ">=3.11, <3.13", and all runtime dependencies (previously only in requirements.txt)
Added [tool.setuptools.packages.find] scoped to API* to prevent setuptools discovering unrelated top-level dirs (assets/, WebAPP/)
Updated [tool.ruff] target-version from py310 to py311

uv.lock

Generated by uv lock — resolves 26 packages reproducibly across platforms

.gitignore

Added *.egg-info/ (setuptools build artifact)
Added .install-*.log (installer log files)

scripts/setup_dev.py

Added --platform-only flag — skips venv/pip steps and runs only platform setup (solvers, demo data, secret key, verification)
Used by the bootstrap installers after uv sync has already created the venv
Raised MIN_PYTHON from (3, 10) to (3, 11)

scripts/install.ps1 (new)

Windows bootstrap installer (PowerShell)
5 steps: check git → install uv → clone MUIOGO → uv sync → setup_dev.py --platform-only
Idempotent: re-running on an existing clone offers git pull instead of re-cloning
Parameters: -Dest, -Branch, -RepoUrl, -Yes, -NoDemoData, -SkipUvInstall, -NoLog

scripts/install.sh (new)

macOS/Linux bootstrap installer (bash)
Same 5 steps and same parameter set as install.ps1 (kebab-case flags)
Git Bash on Windows also supported (detects Scripts/ vs bin/ venv layout)
Browser launch: cmd.exe /c start on Windows/Git Bash, open on macOS, xdg-open on Linux

One-liner install (after merge)

Windows (PowerShell):

irm https://raw.githubusercontent.com/EAPD-DRB/MUIOGO/main/scripts/install.ps1 | iex

macOS/Linux:

curl -fsSL https://raw.githubusercontent.com/EAPD-DRB/MUIOGO/main/scripts/install.sh -o /tmp/install.sh && bash /tmp/install.sh

Testing this PR

Use the fork URL + branch until this PR is merged.

Windows (PowerShell)

Create a clean test directory
mkdir C:.\muiogo-test
Run the installer

powershell -ExecutionPolicy Bypass -Command "irm https://raw.githubusercontent.com/utsinboots/MUIOGO/feature/472-uv-installer/scripts/install.ps1 | iex"

When prompted for destination, enter: C:.\muiogo-test

macOS/Linux (or Git Bash on Windows)

Create a clean test directory
mkdir ~/muiogo-test
Run the installer

curl -fsSL https://raw.githubusercontent.com/utsinboots/MUIOGO/feature/472-uv-installer/scripts/install.sh -o /tmp/install.sh && bash /tmp/install.sh

When prompted for destination, enter: ~/muiogo-test

The following items from #472 are deferred to a follow-up PR:

Git auto-install: The installers check for git and fail with clear instructions if missing (winget / xcode-select / apt). Auto-installing git adds significant complexity per platform and was deferred.
macOS git stub: install.sh uses command -v git; the macOS CLT stub edge case (xcode-select -p check + async GUI polling) is not yet handled.
Temp dir clone: The issue requested cloning to a temp dir then moving on success. Direct clone is used instead (same pattern as OG-Core) — Windows filesystem locks made the move approach unreliable.
setup.bat and start.bat were intentionally left unchanged in this PR to avoid altering the existing developer workflow while the new uv-based bootstrap installers are introduced.
Repo version/update check: The installer detects an existing clone and offers git pull, but does not show the current version or how many commits behind the local clone is before prompting.

…aller

utsinboots · 2026-06-15T17:55:28Z

Hi @SeaCelo @autibet installer is ready to be tested.
Working and tested:

Checks git
Detects/installs uv
Clones the target branch (currently my fork/branch for testing)
Runs uv sync
Performs platform setup:
- Creates .env and MUIOGO_SECRET_KEY
- Checks/installs solver dependencies (GLPK/CBC)
- Downloads and extracts demo data into WebAPP/DataStorage
- Runs dependency verification checks
Launches the MUIOGO app in the browser

autibet

EPIC FAIL! 🤪

(base) sato@Sato MUIOGO % curl -fsSL https://raw.githubusercontent.com/utsinboots/MUIOGO/feature/472-uv-installer/scripts/install.sh -o /tmp/install.sh && bash /tmp/install.sh
(base) sato@Sato MUIOGO % ERROR: conda env 'base' is active. Run 'conda deactivate' first. conda deactivate
sato@Sato MUIOGO % conda deactivate

sato@Sato MUIOGO % curl -fsSL https://raw.githubusercontent.com/utsinboots/MUIOGO/feature/472-uv-installer/scripts/install.sh -o /tmp/install.sh && bash /tmp/install.sh

Where would you like to install MUIOGO?
Enter the PARENT directory; MUIOGO will be cloned as a subfolder inside.
Default: current directory (/Users/sato/GitHub/MUIOGO)
Parent directory [.]: ~/muiogo-test

==============================================================
MUIOGO Installer (uv-based)
Platform : macOS 26.5
Destination : /Users/sato/muiogo-test/MUIOGO
Branch : feature/472-uv-installer
uv : will install (~5MB, official installer)
Log file : /Users/sato/GitHub/MUIOGO/.install-20260615-164910.log

Plan (5 steps):

Check git
Install uv ~5MB, seconds
Clone MUIOGO depends on network
uv sync (Python + deps) ~30s
Platform setup (solvers, demo data, secret key, verification)

Proceed with installation? [Y/n/q] Y
/tmp/install.sh: line 132: ${ans,,}: bad substitution

utsinboots · 2026-06-15T21:42:25Z

@autibet Oops 🩻 it was macOS Bash compatibility issue; the install.sh used case "${ans,,}" in requires Bash 4+ version, so changed it to case "$(echo "$ans" | tr '[:upper:]' '[:lower:]')" in which will work on most Bash.
Could you please rerun the installer please. Thank you. 😅

…false, fix macOS git detection + graceful platform-setup failure, add QUICK_INSTALL.md

autibet

Successfully installed ^_^

SeaCelo · 2026-06-17T18:50:13Z

@utsinboots I pushed two commits straight to the branch to get it merge-ready (now at 0986a6ec) — let me know if you'd rather have handled any of it yourself:

Applied the review fixes: Python floor back to 3.10 (staying aligned with MUIO, not bumping for OG), [tool.uv] package = false since MUIOGO is an app we run rather than a library, a macOS git detection fix, and install.sh now continues past a platform-setup failure so you still get the summary. Also added QUICK_INSTALL.md.
Reverted the installer defaults back to EAPD-DRB/MUIOGO + main for merge.

@autibet — could you give it one more run on macOS? Your earlier approval was on the 3.11 build, and these commits change how the install behaves. One catch: now that the defaults point at EAPD-DRB/main, you have to pass the fork URL and branch explicitly, or it'll clone main instead of this PR:

curl -fsSL https://raw.githubusercontent.com/utsinboots/MUIOGO/feature/472-uv-installer/scripts/install.sh -o /tmp/install.sh && bash /tmp/install.sh --repo-url https://github.com/utsinboots/MUIOGO.git --branch feature/472-uv-installer

Thanks both!

…x upstream comparison

utsinboots · 2026-06-17T20:38:28Z

@SeaCelo thank you for the fix and updates, your validation is always needed :). Tested on windows, everything looks good.
Last commit:

Log off by default, --log to opt in (in both install.sh and install.ps1)
Repo version check in install.sh and install.ps1 inserted in Step 3 clone/pull

--------------------------------------------------------------
  Step 3 of 5: Clone MUIOGO
--------------------------------------------------------------
 Existing MUIOGO clone found at C:\~\uv-final-test\MUIOGO (branch: feature/472-uv-installer).
  Local:   4850e57d  (feature/472-uv-installer)
  Latest:  5cb5911c  (EAPD-DRB/MUIOGO:main)
  [PASS] Up to date  --  0 behind, 12 ahead

  [WARN] 3 behind, 9 ahead  --  update now?
  Update now? [Y/n/q]:

autibet · 2026-06-17T21:00:04Z

Anothe EPIC FAIL

sato@Alfonsos-MacBook-Air muiogo-test % curl -fsSL https://raw.githubusercontent.com/utsinboots/MUIOGO/feature/472-uv-installer/scripts/install.sh -o /tmp/install.sh && bash /tmp/install.sh --repo-url https://github.com/utsinboots/MUIOGO.git --branch feature/472-uv-installer

Where would you like to install MUIOGO?
Enter the PARENT directory; MUIOGO will be cloned as a subfolder inside.
Default: current directory (/Users/sato/Documents/GitHub/muiogo-test)
Parent directory [.]:

==============================================================
MUIOGO Installer (uv-based)

Platform : macOS 26.4
Destination : /Users/sato/Documents/GitHub/muiogo-test/MUIOGO
Branch : feature/472-uv-installer
uv : will install (~5MB, official installer)

Plan (5 steps):
1. Check git
2. Install uv ~5MB, seconds
3. Clone MUIOGO depends on network
4. uv sync (Python + deps) ~30s
5. Platform setup (solvers, demo data, secret key, verification)

Proceed with installation? [Y/n/q] Y

Step 1 of 5: Check git

[PASS] git (git version 2.50.1 (Apple Git-155))

Step 2 of 5: Install uv

Installing uv via the official installer (no sudo required)...
$ curl -LsSf https://astral.sh/uv/install.sh | sh
downloading uv 0.11.21 aarch64-apple-darwin
installing to /Users/sato/.local/bin
uv
uvx
everything's installed!

To add $HOME/.local/bin to your PATH, either restart your shell or run:

source $HOME/.local/bin/env (sh, bash, zsh)
source $HOME/.local/bin/env.fish (fish)

[PASS] uv installed (/Users/sato/.local/bin/uv (uv 0.11.21 (5aa65dd7a 2026-06-11 aarch64-apple-darwin)))

Step 3 of 5: Clone MUIOGO

Cloning MUIOGO into /Users/sato/Documents/GitHub/muiogo-test/MUIOGO...
$ git clone --branch feature/472-uv-installer https://github.com/utsinboots/MUIOGO.git /Users/sato/Documents/GitHub/muiogo-test/MUIOGO
Cloning into '/Users/sato/Documents/GitHub/muiogo-test/MUIOGO'...
remote: Enumerating objects: 43806, done.
remote: Counting objects: 100% (815/815), done.
remote: Compressing objects: 100% (392/392), done.
remote: Total 43806 (delta 595), reused 455 (delta 422), pack-reused 42991 (from 2)
Receiving objects: 100% (43806/43806), 163.30 MiB | 43.30 MiB/s, done.
Resolving deltas: 100% (22801/22801), done.
[PASS] Cloned MUIOGO (/Users/sato/Documents/GitHub/muiogo-test/MUIOGO (branch: feature/472-uv-installer))

Step 4 of 5: Install dependencies (uv sync)

Installing Python + all dependencies into /Users/sato/Documents/GitHub/muiogo-test/MUIOGO/.venv
$ uv sync
Using CPython 3.12.13
Creating virtual environment at: .venv
Resolved 26 packages in 1ms
Prepared 25 packages in 552ms
Installed 25 packages in 40ms

blinker==1.8.2
boto3==1.34.122
botocore==1.34.122
click==8.1.7
colorama==0.4.6
et-xmlfile==1.1.0
flask==3.0.3
flask-cors==4.0.1
itsdangerous==2.2.0
jinja2==3.1.4
jmespath==1.0.1
markupsafe==2.1.5
numpy==1.26.4
openpyxl==3.1.4
packaging==24.0
pandas==2.2.2
python-dateutil==2.9.0.post0
python-dotenv==1.0.1
pytz==2024.1
s3transfer==0.10.1
six==1.17.0
tzdata==2024.1
urllib3==2.7.0
waitress==3.0.0
werkzeug==3.0.3
[PASS] Dependencies installed (.venv)

Step 5 of 5: Platform setup (solvers, demo data, secret key, verification)

$ python scripts/setup_dev.py --platform-only --venv-dir .venv

MUIOGO Development Environment Setup
Platform : Darwin (arm64)
Python : 3.12.13
Support : >=3.10, <3.13
Project : /Users/sato/Documents/GitHub/muiogo-test/MUIOGO
Venv dir : /Users/sato/Documents/GitHub/muiogo-test/MUIOGO/.venv

============================================================
Step 1 & 2: Skipped (uv-managed environment)

[PASS] Python environment managed by uv (skipping venv creation and pip install)

============================================================
Step 2a: App secret key

[PASS] Created persistent MUIOGO_SECRET_KEY (/Users/sato/Documents/GitHub/muiogo-test/MUIOGO/.env)

============================================================
Step 3: Solver dependencies (GLPK & CBC)

[FAIL] Homebrew not found (Install from https://brew.sh then re-run this script.)
[FAIL] GLPK (glpsol) not available
[FAIL] CBC not available

Manual solver installation:

GLPK: brew install glpk
CBC: brew install cbc

============================================================
Step 4: Demo data

Demo-data archive not found locally; downloading from release asset ...
[PASS] Demo-data archive downloaded (/Users/sato/Documents/GitHub/muiogo-test/MUIOGO/assets/demo-data/CLEWs.Demo.zip)
Verifying demo-data archive checksum ...
[PASS] Demo-data archive checksum (db92d380b0448f767c4ba56eea5c79b14bcae8fbf8e05a6a0d92d5345bb742c1)
Extracting demo data archive ...
[PASS] Demo data installed (/Users/sato/Documents/GitHub/muiogo-test/MUIOGO/WebAPP/DataStorage/CLEWs Demo)

============================================================
Step 5: Verification checks

[PASS] Python venv exists (/Users/sato/Documents/GitHub/muiogo-test/MUIOGO/.venv/bin/python)

Checking Python imports:
[PASS] import flask
[PASS] import flask_cors
[PASS] import pandas
[PASS] import numpy
[PASS] import openpyxl
[PASS] import waitress
[PASS] import dotenv

Checking solver binaries:
[FAIL] GLPK (glpsol) (not found via SOLVER_GLPK_PATH or PATH)
[FAIL] CBC (not found via SOLVER_CBC_PATH or PATH)

Checking app startup:
[PASS] Flask app module loads without error

============================================================
Setup Summary

[PASS] Python environment (managed by uv sync)
[PASS] App secret key (/Users/sato/Documents/GitHub/muiogo-test/MUIOGO/.env)
[FAIL] Solver dependencies (GLPK & CBC)
[PASS] Demo data (installed)
[FAIL] Verification checks

Some checks failed.

Next steps:

Review the [FAIL] items above.
Fix the issues and re-run:
./scripts/setup.sh --check
If solver install failed, see manual instructions above or run:
./scripts/setup.sh
after installing the solvers manually.
For help, see CONTRIBUTING.md or open an issue.

[FAIL] Platform setup reported failures -- review output above

==============================================================
Installation Summary

[PASS] git (git version 2.50.1 (Apple Git-155))
[PASS] uv (/Users/sato/.local/bin/uv)
[PASS] Clone (feature/472-uv-installer)
[PASS] uv sync (.venv)
[FAIL] Platform setup (setup_dev.py exited 1)

Elapsed : 0m 20s
Location : /Users/sato/Documents/GitHub/muiogo-test/MUIOGO

One or more steps failed -- review the output above.

autibet

Fix above comment

SeaCelo · 2026-06-17T21:16:19Z

@utsinboots quick diagnosis on autibet's run, then a proposal.

The only step that failed was the solvers — and the root cause is right in the log: [FAIL] Homebrew not found. That Mac just doesn't have Homebrew, so brew install couldn't run. Everything else passed (git, uv, clone, uv sync, secret key, demo data, app load), including the 3.10 revert — so this isn't a regression. It's a clean Mac with no brew, which is exactly the person a one-line installer is meant for.

Right now install_solvers() in setup_dev.py hard-fails when brew is missing (~line 888), and main() then exits 1 — so the whole install reports failure even though MUIOGO is set up and launches.

Proposal: instead of dying on a missing Homebrew, detect it and offer to install it.

On macOS with no brew, prompt: Homebrew is needed for the GLPK/CBC solvers. Install it now? [y/N]
- Yes → run the official installer, load it into the current shell, then carry on with brew install glpk cbc in the same run:
```
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
eval "$(/opt/homebrew/bin/brew shellenv)"   # Intel Macs: /usr/local/bin/brew
```
- No → point them to https://brew.sh and finish without a hard fail, with a clear note that solvers are still needed to run models (brew install glpk cbc once brew is in).

Couple of things to watch:

Homebrew's installer is interactive — it confirms, asks for sudo, and may trigger an Xcode Command Line Tools install. So keep it behind the prompt, and when --yes/-Yes is set, skip the auto-run and just print the brew.sh instructions (it can't run cleanly unattended).
Right after install, brew won't be on PATH yet in the same session — it lands in /opt/homebrew/bin (Apple Silicon) or /usr/local/bin (Intel), so resolve which before calling brew install.

This mirrors what our older macOS installer did (brew was a documented prerequisite) but is friendlier, since it offers to do it for them. Net effect: a clean Mac either ends up fully set up, or finishes with clear instructions instead of an "EPIC FAIL."

Happy to take this on if it's easier — just say the word.

utsinboots · 2026-06-17T21:21:49Z

@SeaCelo right, just the change with the correct behavior required 😅 I'll leave it up to you, thanks. 🚢

utsinboots added 4 commits June 12, 2026 14:36

feat: migrate MUIOGO to uv (pyproject.toml + uv.lock)

27bf063

feat: add --platform-only flag to setup_dev.py for uv bootstrap

dca533b

feat: add Windows bootstrap installer (scripts/install.ps1)

b42311f

feat: add macOS/Linux bootstrap installer (scripts/install.sh)

71ef8c6

github-actions Bot added the needs-intake-fix PR intake structure needs maintainer follow-up label Jun 12, 2026

utsinboots self-assigned this Jun 12, 2026

utsinboots requested a review from SeaCelo June 12, 2026 23:52

utsinboots changed the title ~~feat: migrate MUIOGO to uv and add bootstrap installers (closes #472)~~ feat: migrate MUIOGO to uv and add bootstrap installers (#472) Jun 12, 2026

utsinboots marked this pull request as draft June 13, 2026 00:29

point default repo URL to fork for PR testing (to revert before merge)

f01c204

SeaCelo added Priority: High Track: OG Onboarding Onboarding, first-run UX, and contributor/user guidance labels Jun 15, 2026

utsinboots added 3 commits June 15, 2026 12:43

chore: set default branch to feature/472-uv-installer for PR testing

c142e2e

Merge remote-tracking branch 'upstream/main' into feature/472-uv-inst…

caea75d

…aller

style: fix indentation of --platform-only in setup_dev.py

5b47d10

utsinboots marked this pull request as ready for review June 15, 2026 19:11

utsinboots requested a review from autibet June 15, 2026 19:16

autibet requested changes Jun 15, 2026

View reviewed changes

Fix Bash 3.2 compatibility in install.sh

b210ea6

utsinboots requested a review from autibet June 15, 2026 21:42

utsinboots mentioned this pull request Jun 16, 2026

[Bug] CBC solver installation via Homebrew slow on Intel macOS #484

Open

Installer review fixes for EAPD-DRB#482: keep 3.10 floor, uv package=…

c34b06d

…false, fix macOS git detection + graceful platform-setup failure, add QUICK_INSTALL.md

autibet approved these changes Jun 16, 2026

View reviewed changes

Revert fork URL/branch test defaults to EAPD-DRB/main for merge

0986a6e

SeaCelo marked this pull request as draft June 17, 2026 18:49

utsinboots added 2 commits June 17, 2026 16:05

feat: add a repo version step and make log off by default in installers

4850e57

fix: move version check into clone step, show ahead/behind counts, fi…

1905874

…x upstream comparison

autibet marked this pull request as ready for review June 17, 2026 20:59

autibet self-requested a review June 17, 2026 21:03

autibet requested changes Jun 17, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

feat: migrate MUIOGO to uv and add bootstrap installers (#472)#482

feat: migrate MUIOGO to uv and add bootstrap installers (#472)#482
utsinboots wants to merge 13 commits into
EAPD-DRB:mainfrom
utsinboots:feature/472-uv-installer

utsinboots commented Jun 12, 2026 •

edited

Loading

Uh oh!

utsinboots commented Jun 15, 2026

Uh oh!

autibet left a comment •

edited

Loading

Uh oh!

utsinboots commented Jun 15, 2026

Uh oh!

autibet left a comment

Uh oh!

SeaCelo commented Jun 17, 2026

Uh oh!

utsinboots commented Jun 17, 2026

Uh oh!

autibet commented Jun 17, 2026

Uh oh!

autibet left a comment

Uh oh!

SeaCelo commented Jun 17, 2026

Uh oh!

utsinboots commented Jun 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

utsinboots commented Jun 12, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

One-liner install (after merge)

Testing this PR

Windows (PowerShell)

macOS/Linux (or Git Bash on Windows)

Uh oh!

utsinboots commented Jun 15, 2026

Uh oh!

autibet left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

utsinboots commented Jun 15, 2026

Uh oh!

autibet left a comment

Choose a reason for hiding this comment

Uh oh!

SeaCelo commented Jun 17, 2026

Uh oh!

utsinboots commented Jun 17, 2026

Uh oh!

autibet commented Jun 17, 2026

============================================================== MUIOGO Installer (uv-based)

Step 1 of 5: Check git

Step 2 of 5: Install uv

Step 3 of 5: Clone MUIOGO

Step 4 of 5: Install dependencies (uv sync)

Step 5 of 5: Platform setup (solvers, demo data, secret key, verification)

============================================================ Step 1 & 2: Skipped (uv-managed environment)

============================================================ Step 2a: App secret key

============================================================ Step 3: Solver dependencies (GLPK & CBC)

============================================================ Step 4: Demo data

============================================================ Step 5: Verification checks

============================================================ Setup Summary

============================================================== Installation Summary

Uh oh!

autibet left a comment

Choose a reason for hiding this comment

Uh oh!

SeaCelo commented Jun 17, 2026

Uh oh!

utsinboots commented Jun 17, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

utsinboots commented Jun 12, 2026 •

edited

Loading

autibet left a comment •

edited

Loading

==============================================================
MUIOGO Installer (uv-based)

============================================================
Step 1 & 2: Skipped (uv-managed environment)

============================================================
Step 2a: App secret key

============================================================
Step 3: Solver dependencies (GLPK & CBC)

============================================================
Step 4: Demo data

============================================================
Step 5: Verification checks

============================================================
Setup Summary

==============================================================
Installation Summary