Skip to content

2.1 Build and Deployment Guide

Jump to bottom
Frédéric Clavert edited this page Jul 23, 2026 · 16 revisions

This document explains how to compile, package, and deploy ClioDeck for different platforms.

Table of Contents

Technical Stack

Frontend

  • Electron 40 - Multi-platform desktop
  • React 18 - UI components
  • TypeScript 5 - Type safety
  • CodeMirror 6 - Markdown editor with live rendering
  • Zustand - State management
  • Vite - Build tool

Backend

  • Node.js 20+ - JavaScript runtime
  • better-sqlite3 - SQLite database (vector store)
  • pdfjs-dist - PDF extraction
  • electron-store - Config persistence
  • Python 3.11+ - Analysis services (topic modeling)

LLM & AI

  • A typed provider registry — Ollama, embedded (node-llama-cpp), Anthropic, OpenAI-compatible, Mistral, Gemini — for both generation and embeddings, selected independently
    • Ollama embedding model: nomic-embed-text (768 dimensions) or mxbai-embed-large (not an automatic fallback — an independent choice)
    • Ollama chat model: gemma2:2b (fast, multilingual, but not tool-capable) or any chat model Ollama can run
    • Embedded (no Ollama needed): Qwen2.5-0.5B/1.5B for generation, Nomic Embed Text v2 MoE for embeddings — a full offline RAG workflow needs neither Ollama nor a cloud key
  • BERTopic - Topic modeling and clustering (Python)

Prerequisites

Development

  • Node.js 20+ and npm 10+
  • Python 3.11+ (for better-sqlite3 and Python services)
  • Ollama installed locally for testing (or the embedded model, or a cloud provider — see Embedded LLM Guide)

Platform-Specific

Linux:

sudo apt-get install build-essential python3-dev

macOS:

xcode-select --install

Windows:

  • Visual Studio Build Tools or Visual Studio Community
  • Python 3.11+ with pip

Installation

Installing Dependencies

npm install

This command installs all Node.js dependencies and automatically compiles native modules (better-sqlite3, hnswlib-node, etc.).

Installing Python Dependencies (Topic Modeling)

Python services are used for topic modeling. For the development environment:

cd backend/python-services/topic-modeling
python3 -m venv .venv
source .venv/bin/activate  # Linux/macOS
# Or: .venv\Scripts\activate  # Windows

pip install -r requirements.txt

Development

Development Mode with Hot Reload

npm run dev

This command launches in parallel:

  • Main process TypeScript in watch mode
  • Preload script in watch mode
  • Renderer (React) with Vite hot reload

Start the Application

In another terminal:

npm start

Full Development Mode (All-in-One)

npm run dev:full

Launches build watch AND the application automatically after 3 seconds.

Tests

# Run once
npm test

# Watch mode
npm run test:watch

# With UI
npm run test:ui

# With coverage
npm run test:coverage

Linting and Type Checking

# Linter
npm run lint

# Type checking
npm run typecheck

Build and Packaging

Build Without Packaging

npm run build

Compiles:

  • Main process TypeScript → dist/src/main/
  • Preload script → dist/src/preload/
  • Renderer React → dist/src/renderer/

Build with Packaging

All Platforms

npm run build:all

Creates installers for all platforms configured in package.json.

Specific Platforms

# Linux (AppImage + deb)
npm run build:linux

# macOS (DMG for Intel and Apple Silicon)
npm run build:mac

# Windows (NSIS installer)
npm run build:win

macOS Build by Architecture

# Intel only
npm run build:mac-intel

# Apple Silicon only
npm run build:mac-arm

# Universal (Intel + Apple Silicon)
npm run build:mac-universal

Build Without Installer (for Testing)

npm run build:dir

Creates an unpackaged executable folder in release/.

Build Structure

cliodeck-app/
├── dist/                    # Compiled code
│   ├── src/
│   │   ├── main/           # Main process JS
│   │   ├── preload/        # Preload script JS
│   │   └── renderer/       # React build
├── release/                # Installers, named after the current package.json version
│   ├── ClioDeck-<version>-arm64.AppImage   # Linux (arm64 only, currently)
│   ├── ClioDeck-<version>.dmg              # macOS
│   └── cliodeck_<version>_arm64.deb        # Linux
└── build/                  # Packaging assets
    ├── icon.png
    ├── icon.icns
    └── icon.ico

