Skip to content

1.1 ClioDeck Installation ‐ Linux

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

This guide walks you through the complete installation of ClioDeck on Linux, from prerequisites to first launch.

Table of Contents

System Requirements

  • Distribution: Ubuntu 20.04+ (tested), should work on Debian 11+, Fedora 35+, Arch Linux, or compatible
  • Architecture: the current release (v1.0.0-rc.3) ships arm64 only (AppImage and .deb). On x86_64, build from source (see below) — the code itself is architecture-independent.
  • Disk Space: At least 5 GB free (for application, Ollama models, python and dependencies, tex-live for XeLaTeX, pandoc)
  • Memory: 8 GB RAM minimum, 16 GB recommended
  • System Libraries: libgtk-3, libnotify, libnss3, libxss1, libxtst6, xdg-utils, libatspi2.0

Installing Dependencies

1. Basic System Dependencies

Ubuntu/Debian

sudo apt update
sudo apt install -y \
  curl \
  wget \
  git \
  build-essential \
  libgtk-3-0 \
  libnotify4 \
  libnss3 \
  libxss1 \
  libxtst6 \
  xdg-utils \
  libatspi2.0-0 \
  libsecret-1-0 \
  libgbm1 \
  pandoc \
  texlive-xetex \
  texlive-fonts-recommended \
  texlive-lang-french

Note: Pandoc and XeLaTeX are required for PDF export from ClioDeck.

Fedora/RHEL/CentOS

sudo dnf install -y \
  curl \
  wget \
  git \
  gcc-c++ \
  make \
  gtk3 \
  libnotify \
  nss \
  libXScrnSaver \
  libXtst \
  xdg-utils \
  at-spi2-core \
  libsecret \
  mesa-libgbm \
  pandoc \
  texlive-xetex \
  texlive-collection-fontsrecommended \
  texlive-babel-french

Arch Linux

sudo pacman -Syu --needed \
  curl \
  wget \
  git \
  base-devel \
  gtk3 \
  libnotify \
  nss \
  libxss \
  libxtst \
  xdg-utils \
  at-spi2-core \
  libsecret \
  mesa \
  pandoc \
  texlive-core \
  texlive-fontsrecommended \
  texlive-lang

2. Node.js and npm

ClioDeck requires Node.js 20+ and npm 10+.

Method 1: Via NodeSource (recommended)

Ubuntu/Debian:

# Install NodeSource repository for Node.js 20
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -

# Install Node.js and npm
sudo apt install -y nodejs

# Verify versions
node --version  # Should show v20.x.x or higher
npm --version   # Should show 10.x.x or higher

Fedora/RHEL/CentOS:

# Install NodeSource repository for Node.js 20
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -

# Install Node.js and npm
sudo dnf install -y nodejs

# Verify versions
node --version
npm --version

Arch Linux:

# Node.js 20+ is available in official repositories
sudo pacman -S nodejs npm

# Verify versions
node --version
npm --version

Method 2: Via nvm (Node Version Manager)

Useful for managing multiple Node.js versions:

# Install nvm
curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.7/install.sh | bash

# Reload your shell
source ~/.bashrc  # or ~/.zshrc if using zsh

# Install Node.js 20
nvm install 20
nvm use 20
nvm alias default 20

# Verify
node --version
npm --version

3. Python 3

ClioDeck uses Python for certain services (topic modeling). Python 3.11+ is required.

Ubuntu/Debian

# Check if Python 3.11+ is installed
python3 --version

# If necessary (Ubuntu 22.04+, Debian 12+)
sudo apt install -y python3 python3-pip python3-venv

# For Ubuntu 20.04/Debian 11, install from deadsnakes PPA
sudo apt install software-properties-common
sudo add-apt-repository ppa:deadsnakes/ppa
sudo apt update
sudo apt install python3.11 python3.11-venv python3.11-dev

Fedora/RHEL/CentOS

# Python 3.11+ should be available
sudo dnf install -y python3 python3-pip python3-devel

# Verify
python3 --version

