Build from source

Run FolioOrb as a local web app straight from the source: one setup script starts the server and you use the dashboard in your browser at http://localhost:8000. It works on macOS (Apple Silicon or Intel), Windows, and Linux with Python 3.11+ — no installer, no account, nothing hosted. (You can also build the desktop installers yourself — see below.)

Run from source

macOS / Linux

git clone https://github.com/udhawan97/FolioOrb.git
cd FolioOrb
./scripts/setup.sh

Windows

git clone https://github.com/udhawan97/FolioOrb.git
cd FolioOrb
.\scripts\setup.ps1

The setup script creates a virtual environment, installs dependencies, writes a local .env, prepares the database/ folder, and starts the app at http://localhost:8000. For day-to-day use afterwards, run ./scripts/start.sh (or .\scripts\start.ps1).

Keep custom data in one profile

The default .env needs no changes. If you set FOLIOORB_DATA_DIR, FolioOrb derives database/portfolio.db beneath that root. If you also set a custom DATABASE_URL, set both values in the process environment and keep the SQLite file beneath FOLIOORB_DATA_DIR. Split or out-of-profile paths fail before FolioOrb writes a database, backup, setting, restore marker, update file, or migration copy.

Manual setup

python3 -m venv venv
source venv/bin/activate            # Windows: .\venv\Scripts\activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
cp .env.example .env                # Windows: copy .env.example .env
python run.py

One-line install scripts

For a quick source install without cloning manually, these download the latest release and set up a local environment. They’re short and readable — open them first (mac, win).

curl -fsSL https://raw.githubusercontent.com/udhawan97/FolioOrb/main/scripts/install-mac.sh | bash

irm https://raw.githubusercontent.com/udhawan97/FolioOrb/main/scripts/install-win.ps1 | iex

Set FOLIO_REF to install a specific v5.16.0 or newer tag, or the dev channel, e.g. curl -fsSL https://raw.githubusercontent.com/udhawan97/FolioOrb/main/scripts/install-mac.sh | FOLIO_REF=latest-main bash on macOS/Linux, or $env:FOLIO_REF = "latest-main" before the Windows command.

Unlike a manual clone, a one-line install stores its entire writable profile outside the replaceable source directory. When upgrading an older source install, the installer uses SQLite’s backup API to migrate the database together with .env, Backup Vault, settings, backup policy, update state, and logs. It also retains the prior install as a recovery copy; if both old and new profile locations already contain data, it stops without choosing or overwriting either one.

Build the desktop installers

The DMG and EXE are produced by PyInstaller plus native installer tooling. You can reproduce a build locally on the matching OS.

# Both platforms: freeze the app (onedir bundle)
python -m pip install -r requirements.txt -r requirements-desktop.txt
python -m PyInstaller packaging/pyinstaller/FolioOrb.spec

# macOS only: repair a PyInstaller BUNDLE quirk that can leave data-only
# directories (static/, templates/, pytz's timezone data) as dangling
# symlinks instead of real files — see the script for the full explanation.
python packaging/pyinstaller/fix_macos_bundle_symlinks.py dist

# Sanity-check the frozen bundle boots
#   macOS:   dist/FolioOrb.app/Contents/MacOS/FolioOrb --smoke
#   Windows: dist\FolioOrb\FolioOrb.exe --smoke

macOS .dmg

brew install create-dmg
mkdir -p dist/dmg-src && cp -R dist/FolioOrb.app dist/dmg-src/
create-dmg \
  --volname "FolioOrb" \
  --volicon packaging/icons/FolioOrb.icns \
  --app-drop-link 390 190 \
  --icon "FolioOrb.app" 150 190 \
  "dist/FolioOrb-macOS-arm64-local.dmg" "dist/dmg-src/"

Windows .exe

choco install innosetup -y
& "${env:ProgramFiles(x86)}\Inno Setup 6\ISCC.exe" `
  /DMyAppVersion=5.16.1 `
  /DMyOutputName=FolioOrb-Windows-x64-local-Setup `
  packaging\windows\installer.iss

Note

CI uses these platform toolchains and adds backup-safety checks, both frozen smoke modes, the macOS compatibility symlink, and release assembly on GitHub-hosted runners — see Releases & versioning. Icons are regenerated from the brand PNG with scripts/make-icons.sh (macOS only) and committed, so a build never needs cross-platform icon tooling.

Useful local URLs

URL	Purpose
http://localhost:8000	Dashboard
http://localhost:8000/docs	Interactive Swagger API docs
http://localhost:8000/health	Health check