No Windows entry: npm run build:win exists but no Windows build has ever been published (untested — see User Installation below).

Cross-Platform Packaging

Linux → all OS: Possible with Docker:

docker run --rm -v $(pwd):/project electronuserland/builder:wine \
  bash -c "cd /project && npm install && npm run build:all"

macOS → macOS/Linux/Windows: macOS can build for all platforms natively.

Windows → Windows only: Windows can only build for Windows.

User Installation

User Prerequisites

  1. Ollama installed on the machine
  2. Models downloaded: 
    ollama pull nomic-embed-text
ollama pull gemma2:2b

Linux

AppImage (recommended):

# Download the current release from GitHub Releases (filename includes the
# version and, currently, an arm64 suffix — check the Releases page for the
# exact name, e.g. ClioDeck-1.0.0-rc.3-arm64.AppImage)
wget https://github.com/cliodeck/cliodeck-app/releases/download/v1.0.0-rc.3/ClioDeck-1.0.0-rc.3-arm64.AppImage -O ClioDeck.AppImage

# Make executable
chmod +x ClioDeck.AppImage

# Launch
./ClioDeck.AppImage

Debian/Ubuntu (.deb):

sudo dpkg -i cliodeck_1.0.0-rc.3_arm64.deb
sudo apt-get install -f  # Fix dependencies if necessary
cliodeck

macOS

  1. Download the DMG file from GitHub Releases
  2. Double-click to mount the disk image
  3. Drag ClioDeck to the Applications folder
  4. Launch from Launchpad or Applications

First launch: If macOS displays "app cannot be opened because it is from an unidentified developer":

xattr -cr /Applications/ClioDeck.app

Or: Right-click → Open → Confirm

Windows

No Windows build is currently published. npm run build:win exists and the code should work on Windows, but this is untested — there is no ClioDeck-Setup-*.exe on the Releases page as of v1.0.0-rc.3. Build from source (see Build and Packaging) if you want to try it.

Initial Configuration

1. Verify Ollama

On first launch, ClioDeck automatically checks the Ollama connection.

If Ollama is not detected:

  1. Install Ollama: https://ollama.ai/download

  2. Start the service:

    # Linux/macOS
ollama serve

# Windows: Ollama starts automatically as a service

  3. Verify the service is working:

    curl http://localhost:11434/api/tags

2. Download Models

# Embedding model (REQUIRED)
ollama pull nomic-embed-text

# Chat model (RECOMMENDED)
ollama pull gemma2:2b

# Chat alternatives
ollama pull mistral:7b-instruct    # More accurate but heavier

# Tool-capable alternatives (needed if you want Brainstorm to search your
# corpus on its own — gemma2:2b and the Llama 3.x/4.x families cannot):
ollama pull qwen3:8b

3. Zotero Configuration (optional)

To sync with Zotero:

  1. Get an API key:

  2. Configure in ClioDeck:

    • Settings → Zotero Integration
    • User ID: your Zotero user ID (visible in your library URL)
    • API Key: paste the key
    • Test Connection to verify

  3. Sync:

    • Select a Zotero collection
    • Click "Sync"
    • Wait for PDFs and BibTeX file download

Common Issues

Development

"Incompatible architecture" error on macOS

Symptom:

mach-o file, but is an incompatible architecture (have 'arm64', need 'x86_64')

Cause: Native modules (better-sqlite3, hnswlib-node) are compiled for the wrong architecture.

Solution:

# Rebuild for your architecture
npm run rebuild:native

# Or specifically:
npm run rebuild:x64      # Intel
npm run rebuild:arm64    # Apple Silicon

npm run rebuild:native runs electron-builder install-app-deps, which handles this — there is no separate after-pack script in the repo.

better-sqlite3 doesn't compile

npm rebuild better-sqlite3 --build-from-source

If the issue persists, verify that Python and build tools are installed.

hnswlib-node doesn't compile

# Install C++ build tools
# macOS:
xcode-select --install

# Linux:
sudo apt-get install build-essential

# Then:
npm rebuild hnswlib-node --build-from-source

Python topic modeling service doesn't start

Port already in use:

# Kill process on port 8001
lsof -ti:8001 | xargs kill -9

Missing Python dependencies:

cd backend/python-services/topic-modeling
source .venv/bin/activate
pip install -r requirements.txt

Production

Ollama doesn't start

Linux:

# Check status
systemctl status ollama

