Skip to content

1.1 ClioDeck Installation ‐ Linux

Jump to bottom
Frédéric Clavert edited this page Jul 26, 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: x86_64 and arm64 are both published, as AppImage and .deb. If you are unsure which you have, run uname -m: x86_64 (also called amd64) means the x86_64 files, aarch64 the arm64 ones. The wrong one downloads perfectly and then refuses to start.
  • 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, libsecret-1 (Keyring access for stored API keys), libgbm

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) is not created automatically — it's a manual step from Settings → Topic Modeling, where you check status and trigger the install.

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. v1.0.0-rc.4 publishes an AppImage and a .deb for x86_64 and for arm64. No .rpm is built; Fedora/RHEL/Arch users should take the AppImage.

Check which one you need before downloading — the commands below assume x86_64, the common case:

uname -m   # x86_64 → the x86_64 files;  aarch64 → the arm64 ones

AppImage (works on all distributions)

# Note the `Linux.AppImage.-.` prefix: asset names gained it in rc.4, so a
# URL built by bumping the version number alone returns 404.
wget https://github.com/cliodeck/cliodeck-app/releases/download/v1.0.0-rc.4/Linux.AppImage.-.ClioDeck-1.0.0-rc.4-x86_64.AppImage -O ClioDeck.AppImage

# On arm64, replace `-x86_64` with `-arm64` in the URL above.

# 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)

# Note the `Linux.Debian.-.` prefix: asset names gained it in rc.4, so a
# URL built by bumping the version number alone returns 404.
# Debian names the x86_64 architecture `amd64`; on arm64 replace it with `arm64`.
wget https://github.com/cliodeck/cliodeck-app/releases/download/v1.0.0-rc.4/Linux.Debian.-.cliodeck_1.0.0-rc.4_amd64.deb

# Install
sudo dpkg -i Linux.Debian.-.cliodeck_1.0.0-rc.4_amd64.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

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

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. There's no "Test Connection" button here (that's Zotero's, further down) — use the 🔄 refresh-models button to confirm Ollama responds and lists your installed models

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
    ├── brain.db            # PDF/Tropy vectors, research history (shared store)
    └── 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 (note the exact name: ELECTRON_DISABLE_SANDBOX,
# not ELECTRON_NO_SANDBOX — the latter is not a real Electron env var and
# has no effect)
export ELECTRON_DISABLE_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 (Electron's default userData path on Linux; the app
# never overrides it with app.setName() or a custom getPath() call, and
# doesn't write anything under ~/.local/share)
rm -rf ~/.config/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