Skip to content

installation.md

Latest commit

 

History

History
186 lines (136 loc) · 3.53 KB

installation.md

File metadata and controls

186 lines (136 loc) · 3.53 KB

Installation

Prerequisites

Required

  • Rust toolchain (1.70 or newer)
    • Install via rustup: curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

Optional (for AI features)

  • LM Studio - Local LLM server for photo descriptions
  • Ollama - Alternative local LLM runtime

Optional (for better image previews)

  • A terminal with graphics protocol support:
    • Kitty, iTerm2, WezTerm (best quality)
    • Konsole, foot, xterm with sixel (good quality)

Building from Source

Standard Build

# Clone the repository
git clone <repository-url>
cd clepho

# Build release version (SQLite only)
cargo build --release

# Build with PostgreSQL support
cargo build --release --features postgres

# Binary location
./target/release/clepho

NixOS / Nix

Clepho provides a Nix flake for easy installation on NixOS and systems with Nix.

Run directly (no install)

nix run github:barrulus/clepho

Install to user profile

nix profile install github:barrulus/clepho

Add to NixOS configuration

In your system flake.nix:

{
  inputs = {
    nixpkgs.url = "github:NixOS/nixpkgs/nixos-unstable";
    clepho.url = "github:barrulus/clepho";
  };

  outputs = { self, nixpkgs, clepho, ... }: {
    nixosConfigurations.yourhost = nixpkgs.lib.nixosSystem {
      system = "x86_64-linux";
      modules = [
        ({ pkgs, ... }: {
          environment.systemPackages = [
            clepho.packages.${pkgs.system}.default
          ];
        })
      ];
    };
  };
}

Home Manager

{ inputs, pkgs, ... }:
{
  home.packages = [
    inputs.clepho.packages.${pkgs.system}.default
  ];
}

Development shell

For contributing or building from source:

git clone https://github.com/barrulus/clepho
cd clepho
nix develop
cargo build --release

Debug Build

For development with faster compilation:

cargo build
./target/debug/clepho

First Run

On first launch, Clepho will:

  1. Create configuration directory at ~/.config/clepho/
  2. Create default configuration file config.toml
  3. Create data directory at ~/.local/share/clepho/
  4. Initialize database (SQLite by default at clepho.db)
  5. Create thumbnail cache at ~/.cache/clepho/thumbnails/
  6. Create trash directory at ~/.local/share/clepho/.trash/

Verifying Installation

# Run Clepho
./target/release/clepho

# You should see the three-pane file browser
# Press ? for help, q to quit

Updating

# Pull latest changes
git pull

# Rebuild
cargo build --release

The database schema is automatically migrated on startup if needed.

Troubleshooting

Build Errors

Missing OpenSSL:

# Debian/Ubuntu
sudo apt install libssl-dev pkg-config

# Fedora
sudo dnf install openssl-devel

# macOS
brew install openssl

Missing SQLite:

# Debian/Ubuntu
sudo apt install libsqlite3-dev

# Fedora
sudo dnf install sqlite-devel

# macOS (usually pre-installed)
brew install sqlite

Runtime Issues

No image previews:

  • Check terminal compatibility (see Navigation)
  • Set protocol = "halfblocks" in config for basic support
  • Set protocol = "none" to disable previews

Database locked:

  • Ensure only one instance of Clepho is running
  • Check for stale lock files in ~/.local/share/clepho/

Permission denied:

  • Ensure read access to photo directories
  • Ensure write access to config/data directories