A personal documents server, Coreander indexes the documents (EPUBs and PDFs with no DRM) that it finds in the passed folder, and provides a web interface to search and access them.

Coreander home

• Single binary with all dependencies included. Just download and run, no installation required.
• Search by author, title and even document series (Calibre's series meta supported)
• Improved search for documents with metadata in English, Spanish, French, Italian, German and Portuguese, including genre and singular/plural forms of words in the results among others.
• Estimated reading time calculation.
• Responsive web interface available in English, Spanish, German, Russian and French, more languages can be easily added.
• New documents added or removed to/from the library folder are automatically indexed (Linux only).
• Send to email supported.
• Read indexed epubs and PDFs from Coreander's interface thanks to foliate-js.
• Reading progress sync between multiple devices, E.G.: start reading in your cellphone and resume reading from your tablet where you left off.
• Restrictable access only to registered users.
• Upload documents through the web interface.
• Download as kepub (epub for Kobo devices) converted on the fly thanks to Kepubify.
• Gather information about authors from Wikidata.

Binaries for Windows 64 bit, Linux 32 and 64 bits for both X86 and ARM (Raspberry Pi and other SBCs) and Macs with Intel and Apple processors are available at releases. Just download and unzip the one appropriate for your system.

Coreander's only requirement is the Go compiler. The minimum required Go version is stated in the go.mod file.

When cloning Coreander's repository, use Git's --recurse-submodules flag to also retrieve foliate-js contents as well, which is required for the reader component:

git clone git@github.com:svera/coreander.git --recurse-submodules

There are two possibilities for building Coreander from source:

• If you have Mage installed in your system, just type mage install from the source code folder.
• Otherwise, a simple go build or go install will do, although no version information will be added to the executable.

Although it can be executed as any desktop app, Coreander is designed to be run as a service managed by systemd or any other service manager. For example, in Raspberry Pi OS, just create a file called /etc/systemd/system/coreander.service with the following contents:

[Unit]
Description=coreander

[Service]
Restart=always
RestartSec=5s
WorkingDirectory=<absolute path to directory which contains coreander binary>
ExecStart=<absolute path to coreander binary>
PermissionsStartOnly=true
SyslogIdentifier=coreander
User=<user which will execute this service>
Environment="LIB_PATH=<absolute path to the library>"

then, start the service with service coreander start. You can manage it with the usual commands start, stop and status. Refer to your service manager documentation for more information.

Coreander requires the absolute path where your documents are located as an argument. You can also pass it through the LIB_PATH environment variable.

On first run, Coreander will index the documents in your library, creating a database with those entries located at $home/coreander/index. Depending on your system's performance and the size of your library this may take a while. Also, the database can grow fairly big, so make sure you have enough free space on disk.

Every time it is run, the application scans the library folder only for documents not yet indexed and adds them to the index. You can force to index all documents whether they were previously indexed or not by passing the --force-indexing flag or setting the environment variable FORCE_INDEXING to true.

Even if the application is still indexing entries, you can access its web interface right away. Just open a web browser and go to localhost:3000 (replace localhost with the hostname / IP address of the machine where the server is running if you want to access it from another system). It is possible to change the listening port just executing the application with the -p or --port flags, or the PORT environment variable (e. g. coreander -p 4000 or PORT=4000 coreander)

If you plan to set up Coreander in a public Internet server such as a VPS, using Caddy as a reverse proxy is strongly recommended, as it is dead simple to set up and comes with several niceties such as HTTPS out of the box through Let's Encrypt.

For example, if you have Coreander listening to port 3000 in your server and a domain called coreander.example.com that points to the IP address of your server, you can just tell Caddy to route requests to coreander.example.com to Coreander by putting this in Caddy's Caddyfile:

coreander.example.com {
    reverse_proxy :3000
}

Refer to Caddy documentation for more information.

Some features rely on having an SMTP email service set up, and won't be available otherwise:

• Send document to email.
• Recover user password.
• Invite new users.

You can use any email service that allows sending emails using the SMTP protocol, like GMX. The following flags or environment variables need to be defined:

Coreander can send documents through email. This way, you can take advantage of services such as Amazon's send to email, which also automatically converts EPUB and other formats to the target device.

Coreander distinguishes between two kinds of users: regular users and administrator users, with the latter being the only ones with the ability to create new users and upload and delete documents.

By default, Coreander allows unrestricted access to its contents, except management areas which require an administrator user. To allow access only to registered users in the whole application, pass the -a or --require-auth flags, or the REQUIRE_AUTH=true environment variable.

On first run, Coreander creates an admin user with the following credentials:

• Email: admin@example.com
• Password: admin

Coreander uses TextRank to automatically extract keywords (single words and two-word phrases) from the text of EPUB documents during indexing. TextRank builds a graph where words are nodes and an edge connects two words whenever they appear near each other in the text; words that co-occur with many other important words end up with a higher rank, similarly to how Google's PageRank ranks web pages by how many other important pages link to them. The highest-ranked words and phrases become a document's keywords.

These extracted keywords power two features:

• Search: keywords are indexed alongside title, author and other metadata, so a document can be found by searching for a term that appears frequently in its text even if it's not part of its declared metadata.
• Similar documents: when viewing a document, Coreander suggests others that share a meaningful number of its top keywords.

Before ranking, Coreander detects the document's language(s) (falling back to full text detection if the EPUB doesn't declare one) and filters out stop words (common words like "the" or "and" that carry no distinctive meaning) for each detected language, plus English stop words always, since documents often mix in English terms regardless of their main language.

Not every word or phrase TextRank finds is kept: only those whose occurrence count is close enough to the most frequent one survive, controlled by --min-occurrence-ratio (see table below). This avoids keeping words that only appear once or twice in an otherwise repetitive document, which would otherwise look important simply because they're compared against a low baseline.

Separately, once keywords exist across the whole library, any phrase or word that turns out to be too common there (a genre-wide word, or a series' recurring character name) is stripped from every document that has it, since a signal shared by a large fraction of the library isn't distinctive enough for keyword search or "similar documents" to rely on. This whole-library pruning pass runs after every full (re)indexing, and again in the background whenever enough documents are added or removed since the last pass, controlled by --common-textrank-entry-ratio, --min-common-textrank-absolute-count and --prune-change-trigger-ratio (see table below).

You can fine-tune this behavior with the following flags:

Since keyword extraction runs once per document during indexing, changing --min-occurrence-ratio only affects documents indexed (or re-indexed with --force-indexing) after the change.

Run coreander -h or coreander --help to see help.

In case both a flag and its equivalent environment variable are passed, flag takes precedence.

Search results in dark mode

Document detail

Reading interface

Reading interface in mobile device