# Start manually
ollama serve

macOS:

# Check if process is running
ps aux | grep ollama

# Start manually
ollama serve

Windows:

# Open services.msc
# Check "Ollama" service

Slow embeddings

  1. Use CPU optimized config:

    • Settings → RAG → Chunking: CPU Optimized

  2. Reduce topK:

    • Settings → RAG → Top K: 5 (instead of 10)

  3. Use a lighter model:

    ollama pull gemma2:2b  # Instead of mistral:7b

Chat doesn't respond

  1. Check Ollama:

    curl http://localhost:11434/api/tags

  2. Verify chat model is installed:

    ollama list

  3. Change model:

    • Settings → LLM → Chat Model
    • Select an installed model

Poorly indexed PDFs

Empty extracted text:

  • The PDF is image-only (no selectable text)
  • Solution: Use external OCR then reimport

Poor extraction quality:

  • The PDF is poorly formatted or corrupted
  • Check the PDF in an external reader

Zotero sync fails

  1. Verify API key is valid
  2. Verify User ID is correct
  3. Check internet connection
  4. Check logs for more details

Debug Logs

ClioDeck does not currently write logs to a file — output goes to the console only. Launch the app from a terminal (or npm start in development) to see it. See the Logging System page for the two separate loggers (renderer vs main process) and their env-var behavior.

Distribution and Releases

Code Signing (Production)

macOS

  1. Get an Apple Developer certificate
  2. Configure in package.json:
{
  "build": {
    "mac": {
      "identity": "Developer ID Application: Your Name (TEAM_ID)"
    }
  }
}
  1. Build with signing:
CSC_NAME="Developer ID Application" npm run build:mac

Windows

  1. Get a code signing certificate
  2. Configure and build:
set CSC_LINK=path/to/cert.pfx
set CSC_KEY_PASSWORD=your_password
npm run build:win

GitHub Releases

  1. Create a version tag:
git tag v1.0.0
git push origin v1.0.0
  1. Build and publish:
GH_TOKEN=your_github_token npm run build:all

electron-builder can automatically publish to GitHub Releases if a publish block is configured — package.json does not currently have one; releases are attached to tags manually today. If you add one, point it at cliodeck/cliodeck-app (the current repository — the project moved from inactinique/cliodeck, now archived).

Environment Variables

Build:

  • CSC_LINK: Path to signing certificate
  • CSC_KEY_PASSWORD: Certificate password
  • GH_TOKEN: GitHub token for releases
  • DEBUG: Enable electron-builder debug logs

Runtime:

Performance and Optimization

Recommended Hardware Configuration

Minimum:

  • CPU: Dual-core
  • RAM: 4 GB
  • Disk: 5 GB free

Recommended:

  • CPU: Quad-core
  • RAM: 8 GB
  • Disk: 10 GB free

Optimal:

  • CPU: 8+ cores
  • RAM: 16 GB
  • Disk: 20 GB free (for Ollama models)

Installer Sizes

As of v1.0.0-rc.3:

  • Linux AppImage (arm64): ~262 MB
  • Linux deb (arm64): ~158 MB
  • macOS DMG: ~263-268 MB
  • Windows: not built (no release published)

Disk Space per Project

  • App: ~200 MB
  • Ollama models: ~500 MB - 5 GB (depending on models)
  • Vector database: 50-500 MB per project (depending on PDF count)
  • Research journal: 1-5 MB per session, 50-200 MB for a long project

Security and Privacy

Local Data

All data remains local:

  • PDFs and documents: stored in project folder
  • Embeddings and indexes: local SQLite (.cliodeck/brain.db)
  • LLM and models: local Ollama, the embedded model, or whichever cloud provider you configure (see Technical Stack above)

No data is sent to external servers (except if Zotero API is configured for sync).

API Key Storage

Zotero API Key:

  • Stored in electron-store (OS-provided encryption)
  • Linux: GNOME Keyring / KWallet
  • macOS: Keychain
  • Windows: Credential Manager

Useful Scripts

# Full cleanup
npm run clean

# Reinstall all dependencies
rm -rf node_modules package-lock.json
npm install

# Rebuild native modules
npm run rebuild:native

# Check types
npm run typecheck

# Linter
npm run lint

# Build preview
npm run preview

Resources

Note for daily development: Simply use npm run dev in one terminal and npm start in another.

Clone this wiki locally