ORCA

A simple OPDS Server for Calibre written in Rust.

It supports:

• OPDS v1 and v2
• http and https
• basic authentication
• multiple Calibre libraries

Before you serve your own library, you can test orca by firing up a demo that contains seven public-domain books, in three languages, as EPUB, MOBI and AZW3:

docker run --rm -p 23117:23117 koljaw/orca-demo

Add --auth to serve the same library behind a login (alice / secretpassword):

docker run --rm -p 23117:23117 koljaw/orca-demo --auth

Then point an OPDS reader at http://127.0.0.1:23117 or http://127.0.0.1:23117/v2 for an OPDS v2 feed.

brew tap kolja/orca
brew install orca-server

docker pull koljaw/orca
docker run -p 8080:8080 \
-e ORCA_CONFIG=/app/orca.toml \
-v /path/to/your/config.toml:/app/orca.toml \
-v /path/to/your/library:/app/library \
koljaw/orca:latest

If you point the environment variable ORCA_CONFIG to a .toml file, that's where the configuration will be read from. Otherwise, it will look for a file named orca.toml or orca/config.toml in $HOME/.config/.

The server will either start as HTTP or HTTPS server depending on the value of 'protocol'. If you set it to 'https', you have to provide a path to a certificate and a key file.

[server]
ip = "<your_ip>"
port = 8080
protocol = "Https" # or "Http"
cert = "/path/to/cert.pem"
key = "/path/to/key.pem"
public_url = "https://orca.example.com" # optional, see below

[authentication.login]
alice = "$argon2id$v=19$m=19456,t=2,p=1$bK0qYfzAokhthFP0fKBQvg$QPPf54SN74dT2YX4aGoN+KxoWD+xV+c6OBrrPnvxj24"
bob = "$argon2id$v=19$m=19456,t=2,p=1$FMnONzRzIAkaIuy3c+A9cg$DE3+UC62d/f+L0jqEWgz9GAfNWQkKfugeZFSL/FG5XQ"

[authentication]
public = ["/", "/library/**"] # the root endpoint is publicly accessible, so is everything under /library

[catalog]
author = "Jorge Luis Borges" # optional (default: "orca")

[calibre.libraries.library]
path = "/Volumes/library"

[calibre.libraries.nonfiction]
path = "/Volumes/nonfiction"
author = "Isaac Newton" # optional (overrides catalog.author)

The server supports basic authentication: You can generate a password hash like so:

orca --hash <login>:<password> # e.g. orca --hash alice:secretpassword

The server will print the hash which you have to copy to the [authentication.login] section of your config file.

Under the public array in the [authentication] section you can specify which paths should be accessible without authentication. You can use wildcards like * and ** to match multiple paths.

According to RFC 4287 every catalog needs an Author. The field is set to "orca" by default, but you can override it for the entire catalog or set it individually per library.

Every feed advertises its own address in <link rel="self">. Some OPDS clients will resolve links against that self link instead of against the URL they fetched — which is not necessarily the address Orca binds to.

Orca derives it from the request, honouring X-Forwarded-Proto and X-Forwarded-Host, so a proxy that sets those headers needs no extra configuration.

If your proxy cannot set them, set public_url in the [server] section to the externally visible base URL. It will take precedence over the headers.

There are a couple of tasks you can run with cargo make:

• cargo make docker-build <image/name> - Build Docker image and push it to the registry, followed by <image/name>-demo
• cargo make docker-build-demo <image/name> - Rebuild only the demo image
• cargo make git-tag - Create and push a new git tag. The Version number is read from Cargo.toml
• cargo make list-sha - List all the sha256 hashes for the Assets in the Release (for use with the the homebrew formula)

MIT