Arch Linux

# Python 3.12+ is in repositories
sudo pacman -S python python-pip

# Verify
python --version

Note: The Python virtual environment (venv) will be created by ClioDeck if user asks for it (Settings).

4. Ollama (Local LLM)

Ollama is required for local AI features (embeddings and chat).

Automatic Installation (all distributions)

# Install Ollama
curl -fsSL https://ollama.ai/install.sh | sh

This script:

  • Downloads and installs Ollama in /usr/local/bin/
  • Creates a systemd service ollama.service
  • Automatically starts the service

Manual Installation

Ubuntu/Debian/Fedora/RHEL:

# Download binary
curl -L https://ollama.ai/download/ollama-linux-amd64 -o ollama
chmod +x ollama
sudo mv ollama /usr/local/bin/

# Create systemd service
sudo tee /etc/systemd/system/ollama.service > /dev/null <<EOF
[Unit]
Description=Ollama Service
After=network-online.target

[Service]
ExecStart=/usr/local/bin/ollama serve
User=ollama
Group=ollama
Restart=always
RestartSec=3

[Install]
WantedBy=default.target
EOF

# Create ollama user
sudo useradd -r -s /bin/false -m -d /usr/share/ollama ollama

# Start service
sudo systemctl daemon-reload
sudo systemctl enable ollama
sudo systemctl start ollama

Arch Linux:

# Via AUR
yay -S ollama

# Or from source
git clone https://aur.archlinux.org/ollama.git
cd ollama
makepkg -si

# Start service
sudo systemctl enable --now ollama

Verify Ollama Service

# Check status
systemctl status ollama

# Verify server responds
curl http://localhost:11434/api/tags

Download Required Models

# Embedding model (required for RAG search)
ollama pull nomic-embed-text

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

mxbai-embed-large is a valid alternative embedding model, but it is not an automatic fallback — ClioDeck does not switch between the two on its own; whichever one you pick in Settings → LLM is the one used.

Note on tool use: gemma2:2b cannot call tools (search your corpus, use MCP servers) inside Brainstorm — Ollama only advertises tool support for a specific model whitelist. If you want the assistant to search your corpus on its own, pull a tool-capable model instead:

ollama pull qwen3:8b   # or ministral-3:8b / ministral-3:14b / mistral-nemo

Verification:

# List installed models
ollama list

# Should show at minimum:
# nomic-embed-text
# gemma2:2b

Installing ClioDeck

Option A: Installation from Binaries (User)

Grab the current release from the Releases page — as of v1.0.0-rc.3 that's an arm64 AppImage and .deb (no .rpm is built; Fedora/RHEL/Arch users should use the AppImage, or build from source on x86_64).

AppImage (works on all distributions)

# Replace the filename with whatever the current release actually publishes
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

System integration (optional):

# Move to standard location
mkdir -p ~/.local/bin
mv ClioDeck.AppImage ~/.local/bin/cliodeck

# Create desktop menu entry
mkdir -p ~/.local/share/applications
cat > ~/.local/share/applications/cliodeck.desktop <<EOF
[Desktop Entry]
Name=ClioDeck
Comment=Writing assistant for historians
Exec=$HOME/.local/bin/cliodeck %U
Icon=cliodeck
Terminal=false
Type=Application
Categories=Office;TextEditor;
MimeType=text/markdown;
EOF

# Update applications cache
update-desktop-database ~/.local/share/applications

.deb Package (Ubuntu/Debian)

# Replace the filename with whatever the current release actually publishes
wget https://github.com/cliodeck/cliodeck-app/releases/download/v1.0.0-rc.3/cliodeck_1.0.0-rc.3_arm64.deb

# Install
sudo dpkg -i cliodeck_1.0.0-rc.3_arm64.deb

# Resolve missing dependencies (if necessary)
sudo apt-get install -f

# Launch
cliodeck

Option B: Installation from Source (Developer)

