Korrosync

A modern, high-performance KOReader sync server written in Rust

Overview

Korrosync is a self-hosted synchronization server for KOReader. It enables seamless reading progress synchronization across multiple devices, allowing you to pick up where you left off on any device.

Installation

Building from Source

# Clone the repository
git clone https://github.com/szaffarano/korrosync.git
cd korrosync

# Build with cargo (without TLS)
cargo build --release

# Or build with TLS support
cargo build --release --features tls

# Run the server
./target/release/korrosync

Using Nix Flakes

# Run directly with Nix
nix run github:szaffarano/korrosync

# Or enter development shell
nix develop
cargo run

Pre-built Binaries

Pre-built binaries for Linux and macOS are available in the releases section.

Docker

Docker images are uploaded in Docker Hub.

If you want to build the image yourself, use the following instructions.

# Build for your current platform
docker build -t korrosync .

# Multi-arch builds (requires buildx)
# First, create a buildx builder if you haven't already
docker buildx create --name multiarch --use

# e.g., build for Raspberry Pi 3 and load locally
docker buildx build \
  --platform linux/arm/v7 \
  -t korrosync:arm32 \
  --load .

# Run container (HTTP)
docker run -d \
  -p 3000:3000 \
  -v $(pwd)/data:/data \
  -e KORROSYNC_DB_PATH=/data/db.redb \
  --name korrosync \
  korrosync

# Run container with TLS enabled
docker run -d \
  -p 3000:3000 \
  -v $(pwd)/data:/data \
  -v $(pwd)/tls:/tls \
  -e KORROSYNC_DB_PATH=/data/db.redb \
  -e KORROSYNC_USE_TLS=true \
  -e KORROSYNC_CERT_PATH=/tls/cert.pem \
  -e KORROSYNC_KEY_PATH=/tls/key.pem \
  --name korrosync \
  korrosync

Features

Korrosync supports optional features that can be enabled at compile time:

tls

Enables native TLS/HTTPS support using rustls. When enabled, the server can accept HTTPS connections directly without requiring a reverse proxy.

Building with TLS support:

cargo build --release --features tls

What it enables:

• Direct HTTPS support via rustls
• TLS configuration options (KORROSYNC_USE_TLS, KORROSYNC_CERT_PATH, KORROSYNC_KEY_PATH)
• Native certificate and key file handling

Note: If the tls feature is not enabled during compilation, the server will only support HTTP. You can still use HTTPS by placing the server behind a reverse proxy like Nginx (see Deployment section).

Configuration

Korrosync is configured through environment variables:

Example

# Basic configuration
export KORROSYNC_DB_PATH=/var/lib/korrosync/db.redb
export KORROSYNC_SERVER_ADDRESS=127.0.0.1:8080
korrosync

# With TLS enabled
export KORROSYNC_DB_PATH=/var/lib/korrosync/db.redb
export KORROSYNC_SERVER_ADDRESS=0.0.0.0:3000
export KORROSYNC_USE_TLS=true
export KORROSYNC_CERT_PATH=/etc/korrosync/tls/cert.pem
export KORROSYNC_KEY_PATH=/etc/korrosync/tls/key.pem
korrosync

Usage

Starting the Server

# Start with default configuration
korrosync

# Or with custom configuration
KORROSYNC_SERVER_ADDRESS=0.0.0.0:8080 korrosync

API Endpoints

• POST /users/create — Register a new user
• GET /users/auth — Verify authentication status
• PUT /syncs/progress — Update reading progress for a document
• GET /syncs/progress/{document} — Retrieve progress for a specific document
• GET /healthcheck — Health check endpoint
• GET /robots.txt — Robots exclusion file

Deployment

Systemd Service

Create a systemd service file at /etc/systemd/system/korrosync.service:

[Unit]
Description=Korrosync - KOReader Sync Server
After=network.target

[Service]
Type=simple
User=korrosync
Group=korrosync
Environment="KORROSYNC_DB_PATH=/var/lib/korrosync/db.redb"
Environment="KORROSYNC_SERVER_ADDRESS=0.0.0.0:3000"
# Uncomment to enable TLS
#Environment="KORROSYNC_USE_TLS=true"
#Environment="KORROSYNC_CERT_PATH=/etc/korrosync/tls/cert.pem"
#Environment="KORROSYNC_KEY_PATH=/etc/korrosync/tls/key.pem"
ExecStart=/usr/local/bin/korrosync
Restart=on-failure
RestartSec=5s

# Security
NoNewPrivileges=true
PrivateTmp=true
ProtectSystem=strict
ProtectHome=true
ReadWritePaths=/var/lib/korrosync

[Install]
WantedBy=multi-user.target

Enable and start the service:

sudo systemctl enable korrosync
sudo systemctl start korrosync
sudo systemctl status korrosync

Native TLS Support

Korrosync supports built-in TLS/HTTPS without requiring a reverse proxy:

# Enable TLS with environment variables
export KORROSYNC_USE_TLS=true
export KORROSYNC_CERT_PATH=/etc/korrosync/tls/cert.pem
export KORROSYNC_KEY_PATH=/etc/korrosync/tls/key.pem
korrosync

Note: Certificate and private key files must be in PEM format. For production, use certificates from a trusted CA (e.g., Let's Encrypt). For testing, self-signed certificates are provided in the tls/ directory. See tls/README.md for more information.

Reverse Proxy (Nginx)

Alternatively, use a reverse proxy with TLS termination:

server {
    listen 443 ssl;
    http2 on;
    server_name sync.example.com;

    ssl_certificate /path/to/cert.pem;
    ssl_certificate_key /path/to/key.pem;

    location / {
        proxy_pass http://127.0.0.1:3000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
    }
}

Development

Setting Up Development Environment

Using Nix flakes (recommended):

# Enter development shell with all tools
nix develop

# Pre-commit hooks will be installed automatically

Running Tests

# Run all tests
cargo test

# Run with coverage
cargo tarpaulin --out Html

# Run integration tests only
cargo test --test '*'

Architecture

Korrosync is built with:

• Axum — Fast, ergonomic web framework
• redb — Embedded key-value database (ACID compliant)
• Argon2 — Secure password hashing
• Tokio — Async runtime
• Tower — Middleware and service abstractions
• Governor — Rate limiting

TODO

The following features and improvements are planned:

API & Features

• OpenAPI/Swagger documentation

Infrastructure

• TLS/HTTPS configuration support
• Configurable rate limiting via environment variables
• Metrics and observability (Prometheus/OpenTelemetry)
• Structured logging with log levels
• CLI tool for administrative tasks (user management, database maintenance)

Deployment & Distribution

• Automated binary releases for multiple platforms
• Official Docker images on Docker Hub
• Helm chart for Kubernetes deployment
• NixOS module for declarative configuration

Documentation

• API documentation
• Deployment guides

Testing & Quality

• Increase test coverage to >80%
• Improve logging and error handling

License

This project is licensed under the MIT License — see the LICENSE file for details.

Acknowledgments

• KOReader — The amazing e-reader application this server supports
• KOReader progress sync server — Inspiration for this implementation
• The Rust community for excellent tools and libraries