Skip to content

Instantly share code, notes, and snippets.

@plembo
Last active January 5, 2024 04:26
  • Star 50 You must be signed in to star a gist
  • Fork 8 You must be signed in to fork a gist
Star You must be signed in to star a gist
Save plembo/337f323e53486cbdb03100692ae8c892 to your computer and use it in GitHub Desktop.
Calibre Server on Linux

Calibre Server on Linux

Introduction

Calibre is a powerful cross-platform, open source, ebook manager and editing platform. Its calibre-server component can be used to publish an e-book library on a local network. While you can launch calibre-server as a desktop application, it can also be run as a daemon on a headless Linux server.

This tutorial on setting up calibre-server using Ubuntu 14.04 is very good, but dated.

The following recipe comes from my personal notes on setting up our family library server on Ubuntu 16.04 LTS. I have reproduced the results on the latest Ubuntu 18.04 LTS Server. With a few minor adjustments this could be used to set up a similar server on Fedora or other Linux distributions.

Preparation of the server

I prefer to get my servers all set up from the console and then use ssh to complete my preparation, mostly because I can copy and paste into an ssh terminal. As a result, the first things I check on every server build are: (a) Allow port 22 through the host firewall; (b) Make sure an ssh server is installed. On Ubuntu, the stock firewall is ufw and the ssh server is openssh-server. The latest Ubuntu LTS Server (18.04) ships with ssh enabled but ufw disabled.

Calibre system user

Create a calibre system user and group that will run the daemon. The server will need write privileges to the directory where the calibre database is kept, which by default is the home directory of the user who runs the application. I recommend selecting something other than "/home" for this to maintain separation from user and application data.

In the example that follows the user will be "calibre", and its home directory, "/d1/media/calibre".

sudo useradd -c "Calibre Server" -d /d1/media/calibre -s /bin/bash -m calibre

Also create a directory for uploading new e-books, like:

sudo mkdir -p /d1/upload/ebooks

Permission this so the calibre user owns it, and everyone else can read and write in it:

sudo chown calibre:calibre /d1/upload/ebooks
sudo chmod ugo+rw /d1/upload/ebooks

Firewall

If you're running a host firewall (you are, aren't you?), you'll need to configure it to allow traffic to whatever port the Calibre Server will be listening on. The default is the ubiquitous TCP 8080. To avoid conflicts with other software that may be (and probably are) using that, you can set it to another unused port. I chose 8180.

On Ubuntu Server the ufw firewall can be configured to do this:

ufw enable
ufw allow 8180

Additional packages

  • imagemagick
  • xvfb
  • libxcomposite1

Calibre needs ImageMagick to manipulate graphics, while xvfb is required for running Calibre's services in a headless (no graphical desktop) environment. A completely fresh server install may require libXcomposite for other basic graphics handling.

You may also find it helpful to install xterm for managing things in an ssh -X session (and yes, I should do a comprehensive gist on how to set that up, but not right now).

Install Calibre

As a user with admin (sudo) rights, go to the official Calibre Download page for Linux and follow the instructions there for installation.

Note that you may receive some warnings related to desktop integration, these are safe to ignore because you won't need to use the desktop interface (unless you want to, in which case you could install over a VNC session: but that's outside the scope of this note).

The script you'll run will look something like this:

sudo -v && wget -nv -O- https://download.calibre-ebook.com/linux-installer.sh | sudo sh /dev/stdin

Note: If this is the first time you've installed a graphical application with that user account you may have to re-permission the ~/.config folder, as the installer will create it as root if it doesn't find it:

cd ~
sudo chown -R myuser:myuser .config
## Post Install Tasks

Post Install Tasks

Now log in as the calibre user and create the ~/calibre-library directory to hold the ebook database.

Download a sample e-book to load into the library:

wget http://www.gutenberg.org/ebooks/219.epub.noimages -O /d1/upload/ebooks/heart.epub

As the calibre user, add an e-book to the library:

xvfb-run calibredb add /d1/upload/ebooks/heart.epub --library-path ~/calibre-library

To test the server, launch with the following command:

calibre-server --port=8180 --enable-local-write /d1/media/calibre/calibre-library

Then access the library with a web browser, using the url:

http://hostname.example.com:8180

Substitute your server's FDQN for "hostname.example.com" in the above fake url.

Custom Calibre configuration

Calibre's global.py allows you to change the default configuration in helpful ways. It is in the calibre user's home directory (in this example, /d1/media/calibre) under ~/.config/calibre. The main parameters to change here are database_path and library_path. In my installation these are both set as follows:

