Readarr Setup Guide

Introduction

Readarr is an ebook and audiobook collection manager designed for Usenet and BitTorrent users. Operating as part of the Starr ecosystem, it monitors multiple RSS feeds for new books/audiobooks, integrates with indexers via Prowlarr, and communicates with download clients (such as SABnzbd or Transmission) to automate acquisition, naming, and organization.

---

Step 1: Initial Container Deployment

1. Ensure the required environment variables are set in your root .env file:

READARR_PORT=8787
READARR_API_KEY=your_readarr_api_key_here

2. Copy the readarr.yaml file into your active server compose directory:

cp compose/templates/readarr.yaml compose/server1/readarr.yaml

3. Create host directories for configuration files and logs:

sudo mkdir -p ${DOCKERDIR}/readarr/config ${DOCKERDIR}/logs/readarr

4. Launch the container:

docker compose -p mediaserver -f docker-compose-server1.yaml up -d readarr

---

Step 2: Service Definition (readarr.yaml)

# ------------------------------------------------------------------------------
# Readarr - Book & Audiobook Collection Manager
# ------------------------------------------------------------------------------
services:
  readarr:
    container_name: readarr.${HOST_NAME}
    hostname: readarr.${HOST_NAME}.lan
    image: linuxserver/readarr:develop
    environment:
      TZ: ${TZ}
      PGID: ${PGID}
      PUID: ${PUID}
      DOMAINNAME: ${DOMAINNAME}
      UMASK: 2
    networks:
      - mediaserver
    ports:
      - "${READARR_PORT}:8787"
    volumes:
      - /etc/localtime:/etc/localtime:ro
      - ${DOCKERDIR}/readarr/config:/config
      - ${MEDIASHARE}/Books:/books
      - ${USERDOWNLOAD}/Torrents:/downloads
      - ${DOCKERDIR}/logs/readarr:/var/log
      - ${MEDIASHARE}:/media
    restart: always
    security_opt:
      - no-new-privileges:true
    labels:
      - "com.centurylinklabs.watchtower.enable=true"
      - "homepage.group=Media"
      - "homepage.name=Readarr"
      - "homepage.icon=readarr.png"
      - "homepage.href=https://readarr.gillisonline.com/"
      - "homepage.description=Book download manager"
      - "homepage.widget.type=readarr"
      - "homepage.widget.url=http://readarr.${HOST_NAME}:8787"
      - "homepage.widget.key=${READARR_API_KEY}"

---

Step 3: Accessing the UI & Onboarding

1. Open your browser and go to http://<your-ip-address>:8787 or your reverse proxy URL (https://readarr.gillisonline.com).
2. Navigate to Settings -> General and set up your authentication method (Form/Basic/Prowlarr SSO).
3. Retrieve your API Key under Settings -> General -> Security and paste it into your root .env file for Homepage integration.

---

Step 4: System Integration

Indexers (via Prowlarr)

1. Go to your Prowlarr instance.
2. Under Settings -> Apps, add a new Readarr instance.
3. Set the Server URL to http://readarr.server1.lan:8787 (or your internal container name) and paste the Readarr API Key.

Download Clients

1. In Readarr, go to Settings -> Download Clients.
2. Add your download client (e.g., SABnzbd or Transmission-OpenVPN).
3. Ensure directory paths align between your download client and Readarr (/downloads mapping).

Root Folders

1. Navigate to Settings -> Media Management.
2. Add Root Folders pointing to your library directories:
   • Ebooks: /books or /media/Books
   • Audiobooks: /media/Audiobooks

---

Step 5: Backup & Restore

Backing Up

• Use the built-in backup engine under System -> Backup inside the Readarr UI.
• Alternatively, stop the container and copy the ${DOCKERDIR}/readarr/config directory.

Restoring

1. Stop the Readarr container:

   docker compose -p mediaserver -f docker-compose-server1.yaml stop readarr
   

2. Restore your config folder or extract the .zip archive generated by Readarr back into ${DOCKERDIR}/readarr/config.
3. Restart the container:

   docker compose -p mediaserver -f docker-compose-server1.yaml start readarr
   

---

Step 6: Troubleshooting

• Permission Errors: Verify that the PUID and PGID variables match the user/group that owns the ${MEDIASHARE} and ${USERDOWNLOAD} mount paths.
• Develop Image Tag Notice: Readarr relies on the :develop tag because stable releases are less frequent. Watchtower will update this container automatically as developer updates release.
• Logs: Inspect runtime activity and download errors:

  docker logs -f readarr.${HOST_NAME}
  ```Readarr Setup Guide