To contribute to the project or run the development version:

  1. Clone the repository

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

  2. Install npm dependencies

    Native modules (better-sqlite3, hnswlib-node) are automatically rebuilt for Electron's ABI by the postinstall script — no separate compile step needed:

    npm install

  3. Build the project

    npm run build

  4. Launch in development mode

    # Method 1: All in one
npm run dev:full

# Method 2: Separate (for development)
# Terminal 1: Compile in watch mode
npm run dev

# Terminal 2: Launch application
npm start

  5. Build application for distribution

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

# Files land in release/, named after the current package.json version

Initial Configuration

On first ClioDeck launch:

1. Ollama Verification

ClioDeck automatically checks the connection to Ollama (http://localhost:11434).

If connection fails:

# Check service status
systemctl status ollama

# Restart if necessary
sudo systemctl restart ollama

# Verify port 11434 is open
curl http://localhost:11434/api/tags

2. LLM Configuration

  1. Open Settings → LLM Configuration
  2. Verify settings:
    • Backend: Ollama (default)
    • URL: http://localhost:11434
    • Embedding Model: nomic-embed-text
    • Chat Model: gemma2:2b
  3. Click Test Connection to validate

3. Create Your First Project

  1. New Project → choose a folder and a project type: article (a single document.md), book (chapters as separate files under chapters/), or presentation (slides.md).
  2. ClioDeck creates the structure (article example): 
    my-project/
├── project.json            # Project manifest and settings
├── document.md             # Your text (byte-for-byte, no internal conversion)
├── context.md              # Subject, period, conventions — given to the assistant
└── .cliodeck/
    ├── config.json         # Provider/workspace config
    ├── vectors.db          # PDF vector index
    └── hints.md            # Workspace house rules (optional)
    A book project has no document.md — its chapters live under chapters/, listed in project.json.

4. Zotero Configuration (optional)

If you use Zotero:

  1. Get your API Key: https://www.zotero.org/settings/keys/new
    • Permissions: "Read library" and "Write library"
  2. In ClioDeck: Settings → Zotero Integration
  3. Enter your User ID and API Key
  4. Test Connection

Verifying Installation

Complete Test

  1. Verify Ollama

    # Check service
systemctl status ollama

# Test API
curl http://localhost:11434/api/tags
# Should return list of installed models

  2. Verify Node.js and npm

    node --version  # v20.x.x or higher
npm --version   # 10.x.x or higher

  3. Verify Python

    python3 --version  # 3.11.x or higher

  4. Verify Pandoc and XeLaTeX

    pandoc --version   # 2.x or higher
xelatex --version  # TeX Live 2020+ or higher

  5. Test ClioDeck

    • Create a new project
    • Add a PDF to your bibliography (Zotero import, or drag-and-drop)
    • Index it via the interface
    • Verify corpus displays statistics

Check Logs

ClioDeck does not currently write logs to a file — output goes to the console only. Launch it from a terminal to see it:

# AppImage
./ClioDeck.AppImage

# Installed via .deb
cliodeck

Troubleshooting

Problem: Ollama doesn't respond

# Check if Ollama is running
systemctl status ollama

# Restart service
sudo systemctl restart ollama

# Check logs
sudo journalctl -u ollama -n 50

# Test manually
ollama serve

Problem: "Module did not self-register" (better-sqlite3)

This means the native module wasn't compiled for Electron.

cd /path/to/cliodeck-app

# Recompile native modules for Electron's ABI
npm run rebuild:native

# Relaunch
npm start

Problem: AppImage doesn't launch

# Check FUSE dependencies
# Ubuntu/Debian
sudo apt install libfuse2

# Fedora/RHEL
sudo dnf install fuse-libs

# Arch Linux
sudo pacman -S fuse2

# Make AppImage executable
chmod +x ClioDeck.AppImage

# Launch with --no-sandbox if necessary
./ClioDeck.AppImage --no-sandbox

Problem: Python venv doesn't create

Verify Python 3 and venv are properly installed:

python3 --version
python3 -m venv --help

# Ubuntu/Debian: Install python3-venv if missing
sudo apt install python3-venv

# Fedora/RHEL
sudo dnf install python3-devel

# Arch Linux
sudo pacman -S python

Problem: "cannot open shared object file" error

System libraries are probably missing:

# Check missing dependencies
ldd /path/to/cliodeck

# Ubuntu/Debian: Reinstall dependencies
sudo apt install --reinstall \
  libgtk-3-0 libnotify4 libnss3 libxss1 \
  libxtst6 xdg-utils libatspi2.0-0 libsecret-1-0 libgbm1

# Fedora/RHEL
sudo dnf reinstall \
  gtk3 libnotify nss libXScrnSaver \
  libXtst xdg-utils at-spi2-core libsecret mesa-libgbm

Problem: Insufficient memory for models

Ollama models consume RAM:

  • nomic-embed-text: ~1 GB
  • gemma2:2b: ~2 GB
  • mistral:7b-instruct: ~4 GB

Solutions:

  • Close unused applications
  • Use only gemma2:2b (avoid mistral:7b-instruct)
  • Skip Ollama entirely: ClioDeck can also run on a small embedded model (Qwen2.5-0.5B, ~470 MB, downloaded from Settings → LLM) with no separate service to keep running
  • Add swap: 
    # Create 4GB swap file
sudo fallocate -l 4G /swapfile
sudo chmod 600 /swapfile
sudo mkswap /swapfile
sudo swapon /swapfile

# Make permanent
echo '/swapfile none swap sw 0 0' | sudo tee -a /etc/fstab

Problem: Port 11434 already in use

If another service uses port 11434:

# Identify process
sudo lsof -i :11434

# Option 1: Stop other service

# Option 2: Configure Ollama on another port
sudo systemctl edit ollama

# Add:
[Service]
Environment="OLLAMA_HOST=127.0.0.1:11435"

# Restart
sudo systemctl daemon-reload
sudo systemctl restart ollama

# Then in ClioDeck Settings → LLM → URL: http://localhost:11435

Problem: Electron Sandbox (Wayland)

On some distributions with Wayland:

# Launch with --no-sandbox
./ClioDeck.AppImage --no-sandbox

# Or set environment variable
export ELECTRON_NO_SANDBOX=1
./ClioDeck.AppImage

Getting Help

Uninstallation

To completely uninstall ClioDeck:

AppImage

# Remove AppImage
rm ~/.local/bin/cliodeck

# Remove menu entry
rm ~/.local/share/applications/cliodeck.desktop
update-desktop-database ~/.local/share/applications

# Remove user data
rm -rf ~/.config/cliodeck
rm -rf ~/.local/share/cliodeck

.deb Package

# Uninstall
sudo apt remove cliodeck

# Remove data
rm -rf ~/.config/cliodeck

From Source

# Remove cloned repository
rm -rf /path/to/cliodeck

# Remove user data
rm -rf ~/.config/cliodeck

Uninstall Ollama (optional)

# Stop service
sudo systemctl stop ollama
sudo systemctl disable ollama

# Remove binary
sudo rm /usr/local/bin/ollama

# Remove systemd service
sudo rm /etc/systemd/system/ollama.service
sudo systemctl daemon-reload

# Remove data
sudo rm -rf /usr/share/ollama
sudo rm -rf ~/.ollama

# Remove user
sudo userdel ollama

Note: Your ClioDeck projects (.md files, PDFs, .cliodeck/) are not automatically deleted.

Next Steps

Once ClioDeck is installed, see Getting Started for your first project.

Distribution-Specific Notes

Ubuntu 20.04 LTS

  • Use deadsnakes PPA for Python 3.11+
  • Node.js 20 via NodeSource
  • Ollama via automatic installation script

Fedora 38+

  • Python 3.11+ available by default
  • Node.js 20 via NodeSource or dnf
  • Ollama via automatic installation script

Arch Linux

  • All dependencies in official repositories
  • Ollama via AUR (yay -S ollama)
  • Continuous updates (rolling release)

License: GPLv3 Support: Open an issue on GitHub for any questions

Clone this wiki locally