docker container ebook management and conversion made easy, with send to kindle as a bonus

eBook management and automation using Calibre, COPS or Calibre-Web, and Readarr

Containers Oct 8, 2021

About 10 years ago I was handed a 150GB ebook library consisting of I don't know how many sci-fi books. It's a lot, and needless to say I'll never manage to read them all in my lifetime.

Since I bought my NAS they've been sat in a directory collecting dust, and every now and then I'd jump on, grab a book I wanted, download it to my machine and email it to my kindle. Not exactly rocket science, but also not exactly a smooth process. It felt clunky. I did a bit of digging and came across Calibre, an ebook management tool, and from there the others fell into place.

I'll walk you through setting up the following containers via docker compose, and the in-app settings you'll need to integrate them together:

💡
It's worth noting that Readarr cannot 'send-to-kindle' by itself. That particular service is done either by Calibre, or (better) Calibre-Web / COPS)

Before we start, I'm going to assume the following:

  1. You can use docker-compose, either via SSH or via Portainer
  2. You can SSH into your system, or you know another way to create a docker network
  3. You have a docker directory on your machine, and you can create folders
  4. You are familiar with the *arr family of services (Radarr/Sonarr etc.) and already have indexers and download agents set up (Usenet/Torrent, either or)
  5. You have an email address you can configure with smtp (required for sending to your eBook device)
I've not yet written an article on Radarr or Sonarr, but there is one on how they work with Prowlarr which includes some basic setup for them

Let's get started!


Setting up Calibre

Our whole eBook system hinges on Calibre. It will act as our database, our content server and our format converter (not all devices read EPUB or AZW3 for instance).

The Prep

  • Create a docker bridge network called 'ebooks'. Via SSH, this is achieved by typing the following:
sudo docker network create ebooks
  • Inside your docker directory, create a folder called calibre
  • Inside that directory, create the following folders:
config
cops #if you plan to use cops
calibre-web #if you plan to use calibre-web
plugins
upload
CalibreLibrary #only use if you don't have a pre-existing ebook library
  • Still inside your calibre folder, create a file called docker-compose.yml and copy paste the following into it:
services:
  calibre:
    image: ghcr.io/linuxserver/calibre
    container_name: calibre
    environment:
      - PUID=$PUID #change this to your user's PID
      - PGID=$PGID #change this to your user's PGID
    volumes:
      - path/to/your/calibre/config:/config #change before the ':'
      - path/to/your/calibre/upload:/uploads #change before the ':'
      - path/to/your/calibre/plugins:/plugins #change before the ':'
      - path/to/your/CalibreLibrary:/Calibre_Library #this is where your ebooks will end up
    ports:
      - 8080:8080 #change before the ':' if necessary
      - 8081:8081 #change before the ':' if necessary
    restart: unless-stopped
    networks:
      - ebooks

  cops:
    image: lscr.io/linuxserver/cops
    container_name: cops
    environment:
      - PUID=$PUID #change this to your user's PID
      - PGID=$PGID #change this to your user's PGID
    volumes:
      - path/to/your/calibre/cops:/config #change before the ':'
      - path/to/your/CalibreLibrary/Calibre Library:/books #this directory path is correct, calibre will create the folder 'Calibre Library' when it spins up
    ports:
      - 80:80 #change before the ':' if necessary
    labels:
    depends_on:
      - calibre
    restart: unless-stopped
    networks:
      - ebooks

networks:
  ebooks:
    external: true
the docker-compose file for Calibre and COPS
  • To use Calibre-Web instead of COPS, replace the above cops block with the following:
  calibre-web:
    image: ghcr.io/linuxserver/calibre-web
    container_name: calibre-web
    environment:
      - PUID=$PUID
      - PGID=$PGID
    volumes:
      - $DOCKERDIR/calibre/calibre-web:/config
      - path/to/your/Calibre Library:/books
    restart: unless-stopped
    depends_on:
      - calibre
    ports:
      - 8083:8083
    networks:
      - ebooks
💡
As you've likely noticed, this will try and create a COPS container, but it may fail as the /CalibreLibrary/Calibre Library/ folder may not yet exist. We can ignore this for the time being, and will come back to it later, but if COPS doesn't spin up properly even after this, then make sure you're pointing it to the same directory that Calibre has put its metadata.db file in. This holds true for Calibre-Web
  • In SSH, navigate to your docker/calibre directory and type sudo docker-compose up -d to create the containers
  • If you're using Portainer, I'm going to assume you already know how to create the stack, copy paste the above and hit deploy

Configuring Calibre

Once the container is up and running, you should be able to access it at http://yourmachineIP:8080, and after a bit of thinking it should throw up this screen:

