Capablio

Handbook

Packaging and distribution

360 Insights Studio ships as a desktop app (Electron) with a frozen Python backend (PyInstaller). Builds are unsigned in v1 — facilitators must bypass OS warnings once per install.

Updated

Layout inside the app

Resource Packaged path Purpose
Frozen backend resources/backend/feedback360-backend/ (dir) Studio API (--app --port N)
Sample PDFs resources/samples/*.pdf Bundled Thomas + snapshot decks for demos
Electron shell resources/app.asar UI, IPC, keystore

The Electron main.js spawns feedback360-backend directly when packaged (no system Python required). In dev it falls back to .venv/bin/python -m feedback360.

Local builds

1. Frozen backend (all platforms)

cd workbench/feedback-360
bash packaging/build-backend.sh

Output: packaging/dist/feedback360-backend/ containing the feedback360-backend executable (.exe on Windows).

Requires requirements-dev.txt (pyinstaller plus runtime deps).

2. Electron — fast directory pack (verify layout)

cd desktop
npm ci
npm run pack:dir

Output: desktop/dist/linux-unpacked/ (on Linux) — unpacked tree for smoke checks without producing installers.

3. Platform installers

From desktop/ after the backend build:

Command Artifacts
npm run dist:linux .AppImage, .deb
npm run dist:win NSIS .exe, portable .exe
npm run dist:mac .dmg, .zip

Config: packaging/electron-builder.yml (appId: com.forge.feedback360studio, product name 360 Insights Studio).

CI matrix

The portable workflow template lives at .github-workflows/build.yml. When this folder is its own git repository, move it to .github/workflows/build.yml.

Job Runner Backend Electron target
linux ubuntu-latest Native Linux PyInstaller AppImage + deb
macos macos-latest Native macOS PyInstaller dmg + zip
windows-backend windows-latest Native Windows PyInstaller NSIS + portable

Triggers: workflow_dispatch and git tags v*. Each job uploads artifacts via actions/upload-artifact.

Windows caveat: the Windows backend cannot be cross-compiled on Linux. CI builds it only on windows-latest.

Unsigned app notes for facilitators

macOS (Gatekeeper)

The app is not notarized. First launch: right-click the app → Open → confirm Open in the dialog. Alternatively, allow in System Settings → Privacy & Security.

Windows (SmartScreen)

Windows may show “Windows protected your PC.” Click More info → Run anyway. No code-signing certificate is bundled in v1.

Linux

AppImage: chmod +x then run. .deb: install with your package manager; no signing step.

Frozen backend behavior

packaging/studio_backend.py delegates to feedback360.__main__:main with argv passthrough. Templates load via feedback360.resources.resource_path() so HTML templates resolve under sys._MEIPASS/feedback360/templates/ when frozen.