mirror of
https://github.com/maziggy/bambuddy.git
synced 2026-09-30 03:01:21 +02:00
maziggy
8711c54ec3
Lays down the Inno Setup + embedded Python pipeline for producing a self-contained Bambuddy Windows installer .exe. The installer ships an embedded Python 3.13, the pre-built React bundle, NSSM (service supervisor) and ffmpeg — no host Python or Node required on the target machine. Architecture: - Install: C:\Program Files\Bambuddy (admin install, one-time UAC) - Data: C:\ProgramData\Bambuddy\data (preserved on uninstall) - Service: registered via NSSM, runs as LocalSystem, autostart on boot - UI: browser at http://localhost:8000 (Start Menu shortcut) Files: - installers/windows/build.py stages embedded Python + deps, frontend bundle, NSSM, ffmpeg - installers/windows/bambuddy.iss Inno Setup compiler script - installers/windows/service/*.bat NSSM register/deregister - .github/workflows/windows-installer.yml CI build on tag push + manual dispatch, uploads .exe artifact build.py hard-fails on non-Windows hosts; Wine cross-build is an unsupported escape hatch behind --allow-non-windows. v1 ships unsigned (SmartScreen warns on first run) — production signing will be wired up via SignPath OSS once the application is approved. See installers/windows/README.md for build prerequisites and the embedded-Python ._pth gotchas.
85 lines
3.5 KiB
Markdown
85 lines
3.5 KiB
Markdown
# Bambuddy Windows Installer
|
||
|
||
Builds a self-contained Windows installer (`.exe`) for Bambuddy: embedded
|
||
Python 3.13 distribution + pre-built frontend + NSSM-supervised Windows
|
||
service. No Python or Node installation required on the target machine.
|
||
|
||
## Architecture
|
||
|
||
- **Install target:** `C:\Program Files\Bambuddy\`
|
||
- **Data target:** `C:\ProgramData\Bambuddy\data\` (preserved on uninstall by default)
|
||
- **Logs target:** `C:\ProgramData\Bambuddy\logs\`
|
||
- **Service:** registered via NSSM, runs as `LocalSystem`, autostart on boot
|
||
- **Service command:** `python.exe -m uvicorn backend.app.main:app --host 0.0.0.0 --port 8000`
|
||
- **Bundled binaries:** Python 3.13 embeddable, NSSM, ffmpeg static build
|
||
|
||
Browser is the UI. Start Menu shortcut opens `http://localhost:8000`.
|
||
|
||
## Why these choices
|
||
|
||
See `memory/windows-installer-decision.md` for the full reasoning. Short
|
||
version: PowerShell install scripts can't survive environmental drift
|
||
across the Windows host fleet, so we ship a self-contained bundle that
|
||
depends on nothing on the host. Inno Setup + embedded Python is the
|
||
lowest-maintenance path that delivers native-app UX. No Tauri/Electron
|
||
launcher in v1 — browser-as-UI matches every other Bambuddy platform.
|
||
|
||
## Build prerequisites
|
||
|
||
The build runs on Windows (or in a Windows GitHub Actions runner). Cross-
|
||
building from Linux is possible via Wine but not officially supported.
|
||
|
||
- Windows 10/11 x64 (or `windows-latest` GitHub Actions runner)
|
||
- Python 3.11+ (for running `build.py`; the embedded Python that ships
|
||
in the installer is downloaded fresh by the build script)
|
||
- Node.js 22 LTS + npm (for building the frontend bundle)
|
||
- [Inno Setup 6](https://jrsoftware.org/isdl.php) (for compiling
|
||
`bambuddy.iss` → `.exe`)
|
||
|
||
The build script downloads everything else automatically (embedded Python,
|
||
NSSM, ffmpeg).
|
||
|
||
## Build steps
|
||
|
||
```cmd
|
||
:: From the repo root on a Windows machine
|
||
cd installers\windows
|
||
python build.py
|
||
:: Then open bambuddy.iss in Inno Setup Compiler and click Build → Compile
|
||
:: (or invoke ISCC.exe directly:)
|
||
"C:\Program Files (x86)\Inno Setup 6\ISCC.exe" bambuddy.iss
|
||
```
|
||
|
||
Output: `installers\windows\build\output\bambuddy-windows-setup.exe`
|
||
|
||
## Testing without signing
|
||
|
||
The installer can be built and run unsigned. Windows SmartScreen will
|
||
show "Windows protected your PC" on first run. Click **More info** →
|
||
**Run anyway** to proceed. This is expected and harmless for testing.
|
||
Production builds will be signed via SignPath OSS (application in
|
||
flight as of 2026-06-10) and won't show this warning after reputation
|
||
accrues.
|
||
|
||
## CI build
|
||
|
||
See `.github/workflows/windows-installer.yml` for the automated build.
|
||
The workflow runs on every tag matching `v*` and uploads the installer
|
||
as a release asset.
|
||
|
||
## Known limitations / open questions
|
||
|
||
- **VP feature on Windows:** the Virtual Printer needs to bind 322/990/8883
|
||
(privileged ports). Service runs as LocalSystem which can bind these
|
||
ports, but the user's Windows Firewall will prompt on first VP enable.
|
||
Documenting this is TBD.
|
||
- **Spoolman:** explicitly NOT bundled in v1. Users who want Spoolman
|
||
install it separately. Bambuddy internal-inventory mode is the default
|
||
on Windows.
|
||
- **Bundle size:** estimated 250–350MB installed (mostly opencv +
|
||
ffmpeg + matplotlib). Acceptable for a v1; can investigate slimming
|
||
later if users complain.
|
||
- **Updates:** v1 ships as a fresh install / uninstall + install cycle.
|
||
In-place upgrade via the same installer is supported by Inno Setup but
|
||
needs end-to-end testing before we promise it.
|