Environment Setup

What is SourceQuote?

SourceQuote is a self-hosted audio transcription, editing, and review platform. It supports waveform-synchronized editing, multi-speaker labeling, collaborative sharing, and public embeds. The same codebase supports three distinct deployment targets:

• Local mode — A single-user desktop application packaged as a Windows/macOS executable. No authentication, no server, offline-capable. Uses SQLite for storage.
• Server mode — A self-hosted web server (Flask + PostgreSQL + Caddy). Supports multiple users, Firebase authentication, and optional Stripe payments.
• Cloud mode — A fully managed deployment on Google Cloud Run, backed by Cloud SQL, Google Cloud Storage, and Secret Manager. Auto-scales, requires no infrastructure management.

This guide covers everything needed to get a working development environment from a fresh clone, regardless of which deployment target you intend to use.

Prerequisites

Install the following tools before proceeding.

Required for all modes

Windows (winget):

winget install Git.Git
winget install Python.Python.3.12
winget install OpenJS.NodeJS.LTS
winget install Gyan.FFmpeg

After installing, restart your terminal so PATH changes take effect. Verify with git --version, python --version, node --version, and ffmpeg -version.

macOS:

brew install git python@3.12 node ffmpeg

Linux:

sudo apt install git python3.12 nodejs npm ffmpeg

Required for server and cloud modes

Windows (winget):

winget install PostgreSQL.PostgreSQL

macOS:

brew install postgresql@15

Linux:

sudo apt install postgresql-15

The default Windows install path C:\Program Files\PostgreSQL\<version>\ is assumed by database\build.bat. After installing, ensure psql is on your PATH.

Installing Caddy:

Windows (winget):

winget install CaddyServer.Caddy

macOS:

brew install caddy

Linux:

sudo apt install caddy

Required for local desktop installer builds (Windows only)

These are only needed to run npm run installer. The npm run build step (PyInstaller) does not need them.

winget install 7zip.7zip
winget install JRSoftware.InnoSetup

Required for GPU desktop builds

Download from developer.nvidia.com/cuda-12-4-0-download-archive. An NVIDIA GPU with a compatible driver must also be present.

Required for cloud mode only

Windows (winget):

winget install Google.CloudSDK
winget install Docker.DockerDesktop

macOS:

brew install --cask google-cloud-sdk docker

Linux:

# gcloud — see https://cloud.google.com/sdk/docs/install for distro-specific steps
# Docker
sudo apt install docker.io

After installing gcloud, run gcloud auth login and gcloud config set project YOUR_PROJECT_ID before using any cloud deploy commands.

1. Clone the Repository

git clone https://gitlab.com/vtleavs/sourcequote.git
cd sourcequote

2. Python Virtual Environment

Create and activate a virtual environment to isolate dependencies.

python -m venv .venv

Activate (Windows PowerShell):

.venv\Scripts\Activate.ps1

Activate (Windows CMD):

.venv\Scripts\activate.bat

Activate (macOS/Linux):

source .venv/bin/activate

Verify activation — the prompt should show (.venv).

3. Install Python Dependencies

There are three requirements files depending on your target:

For local and server development (most developers):

pip install -r requirements-cpu.txt

For GPU-accelerated local transcription (requires NVIDIA GPU + CUDA 12.4):

pip install -r requirements-gpu.txt

For cloud mode development:

pip install -r requirements-gcp.txt

4. Install Node.js Dependencies

npm install

This installs the JavaScript toolchain used for linting, testing, docs generation, and desktop builds.

5. Set Up Configuration Files

Configuration is split by deployment mode. Each mode has a .env file (non-secret settings) and a .secrets file (credentials and API keys — never committed to version control).

Copy the example files for the mode(s) you intend to use:

Local mode:

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

Server mode:

cp config/server/.env.server.example config/server/.env.server
cp config/server/.secrets.server.example config/server/.secrets.server

Cloud mode:

cp config/cloud/.env.cloud.example config/cloud/.env.cloud
cp config/cloud/.secrets.cloud.example config/cloud/.secrets.cloud

The .secrets.* files are listed in .gitignore and must never be committed.

6. Generate a Flask Secret Key

