Local Deployment (Desktop App)

What This Is

The local deployment packages SourceQuote as a standalone desktop executable for Windows or macOS. It runs as a self-contained application with no external dependencies — no internet connection required, no Firebase authentication, no PostgreSQL. The user is automatically signed in as a single implicit user.

Key characteristics:

• Single-user, no login — authentication is bypassed entirely
• SQLite database — stored at ~/Documents/SourceQuote/source_quote.db
• Local filesystem storage — project files stored in ~/Documents/SourceQuote/projects/
• Offline-capable — all processing runs on the local machine
• Native window — opens in a pywebview window (1400×900, resizable)
• Auto-detects port — picks a free port at startup to avoid conflicts
• Packaged with PyInstaller — produces a single .exe on Windows

Two build variants are available:

Prerequisites: Assumes the development environment is set up as described in ENVIRONMENT_SETUP.md.

1. Configure the Local Environment

Copy the example config files if you haven't already:

cp config/local/.env.local.example config/local/.env.local
cp config/local/.secrets.local.example config/local/.secrets.local

Edit config/local/.secrets.local and fill in:

SECRET_KEY=local-dev-secret-change-me

Any string works for the local build. The file already contains a placeholder.

For local transcription, set your HuggingFace token:

HF_TOKEN=hf_your_token_here

See ENVIRONMENT_SETUP.md § 9 - HuggingFace Token for how to obtain this.

2. Run in Development Mode (Without Building)

Before building the installer, you can run the app directly from source to verify it works.

Set the deploy mode in your shell, then run the server:

Windows PowerShell:

$env:DEPLOY_MODE = "local"
python serve.py

macOS/Linux:

export DEPLOY_MODE=local
python serve.py

Open http://localhost:5000 in your browser. You should see the app without a login screen.

3. Build the Executable

CPU Build (recommended for most users)

npm run build:cpu

Output: build/local-cpu/sourcequote.exe (Windows) or build/local-cpu/sourcequote (macOS/Linux)

GPU Build (NVIDIA GPU required, CUDA 12.4)

npm run build:gpu

Output: build/local-gpu/sourcequote.exe

Both Variants

npm run build

This runs build:cpu followed by build:gpu.

Note: The GPU build requires CUDA 12.4 to be installed on the build machine. The resulting executable will fail at startup on machines without a compatible NVIDIA GPU and CUDA installation.

4. Create the Installer

After building, package the output into a Windows installer:

CPU Installer

npm run installer:cpu

GPU Installer

npm run installer:gpu

Both Installers

npm run installer

Output is placed in the dist/ directory:

dist/
  SourceQuote-v0.5.28-win-x64-cpu/
  SourceQuote-v0.5.28-win-x64-gpu/

5. Running the Built Executable

The packaged executable looks for its config files at the following path relative to the executable:

config/local/.env.local
config/local/.secrets.local

These files must exist beside the executable (or in the installer package) for the app to start. The installer packages them automatically if they are present in the project root at build time.

When the executable runs:

1. It initialises the SQLite database at ~/Documents/SourceQuote/source_quote.db on first launch
2. It opens a native pywebview window pointing to the local Flask server
3. All project files are stored at ~/Documents/SourceQuote/projects/

6. Transcription in Local Mode

On first use of transcription:

• The app downloads Whisper and Pyannote models from HuggingFace (several hundred MB)
• A valid HF_TOKEN must be set in config/local/.secrets.local
• You must have accepted the model licence agreements (see ENVIRONMENT_SETUP.md § 9)

For the CPU build, transcription is slower but works on any machine. For the GPU build, transcription uses the NVIDIA GPU via CUDA. If no compatible GPU is detected at startup, the app shows an error.

Build Command Reference