Skip to content
FolioOrb

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

Section titled “Run from source”
Terminal window
git clone https://github.com/udhawan97/FolioOrb.git
cd FolioOrb
./scripts/setup.sh

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).

Manual setup

Section titled “Manual setup”
Terminal window
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

Section titled “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).

Terminal window
curl -fsSL https://raw.githubusercontent.com/udhawan97/FolioOrb/main/scripts/install-mac.sh | bash
Terminal window
irm https://raw.githubusercontent.com/udhawan97/FolioOrb/main/scripts/install-win.ps1 | iex

Set FOLIO_REF to install a specific tag or the dev channel, e.g. FOLIO_REF=latest-main.

Build the desktop installers

Section titled “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.

Terminal window
# 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
Terminal window
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/"

Useful local URLs

Section titled “Useful local URLs”
URL Purpose
http://localhost:8000 Dashboard
http://localhost:8000/docs Interactive Swagger API docs
http://localhost:8000/health Health check