Required for server and cloud modes. Skip for local mode (a placeholder is already in the example file).

python -c "import secrets; print(secrets.token_hex(32))"

Copy the output into the SECRET_KEY field of your .secrets.server or .secrets.cloud file.

7. Set Up Firebase (Server and Cloud Modes Only)

Firebase provides authentication. Local mode does not use it.

7a. Create a Firebase Project

1. Go to the Firebase Console
2. Click Add project and follow the prompts
3. Enable Authentication → Sign-in method → choose your providers (Email/Password and/or Google)

7b. Get the Web API Key and Auth Domain

1. In the Firebase Console, go to Project Settings → General
2. Under Your apps, click Add app → Web if you haven't already
3. Copy the values for:
   • apiKey → FIREBASE_API_KEY
   • authDomain → FIREBASE_AUTH_DOMAIN
   • projectId → FIREBASE_PROJECT_ID

Paste these into your .env.server or .env.cloud file.

7c. Download the Service Account Key

This is the backend credential that verifies Firebase JWT tokens.

1. Firebase Console → Project Settings → Service Accounts
2. Click Generate new private key
3. Save the downloaded JSON file somewhere safe (e.g., config/server/firebase-service-account.json)
4. Set FIREBASE_SERVICE_ACCOUNT in your .secrets.server or .secrets.cloud to the path of that file

8. Set Up PostgreSQL (Server and Cloud Modes Only)

8a. Create the database

createdb transcriber

Or using psql:

CREATE DATABASE transcriber;

8b. Build the schema

Windows:

database\build.bat -h localhost -p 5432 -U postgres

macOS/Linux:

./database/build.sh -h localhost -p 5432 -U postgres

This runs base_schema.sql and all migration files in order. It is safe to re-run on a fresh database.

8c. Set the connection string

In your .secrets.server or .secrets.local file, set:

DATABASE_URL=postgresql://postgres:yourpassword@localhost:5432/transcriber

9. External API Keys

The following keys are optional depending on the features you need.

HuggingFace Token (for local transcription)

Required to download Whisper and Pyannote models the first time transcription is used.

1. Create an account at huggingface.co
2. Go to Settings → Access Tokens and create a token with Read access
3. Accept the licence agreements for:
   • pyannote/speaker-diarization-3.1
   • pyannote/segmentation-3.0
4. Set HF_TOKEN in your .secrets.* file

Modal.com Token (for cloud-based transcription)

Required if you want transcription routed through Modal.com instead of running locally.

1. Create an account at modal.com
2. Go to Settings → API tokens and create a new token
3. Set MODAL_TOKEN_ID in your .env.* file (not secret)
4. Set MODAL_TOKEN_SECRET in your .secrets.* file

Stripe Keys (for subscription payments — optional)

1. Create an account at stripe.com
2. Go to Developers → API keys
3. Use test keys (sk_test_..., pk_test_...) during development
4. Set STRIPE_SECRET_KEY and STRIPE_PUBLISHABLE_KEY in your .secrets.* file
5. For webhook verification (required for subscription events):
   • Install the Stripe CLI
   • Run stripe listen --forward-to localhost:5000/api/stripe/webhook
   • Copy the whsec_... secret it prints into STRIPE_WEBHOOK_SECRET

GitLab Token (for bug reporting — optional)

Used to automatically create GitLab issues from in-app bug reports.

1. In GitLab, go to User Settings → Access Tokens
2. Create a token with the api scope
3. Set GITLAB_TOKEN in your .secrets.* file
4. Set GITLAB_PROJECT_ID in your .env.* file

SMTP Credentials (for email notifications — optional)

Used to send admin notifications (new user registrations, error alerts).

• Set SMTP_HOST, SMTP_PORT, SMTP_USER, SMTP_FROM, SMTP_FROM_NAME in your .env.* file
• Set SMTP_PASS in your .secrets.* file
• For Gmail: generate an App Password at Google Account → Security → 2-Step Verification → App passwords and use that as SMTP_PASS

10. Verify the Setup

Run the test suite to confirm everything is working:

npm test

Or run backend and frontend tests individually:

npm run test:backend
npm run test:frontend

Summary of Config Files

Never commit any .secrets.* file.