Skip to content

installation.md

Latest commit

 

History

History
120 lines (78 loc) · 3.96 KB

installation.md

File metadata and controls

120 lines (78 loc) · 3.96 KB

Installation

Home Assistant

Using Home Assistant? Install KoShelf as an add-on with just one click below.

Open your Home Assistant instance and show the dashboard of an add-on.

Docker Compose

Deploy KoShelf using the community-maintained Docker image.

Quick Start

  1. Create a docker-compose.yml file:
services:
    koshelf:
        image: ghcr.io/devtigro/koshelf:latest
        ports:
            - '3000:3000'
        volumes:
            - /path/to/your/books:/books:ro
            - /path/to/your/settings:/settings:ro
        restart: unless-stopped
  1. Update the volume paths:
  • Replace /path/to/your/books with the absolute path to your book library
  • Replace /path/to/your/settings with the absolute path to your settings directory
  1. Start the container:
docker compose up -d
  1. Access KoShelf at http://localhost:3000

Docker Image Repository: koshelf-docker

Prebuilt Binaries

Download a prebuilt binary from the releases page. Binaries are available for:

  • Windows (x64)
  • macOS (Apple Silicon, Intel & Universal)
  • Linux (x64 and ARM64)

KoShelf is a command line tool — you need to run it from a terminal (macOS/Linux) or PowerShell/Command Prompt (Windows). Double-clicking the executable won't work since it requires command line arguments.

Note for Windows users: Windows Defender will likely flag and delete the Windows binary as a virus (more information here). This is a false positive if you downloaded the binary directly from this repo. To use the binary:

  1. Restore it from Windows Defender's protection history (Windows Security > Virus & threat protection > Protection history > Restore)
  2. Launch the binary from PowerShell or Windows Terminal with arguments - double-clicking will cause it to close immediately since no arguments are provided

First Time Using Command Line?

If you've never used a command line before, here's how to get started:

Windows:

  1. Press Win + R, type powershell, and press Enter
  2. Navigate to where you downloaded the KoShelf binary (e.g., cd C:\Users\YourName\Downloads)
  3. Run the tool with your desired arguments (see Configuration)

macOS and Linux:

  1. Press Cmd + Space, type terminal, and press Enter
  2. Navigate to where you downloaded the KoShelf binary (e.g., cd ~/Downloads)
  3. Make the file executable: chmod +x koshelf (should not be needed on macOS as the binary is signed)
  4. Run the tool with your desired arguments (see Configuration)

Example:

# Navigate to your downloads folder
cd ~/Downloads  # macOS/Linux
cd C:\Users\YourName\Downloads  # Windows

# Run KoShelf with your books folder
./koshelf export ./my-library-site --library-path /path/to/your/library

Tip: On most terminals, you can drag and drop the downloaded binary file into the terminal window to insert its full path.

System-Wide Installation (Linux/macOS)

If you plan to use KoShelf frequently, you can move the binary to /usr/local/bin/ to make it available system-wide:

# Move the binary to system PATH (requires sudo)
sudo mv koshelf /usr/local/bin/

# Now you can run it from anywhere
koshelf export ~/my-library-site --library-path ~/Books

From Source

Prerequisites

  • Rust 1.70+ (for building)
  • Node.js and npm (React frontend build pipeline)

Building the tool

git clone https://github.com/paviro/KoShelf
cd KoShelf

# Build the Rust binary
cargo build --release

The binary will be available at target/release/koshelf.

Note: The React frontend is built during cargo build and embedded into the binary.