Skip to content

1. ClioDeck Installation

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

Quick installation guide for ClioDeck across different platforms.

Platform Support

ClioDeck's architecture is designed to be cross-platform and supports:

  • Linux - Fully tested and supported (AppImage and .deb, for x86_64 and arm64)
  • macOS - Fully tested and supported (Intel and Apple Silicon)

Builds are not code-signed: macOS will refuse the app on first launch until you allow it explicitly (see the platform guide below).

Note: While the codebase is designed to run on all platforms, it has not been tested on Windows. It should be installable through a full build. Windows users may encounter issues. Contributions and testing reports are welcome!

Detailed Installation Guides

For complete platform-specific installation instructions, see:

Prerequisites

Before installing ClioDeck, ensure you have:

  • Node.js 20+ and npm 10+
  • Python 3.11+ (for topic modeling services)
  • Pandoc + XeLaTeX (for PDF export)
  • Ollama with models — or skip Ollama entirely and use the small embedded models instead (see below):
    • nomic-embed-text (embeddings, 768 dimensions). mxbai-embed-large is a valid alternative, but ClioDeck does not fall back to it automatically — whichever you pick in Settings is the one used.
    • gemma2:2b (chat - recommended for generation, but cannot use tools — see the note below)

To benefit from the PDF and word export features, installing pandoc and xelatex is necessary.

Fully offline generation, no Ollama: download the embedded generation model (Qwen2.5-0.5B, ~470 MB) from Settings → LLM. A fully offline RAG workflow — embeddings included, not just generation — is available from Settings since RC4, which added an Embeddings section exposing the provider and the embedded model. See the Embedded LLM Guide.

Tool use: gemma2:2b can't call tools (search your corpus, use MCP servers) inside Brainstorm — Ollama only advertises tool support for a specific whitelist (qwen3:8b/14b/32b, ministral-3:8b/14b, mistral-nemo).

Quick Installation

Linux (AppImage)

# Download the AppImage from releases
chmod +x ClioDeck-*.AppImage

# Launch
./ClioDeck-*.AppImage

(scripts/install-desktop.sh exists in the source repository but is not bundled into the AppImage release asset — it's only usable if you've cloned the repo. Note: the .desktop entry it generates launches the AppImage with --no-sandbox, a common AppImage/Electron compatibility workaround — but it does disable Chromium's OS-level sandbox for that launch method specifically, on top of whatever the app's own renderer sandbox: true setting provides. Launching the AppImage directly, as in the command above, does not add this flag.)

Linux (Debian/Ubuntu .deb)

sudo dpkg -i cliodeck_*.deb
sudo apt-get install -f  # Install missing dependencies

macOS (DMG)

# Download DMG from releases
open ClioDeck-*.dmg

# Drag ClioDeck to Applications folder
# First launch: System Preferences → Security & Privacy → Open Anyway

Installing Ollama and Models

Linux

curl -fsSL https://ollama.ai/install.sh | sh
ollama pull nomic-embed-text
ollama pull gemma2:2b

macOS

brew install ollama
brew services start ollama
ollama pull nomic-embed-text
ollama pull gemma2:2b

Building from Source

For developers or if pre-built packages are not available:

# Clone repository
git clone https://github.com/cliodeck/cliodeck-app.git
cd cliodeck-app

# Install dependencies (native modules are rebuilt for Electron's ABI
# automatically by the postinstall script — no separate step needed)
npm install

# Build the application
npm run build

# Launch in development mode
npm start

# Or build packages for distribution
npm run build:linux    # AppImage + .deb
npm run build:mac      # DMG (x64 + arm64)
npm run build:win      # NSIS installer (untested)

See Build and Deployment Guide for complete build instructions.

First Launch Configuration

The first time you open Settings, ClioDeck checks the Ollama connection (http://localhost:11434) — this happens when the Settings panel mounts, not automatically at app launch.

Creating a project will create project structure in your chosen folder and initialize .cliodeck/brain.db — the shared SQLite store for PDF vectors, Tropy primary sources, and research history.

Configure in Settings:

  • LLM backend (Ollama URL and models)
  • RAG parameters (topK, similarity threshold)
  • Zotero integration (optional)
  • Download the embedded model (for small configs)
  • Install the BERTopic venv
  • Choose language (French / English / German)

Troubleshooting

Ollama not responding

# Check if Ollama is running
curl http://localhost:11434/api/tags

# Start Ollama manually if needed
ollama serve

Native module errors (better-sqlite3, hnswlib-node)

# Rebuild native modules for your platform
cd /path/to/cliodeck-app
npm run rebuild:native

Missing Pandoc or XeLaTeX

PDF export requires both Pandoc and XeLaTeX. See platform-specific guides for installation instructions.

Getting Help

Uninstallation

Linux (AppImage)

rm ~/.local/share/applications/cliodeck.desktop
rm -rf ~/.local/share/icons/hicolor/*/apps/cliodeck.png
update-desktop-database ~/.local/share/applications/

Linux (.deb)

sudo apt remove cliodeck

macOS

rm -rf /Applications/ClioDeck.app
rm -rf ~/Library/Application\ Support/cliodeck

Note: Your project data (.md files, PDFs, .cliodeck/ folders) is stored in your project directories and is not automatically deleted during uninstallation.

Clone this wiki locally