ctrl+click to enlarge
  • Change the folder if necessary, however it should already be pointing at /Calibre_Library
  • Go through the next few screens to set up your preferred eBook reading device, and your smtp email settings if you have them
  • You'll then get a 'Loading' type screen, which will then open onto a retro-looking screen with one eBook on it
hit the 'maximize screen' button if necessary (top right of the calibre window)

We need to do a few configuration steps now.

  • Hit the 'Preferences' button on the right hand side of the ribbon, then hit 'Sharing over the net'. Select the 'User accounts' tab which will take you to this screen:
  • Click Add user and create your username and password. I suggest readarr as a user, as we'll need that later on, but it could be anything
  • When you've created the user, head back to the 'Main' tab, and make sure it looks like the following (boxes ticked etc.)
it is important that you keep the server port as 8081, regardless of whether you changed your published port in the compose file
  • Hit Start server, then the Apply button bottom right
  • Back on the 'Preferences' screen, select 'Behaviour':
  • Make sure you select the preferred output format for your ebook reading device, and the format order in the big box underneath it, then hit Apply
  • Back in the 'Preferences' screen, select 'Adding books', then choose the 'Adding actions' tab:
  • It's up to you how you want to configure this, but I prefer those settings in the above image. When you're satisfied, select the 'Automatic adding' tab:
  • This is where we select the docker/calibre/uploads folder we created right at the beginning of this process, by clicking the folder icon on the right hand side and navigating to the correct folder
  • Read the WARNING
  • I also check the next two boxes, then hit apply
note that to select the correct folder, you may need to hit the drop down for the path and select / to find your uploads folder, as in the next image:

Now whenever you drop an ebook file into that upload folder, Calibre will automatically import it and convert it to your preferred format.

Calibre cannot read subfolders, so if you put ebook files in subfolders into upload then Calibre won't know they're there, and there they'll sit

That's the basics set up, you can take a look at the other methods to add books, convert or remove formats yourself. Congrats, Calibre is up and running!

At this stage you should restart your Calibre container so certain settings get baked in.


Setting up COPS or Calibre-Web

COPS is a simplified way to share eBooks from your Calibre library to your reading device. One of the reasons we set up the Content Server above (Share over the net) is because COPS requires it.

The good news: you've already done the prep.

The bad news: you've got a couple more steps to go.

  • First up, make sure that the volume you mapped to /books in the compose file is the directory which includes Calibre's metadata.db file (this should be inside the newly created Calibre Library folder)
  • If your COPS or Calibre-Web container threw an error during the initial calibre creation, run docker-compose up -d again
  • If the container was created properly, then just restart it