database_path = u'/d1/media/calibre/calibre-library/metadata.db'
library_path = u'/d1/media/calibre/calibre-library'

The "u" leading the setting for these paths is intentional, be sure to include it (Calibre is written in python, and this is a python thing).

Creating an init script

The main difference between previous tutorials using the Ubuntu 14.04 release and later versions is that since 14.04 you would now need to create a systemd init instead of an upstart init script.

[Unit]
Description=calibre content server
After=network.target

[Service]
Type=simple
User=calibre
Group=calibre
ExecStart=/opt/calibre/calibre-server \
--port=8180 --enable-local-write \
/d1/media/calibre/calibre-library

[Install]
WantedBy=multi-user.target

Name the script "calibre-server.service" and copy it to /etc/systemd/system.

Then enable and start with:

systemctl enable calibre-server
systemctl start calibre-server

Check for errors with "systemctl status calibre-server".

The above init script is based on a sample provided in the Calibre manual.

Adding (or removing) e-books

Of course you'll want to add e-books to the server. When running in daemon mode the best way to do this is to use the command line tool, calibredb, that comes with Calibre.

xvfb-run calibredb add /d1/upload/ebooks --with-library http://localhost:8180

Notice the addition of the "--with-library" option above. This is necessary because with the server running the database can only be modified through its web service. In this case, calibredb connects to the server through the web service to make the necessary changes.

Setting up a reverse web proxy

This is entirely optional. E-book readers like FB Reader have plugins that allow them to connect to a Calibre library server through Calibre's web service, but in my house we mostly use our web browsers.

If you're like me and can't recall what you had for breakfast, let alone what port a particular service might be running on, you can use a web server to reverse proxy the Calibre service. A reverse proxy is different from a redirect in that the reverse proxy preserves the url originally used by the client through the whole conversation.

Here is an example of an nginx virtual host located on the same server as Calibre that can accomplish that:

server {
    listen 10.0.0.20:80;
    server_name library.example.com;
    root /var/www/html;
    index index.html;
    location / {
        proxy_pass http://127.0.0.1:8180/;
    }
}

In this case my users can simply go to "http://library.example.com" and reach the Calibre Server without having to know the backend hostname or port Calibre is listening on.

The "listen" directive above contains the IP address that the site name resolves to, while "server_name" is the DNS name of the site.

Document "root" really doesn't matter in this vhost because there's no static content to serve up beyond what Calibre provides.

The "location" block is key: basically it tells the server to proxy everything it gets from the root of the Calibre server. Proxying the locahost address allows me to drop the firewall rule allowing remote users to connect directly to Calibre over port 8180.

@d-salinas
Copy link

Do you know what would be the best way to add a second library on the server?
Thank you!

@plembo
Copy link
Author

plembo commented Nov 5, 2019

Never thought about it, but to keep it simple I might try running calibre-server in a full kvm (libvirtd) guest, again using nginx to proxy the connection to the outside (even if the guest is using the local kvm private network instead of a bridge, nginx on the host can still get to it using the guest's internal address). You could try using an lxc container, but after experimenting with that just now I can already see it may be a rabbit hole due to lxc's spotty x11 support. The first bionic image for lxc I downloaded (ubuntu:bionic) didn't have xvfb in its repo. But I was able to find one that did, images:ubuntu/bionic. Whatever type of virtualization you use, the main idea would be to keep each instance completely separated from the other at the system level. Otherwise you'd have to negotiate both port and (service) namespace conflicts.

@librafrog
Copy link

Does someone find a way to log out a user once log in. It says restart browser but it dosn't work. I'm asking for Windows still also on other platforms ❔

@plembo
Copy link
Author

plembo commented Mar 16, 2021 via email

@librafrog
Copy link

I'm using Edge. It seems cookies related. I've clear them and after an pending update of browser it works now.

@plembo
Copy link
Author

plembo commented Mar 18, 2021

Edge (Chromium) shares Google Chrome's persistence in caching content (and cookies). Makes testing changes an exercise in frustration, especially if you're in an environment where regularly purging history is inconvenient (e.g. protected by Azure AD SSO with MFA). "Incognito" or "InPrivate" windows rarely help, same with the old F5 trick. It gets even worse when you've got an intervening CDN (where even purging history won't help).

@pineapples5972
Copy link

Do you know what would be the best way to add a second library on the server? Thank you!

Inorder to have multiple libraries running on same server just add the different library path to the main command
i.e. /<path/calibre-server --port=8180 --enable-local-write /home/you/library/fiction /home/you/library/tech

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment