From aeb66e878c65cd041dd6a2cab4a3eb476a75fb8a Mon Sep 17 00:00:00 2001 From: Sebastian Hugentobler Date: Fri, 10 May 2024 15:05:56 +0200 Subject: [PATCH] add readme --- README.md | 78 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 78 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..6f8f9b0 --- /dev/null +++ b/README.md @@ -0,0 +1,78 @@ +# Rusty Library + +I have been a long time user of [cops](https://github.com/seblucas/cops) and its +[fork](https://github.com/mikespub-org/seblucas-cops) in order to access my +ebook collection in a nice way from a browser. My biggest use always has been +the [ODPS](https://en.wikipedia.org/wiki/Open_Publication_Distribution_System) +feed for getting all of that from within [KOReader](https://koreader.rocks/). + +It so happened that exactly when I was looking for a small side project I also +had trouble with a new cops version (not through their fault, only because I +insist on writing my own containers). _How hard can it be_ I thought and went on +hacking something together. The result does at most one tenth of what cops can +do but luckily enough it is the part I need for myself. + +# Building + +## Nix + +A [nix](https://nixos.org/download/) environment with enabled +[nix-commands](https://nixos.org/manual/nix/stable/contributing/experimental-features#xp-feature-nix-command) +in order to use `nix develop` and `nix build`. + +A statically linked binary for linux systems (using +[musl](https://musl.libc.org/)) can be compiled by running `nix build` (run +`nix flake show` to get a list of available targets). + +Otherwise run `nix develop` to be dropped into a shell with everything installed +and configured. From there all the usual `cargo` commands are accessible. + +## Classic + +A recent [rust](https://www.rust-lang.org/learn/get-started) installation is all +that is needed. + +From there on `cargo run` and `cargo build` and so on can be used. + +# Configuration + +The binary takes exactly one argument, the path to the calibre library folder. + +The listening port is hardcoded to `3000` for now, as is the listening on all +interfaces. + +# Usage + +Run the binary with the calibre library as an argument and open +http://localhost:3000 (or wherever it should be accessible). +http://localhost:3000/opds is the entry point for the OPDS feed. + +# FAQ + +## No authentication? + +Not planned, put a reverse proxy in front of it that handles access. + +## No search? + +On my todo list once I feel like I need it. + +## Why are the OPDS entries not paginated? + +My hardware (a Kobo Aura One from ~2016) with KOReader works perfectly fine with +parsing the 1MB book feed from own library. Once that changes I might get over +my laziness and implement it. + +## Aren't these database access patterns inefficient? + +They most probably are but my elaborate testing setup (my own calibre library) +works fine with it. + +## Why rust? + +I like the language and wanted to try the +[poem](https://github.com/poem-web/poem) framework. + +## Is it webscale? + +Go away.