Skip to content

1. ClioDeck Installation

Jump to bottom
inactinique edited this page Feb 9, 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
  • macOS - Fully tested and supported (Intel and Apple Silicon)

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:
    • nomic-embed-text (embeddings - primary, 768 dimensions)
    • mxbai-embed-large (embeddings - fallback, used if nomic unavailable)
    • gemma2:2b (chat - recommended for generation)

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

Quick Installation

Linux (AppImage)

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

# Optional: Install to applications menu
./scripts/install-desktop.sh ClioDeck-*.AppImage

# Launch
./ClioDeck-*.AppImage

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/inactinique/cliodeck.git
cd cliodeck

# Install dependencies
npm install

# Rebuild native modules for Electron
npx electron-rebuild -f

# 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

On first launch, ClioDeck will check Ollama connection (http://localhost:11434)

Creating a project will create project structure in your chosen folder and initialize vector databases:

  • .cliodeck/vectors.db for PDFs (secondary sources)
  • .cliodeck/primary-sources.db for Tropy sources (if used)

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
npx electron-rebuild -f

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
rm -rf ~/Library/Logs/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