COPS

  • Once created and/or restarted, you should be able to access it via http://yourmachineIP:80 and you'll get a screen that looks like this:
  • Hit the wrench/spanner (depending on where you're from) in the bottom left corner to access the settings screen
  • The only setting we need to change here is the email you use for emailing ebooks to yourself (such as your @kindle.com email address)

Now you'd expect that you could hit the home button, select a book (provided you have some in your Calibre Library) and then hit the little mail icon on the right to mail to you. Well no. We still need to configure the smtp server, which for some reason isn't accessible via the GUI.

  • Navigate to the docker/calibre/cops directory we set up earlier, and you should see a config_local.php file in it. Open it up with Notepad++ or whatever you use
  • Scroll to the bottom until you see the part about sending via email, and add in your credentials
note that if you're using smtp, there isn't a separate line to enter the port. Instead, you would add it after : after the URL, such as "smtp.host"  => "smtp.domain.com:port"
  • Save the .php file, restart COPS, and try and send the email again. It should now work

Calibre-Web

The Calibre-Web setup is similar, but has more options. Navigate to http://localhost:8083 in your browser, and create your admin account. Once logged in, if you already have books in your Calibre Library, they should begin populating on the screen. Top right, click the Admin button:

The Admin page

Here you can manage multiple users and set the email server settings which will allow you to 'send to kindle'.

Next to the Admin button you'll find the profile button, which will be the name of your user. Clicking this will give you a lot of options, including which email address should be used when you click the 'send to kindle' button. This last is user-specific, meaning each of your users can have their own emails here.

That's COPS and/or Calibre-Web set up and running, now for Readarr!


Setting up Readarr

Readarr works for ebooks and audio books in the same way that Sonarr does for TV shows and Radarr does for movies. It monitors books or authors and searches indexers for files to send to your download agent. It can then rename the files into the correct or preferred format of your choosing, and it even has a nifty integration with Calibre!

STOP! Before you continue, know that at time of writing Readarr is still under development and isn't a finished product. The team are still working out the kinks and quirks and and and... If you have any thoughts, suggestions, or support requests, I'd recommend visiting their Discord server

The Prep

  • I assume you already have a directory for your media downloads (either via Usenet or torrent)
  • In your docker directory, create a folder called readarr
  • Head back to your calibre's docker-compose.yml file and add the readarr block to it, so the full file looks as follows:
services:
  calibre:
    image: ghcr.io/linuxserver/calibre
    container_name: calibre
    environment:
      - PUID=$PUID #change this to your user's PID
      - PGID=$PGID #change this to your user's PGID
    volumes:
      - path/to/your/calibre/config:/config #change before the ':'
      - path/to/your/calibre/upload:/uploads #change before the ':'
      - path/to/your/calibre/plugins:/plugins #change before the ':'
      - path/to/your/CalibreLibrary:/Calibre_Library #this is where your ebooks will end up
    ports:
      - 8080:8080 #change before the ':' if necessary
      - 8081:8081 #change before the ':' if necessary
    restart: unless-stopped
    networks:
      - ebooks

  cops:
    image: lscr.io/linuxserver/cops
    container_name: cops
    environment:
      - PUID=$PUID #change this to your user's PID
      - PGID=$PGID #change this to your user's PGID
    volumes:
      - path/to/your/calibre/cops:/config #change before the ':'
      - path/to/your/CalibreLibrary/Calibre Library:/books #this directory path is correct, calibre will create the folder 'Calibre Library' when it spins up
    ports:
      - 80:80 #change before the ':' if necessary
    labels:
    depends_on:
      - calibre
    restart: unless-stopped
    networks:
      - ebooks

  readarr:
    image: ghcr.io/linuxserver/readarr:nightly
    container_name: readarr
    environment:
      - PUID=$PUID #change to your PID
      - PGID=$PGID #change to your PGID
    volumes:
      - /path/to/your/docker/readarr:/config #change before the ':'
      - /path/to/your/CalibreLibrary:/books #change before the ':'
      - /path/to/your/downloads:/downloads  #change before the ':'
    ports:
      - 8787:8787
    restart: unless-stopped
    networks:
      - ebooks

networks:
  ebooks:
    external: true
the mapped path to your readarr's /books should be the same path as your calibre's /Calibre_Library
  • Save this, and in SSH, navigate to the /docker/calibre directory and type:
sudo docker-compose up -d readarr
This should only create the readarr container without doing anything to the other two

Once the container is running, you should be able to access the readarr GUI via http://yourmachineip:8787.

Configuring Readarr with Calibre

You will need to set up your indexers and download agent settings yourself, however to integrate with Calibre it's pretty easy. The first screen you see when you spin up the container should say something like 'Nothing found' with two buttons, one of which is Add root folder. Click it.

  • You will see a relatively empty screen with a + button which says 'Add root folder'. Click it
  • The next set of images show you how to set up your Calibre integration:
  • Name it anything you want
  • Your path should look like /books/Calibre Library
  • Be sure to tick the Use Calibre checkbox
  • The host is your machine's IP address, OR calibre
  • If the host is calibre, then the port is 8081, BUT if you use the machine IP address, then the port is whatever you changed it to in your calibre docker-compose service block
  • Remember the username and password we set up in Calibre under 'Sharing over the net`? Use those credentials here
  • The Calibre Library can either be blank, or Calibre_Library
  • Next to Convert to format I have chosen mobi. This means that when readarr sends the downloaded ebook file to calibre, regardless of what it is, calibre will automatically convert it to my chosen preference
  • Hit Save

Back on the 'Media Management' screen, you should now have a fully set up root folder called Calibre (or whatever you named it). If you had books in it, you should see bottom left that readarr has already started indexing them, and they'll soon be available to view in your 'Library'.

Final things:

ctrl+click to enlarge
  • Click the 'Show Advanced' button top left
  • You may need to add a path mapping - if so, you'll see a red number next to 'System' in the left hand tray, and it will tell you that a path mapping may be required
  • Make sure to check the box next to Rename Books
  • Select whichever format you want
  • Continue scrolling down this screen making your selections for preference, then don't forget to hit Save Changes next to the now 'Hide Advanced' button top left

And that's it. You should now have Calibre, COPS and Readarr all playing nicely together.


Portainer - Easy Container Management for Docker
A step-by-step docker walkthrough to installing and configuring Portainer, your one-stop container-management resource

PTS

PTS fell down the selfhosted rabbit hole after buying his first NAS in October 2020, only intending to use it as a Plex server. Find him on the Synology discord channel https://discord.gg/vgSq5pcT

Have some feedback or something to add? Comments are welcome!

Please note comments should be respectful, and may be moderated