From aeb66e878c65cd041dd6a2cab4a3eb476a75fb8a Mon Sep 17 00:00:00 2001
From: Sebastian Hugentobler <sebastian@vanwa.ch>
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.