ReadAIrr is a renamed fork of Readarr. Some inherited screenshots, executable names, config keys, API labels, and custom-script environment variables still say Readarr where the current app repo still requires that compatibility name. {.is-info}

#Table of Contents

#Quick Start Setup Guide

This page is still in progress and not complete. Contributions are welcome

For a more detailed breakdown of all the settings, check ReadAIrr Settings {.is-info}

In this guide we will try to explain the basic setup you need to do to get started with ReadAIrr. We're going to skip some options that you may see on the screen. If you want to dive deeper into those, please see the appropriate page in the FAQ and docs for a full explanation.

Please note that within the screenshots and GUI settings in orange are advanced options, so you will need to click Show Advanced at the top of the page to make them visible. {.is-warning}

#Startup

After installation and starting up, you open a browser and go to http://{your_ip_here}:8787

If you used the app repo's Docker deployment, the app still listens on 8787 inside the container, but the host port is controlled by READARR_PORT in the env file. Public GHCR image channels are ghcr.io/readairr/app:prod for normal installs, ghcr.io/readairr/app:val for validation, and ghcr.io/readairr/app:dev for active development.

Before adding books, go to Settings => Development and confirm the metadata source. New installs default to Goodreads hosted (https://api.bookinfo.pro). You can also select Hardcover hosted or enter a Custom rreading-glasses URL if you operate a compatible service yourself. Use Test Metadata Source before saving a custom URL.

Leave Minimum Book Match Similarity at the Balanced - 80% default preset while getting started. Raise it later for stricter automatic/manual import matching, or lower it if correct files are being rejected as not close enough.

qs_startup.png

#Media Management

First we’re going to take a look at the Media Management settings where we can setup our preferred naming and file management settings.

Settings => Media Management

mediamanagement.png

#Book Naming

booknaming.png

This does not apply if Calibre is used as Calibre handles file/folder naming using its own internal schema. {.is-info}

#Folders

folders.png

One of those boxes can be checked, but they should not BOTH be checked. {.is-warning}

This does not apply if Calibre is used as Calibre handles file/folder naming using its own internal schema. {.is-info}

#Importing

importing.png

You should ideally use this wherever possible. In order for hard links to be used, you must have your source/destination on the same file system (drive, partition) and mount points. See TRaSH's Hardlink Guide for more information {.is-info}

If you are using ReadAIrr for audiobooks, you should add .cue to this list, as it holds your chapter information! {.is-info}

#File Management

filemanagement.png

* PROPER - means there was a problem with the previous release. Downloads tagged as PROPER shows that the problems have been fixed in that release. This is done by a Group that did not release the original. * REPACK - means there was a problem with the previous release and is corrected by the original Group. Downloads tagged as REPACK shows that the problems have been fixed in that release. This is done by a Group that did release the original. {.is-info}

It is highly recommended that you use a Recycling Bin. It's easy to delete files, and recovering them is easy if you use the bin. {.is-warning}

#Root Folders and Calibre Integration

rootfolders1.png

Here we will add the root folder that ReadAIrr will be using to import your existing organized media library and where ReadAIrr will be importing (copy/hardlink/move) your media after your download client has downloaded it.

The user and group you configured ReadAIrr to run as must have read & write access to this location. {.is-info}

You may also elect to use Calibre to manage your library on this screen. Doing so will require you to run the Calibre Content Server. This is NOT Calibre-Web.

Non-Windows Users: * If you're using an NFS mount ensure nolock is enabled. * If you're using an SMB mount ensure nobrl is enabled. {.is-warning}

If you are going to use Calibre, the books you want to have ReadAIrr recognize on initial library import must already be in Calibre. Books within the folder and not in Calibre will be ignored. Hard links are not used when adding Calibre integration. Note that you cannot add Calibre integration to a root folder after it's created. {.is-danger}

Your download client downloads to a download folder, and ReadAIrr imports it to your media folder (final destination) that your media server uses. Your download folder and media folder can’t be the same location! {.is-warning}

Don’t forget to save your changes.

#Calibre Content Server (Optional)

If you are going to use Calibre to manage your books, you need to set up the Calibre Content Server. Again, this is not Calibre-Web, but a piece of Calibre itself. You must be running Calibre, and you must set up the Content Server.

If you choose to use Calibre - you cannot change anything in Calibre's database. Failure to heed this warning will result in you needing to deleting your ReadAIrr database and starting over {.is-danger}

If you're using docker, your Calibre mounted book directory and your ReadAIrr mounted book directory must be the same.

Please note that while ReadAIrr is in beta; if you use Calibre it is recommended to disable Renaming in ReadAIrr just in case an unintended bug slips through. {.is-info}

To do this, open Calibre, and click Preferences / Sharing over the net

calibreprefs.png

First, add a user account. The account DOES need "make changes" access.

calibreacct.png

Then you will need to restart Calibre. Once back in, configure and start up the content server. It should show you that it's running. Set it to run automatically on startup. After saving, you will again need to restart Calibre. Make sure the sever is started when it comes back up, then you can move to the next section.

You must select "Require username and password to access the content server" in order for ReadAIrr to properly work. If you do not, you will get an error that says "Anonymous users are not allowed to make changes" when ReadAIrr import a book! {.is-info}

calibreserver.png

#Calibre Integration

calibre1.png

The below are Calibre Specific Settings and only display if Use Calibre is enabled

* Only for use with ebooks, cannot be used for audiobooks! * Note that this cannot be enabled on an existing root folder. * Note that this cannot be disabled on an existing Calibre enabled root folder. * Note that this requires Calibre Content Server and will not work with Calibre Web nor Calibre. * Note that hard links do not work with Calibre integration. * Note that this requires that Calibre to have Require username and password to access the content server to be enabled. * Failure to have Require username and password to access the content server enabled in Calibre will result in an error of Anonymous users are not allowed to make changes {.is-warning}

There was a change in Calibre 7.2.0 which starts listening on ipv6, and it can cause a problem with readarr connections. To fix it, change the Calibre setting "The interface to listen for connections" to 0.0.0.0 in Preferences->Sharing over the net->Advanced, in calibre, and restart calibre. This should resolve the issue. {.is-info}

If you choose to use Calibre - you cannot change anything in Calibre's database. Failure to heed this warning will result in you needing to deleting your ReadAIrr database and starting over. You cannot add books, delete books, re-tag books, or convert books inside Calibre. This includes updating the metadata. {.is-danger}

If you add an individual book, and select None* for the metadata profile, only that book will show up under the author when it's added. If you want other books for that author added, choose an appropriate metadata profile. * Note that None does not apply any metadata filters and you may get unwanted foreign editions. To work around these create a metadata profile as prescribed in the faq {.is-warning}

#Download Clients

Settings => Download Clients

Downloading and importing is where most people experience issues. From a high level perspective, the software needs to be able to communicate with your download client and have access to the files it downloads. There is a large variety of supported download clients and an even bigger variety of setups. This means that while there are some common setups there isn’t one right setup and everyone’s setup can be a little different. But there are many wrong setups.

See the settings page, at the More Info (Supported) page for this section, and TRaSH's Download Client Guides for more information. {.is-info}

#{.tabset}

#Usenet

{#usenet}

#BitTorrent

{#bittorrent}

#How to import your existing organized media library

Note that ReadAIrr does not regularly search for Books. See these two FAQ Entries for details to understand how ReadAIrr works. How does ReadAIrr find books? and How does ReadAIrr work? {.is-info}

After setting up your profiles/quality sizes and added your indexers and download client(s) it’s time to import your existing organized media library.

Coming soon - Contributions Welcome

#Importing Existing Media

Coming soon - Contributions Welcome

#Add New Books

Refer to the Library Page for additional information