Oh… you didn’t think that title meant I was providing my entire ebook library to the public, did you? Sorry. Thar be no pirates here, maties. This is more of a tutorial on how I make my ebook library available to me. Onward, hoe!
I love using Calibre to maintain my ebook collection. If you have not heard of it and would like more control over your ebooks, then you should take a look. Calibre also has a built in server that you can access via a web browser. This allows you to browse your ebook collection and download them if you like. This is a really neat feature, except that the software has to be running in order to access it.
What I really want is to be able to publish this library and be able to access it from anywhere without any dependence on my computer and the Calibre software running.
This is my solution.
Is This Article For Me?
This how-to is NOT going to attempt to make this process user friendly. There is no program here that you can run to put your library online. In order to be successful with this method, you should have some familiarity with *nix shells (Bash, cygwin, etc), rsync, ant build files and you should have domain hosting.
Now, to be fair, you could publish to a local server and host it yourself. If you are doing that then you should have no problems understanding this workflow.
Calibre2Opds Setup
Other than Calibre, you’ll need the Calibre2Opds program. This is a Java program, but we’re not really concerned about that other than making sure you have Java installed (also needed for Ant). I am not going to teach you how to use Calibre2Opds. For that, please go to their website and read the documentation.
Create a custom profile that uses the Publish mode. This will allow you to generate the catalog (website) in a location outside of your Calibre library. Change the value of Books URL to /books/. By default the generated website references books that are one directory up (outside of the website). I wanted them within the website. This makes the generated webpages reference a books directory at the root of the website.
Check Destination folder is catalog only. This prevents the software from copying your entire Calibre books library to the generated website when it runs.
On the Advanced Options tab, check the Include cover images within the catalog option so that the generated website will have cover images, which is kind of nice.
That’s really it for the Calibre2Opds software. Well, the GUI portion. Make sure you save the profile as you’ll be referencing it from the ant build file.
Ant Build File
Create a directory for you build file and configuration. Within this directory create a file named build.properties. This contains configuration that is specific to your environment. View the comments within the file sample below for explanations.
; The generated website output directory build.dir=build ; Self-explanatory remote.host=yourhost.com ; Path to the hosted files (where your domain points - or where you are accessing the books library) remote.dir=~/path/to/your/website ; Path to the calibre2opds installation directory calibre2opds.dir=../calibre2opds-3.3-271M ; Path to your Calibre library calibre.lib=C:\\Users\\john.doe\\Calibre Library ; Path to your password file (on the web host - used for securing your library) pwd.path=/absolute/remote/path/to/password/file
Now the entire ant build.xml script is listed below, so you can download it and modify to your hearts desire. The basic gist of what we are accomplishing here is this.
- Run Calibre2Opds in a scripted/batch mode to create our website
- Create a .htaccess file to add a couple of mime types and also to secure online book library
- Use rsync to mirror the website files up to the web host
- Use rsync to mirror the Calibre library (the ebooks) up to the web host
The first time you run this, it will take some time depending on the size of your library. Subsequent runs, however, will be much quicker since it only needs to calculate changes to your library. And since we’re using rsync to copy the files to the web server, subsequent runs do not have to transfer every single file… thus quicker.
<?xml version="1.0" encoding="UTF-8"?>
<project name="pubopds" basedir="." default="build">
<property file="build.properties" />
<!-- Convert path since I'm using Cygwin -->
<exec executable="cygpath" outputproperty="calibre.lib.x">
<arg value="${calibre.lib}" />
</exec>
<!-- Only run this if you want to re-generate the entire website and catalog -->
<target name="clean">
<delete dir="${build.dir}"/>
</target>
<target name="build">
<mkdir dir="${build.dir}" />
<!--
The inputstring 1 is because Calibre2Opds doesn't run completely in
batch mode. It prompts the user to "be sure" if a rewrite of existing
files is desired.
-->
<java classname="Cli" inputstring="1">
<arg value="Publish" />
<classpath>
<fileset dir="${calibre2opds.dir}">
<include name="**/*.jar" />
</fileset>
</classpath>
</java>
<echo file="${build.dir}/.htaccess">AuthType Basic
AuthName "restricted area"
AuthUserFile ${pwd.path}
require valid-user
AddType application/epub+zip .epub
AddType application/x-mobipocket-ebook .mobi
</echo>
</target>
<!--
Read up on rsync to see what all the options are for. Just be sure you set
the file mode/permissions correctly or you won't be able to browse the site.
-->
<target name="deploy" depends="rsync_catalog,rsync_books" />
<target name="rsync_catalog">
<echo>Syncing catalog...</echo>
<exec executable="rsync">
<arg value="-azv" />
<arg value="--delete" />
<arg value="--checksum" />
<arg value="--exclude=/books/*" />
<arg value="--chmod=Du+rwx,Dgo+rx,Fu+rw,Fgo+r,Fugo-x" />
<arg value="--perms" />
<arg value="${build.dir}/" />
<arg value="${sshuser}@${remote.host}:${remote.dir}" />
</exec>
</target>
<target name="rsync_books">
<echo>Syncing books...</echo>
<exec executable="rsync">
<arg value="-azv" />
<arg value="--delete" />
<arg value="--chmod=Du+rwx,Dgo+rx,Fu+rw,Fgo+r" />
<arg value="--perms" />
<arg value="${calibre.lib.x}/" />
<arg value="${sshuser}@${remote.host}:${remote.dir}/books" />
</exec>
</target>
</project>
Notice that I don’t store my login credentials anywhere. I consider that bad practice, as do most people. The build file references an sshuser variable, which you can simply pass to ant on the command-line when you run the build. You may also want to setup a private ssh key so that you don’t have to enter a password to login to your remote site.
Easy Updates
Now, whenever I add new books to my Calibre library, I have but one simple command to run from a Cygwin Bash shell:
ant -Dsshuser=<MY_USERNAME> build deploy
If you don’t run the clean action, then it only needs to perform an update to the generated catalog, which means it runs faster than when you first run it. After a few minutes, my online book library is updated and I can access the new books along with my entire library… on my terms.
Accessing My Library
Now if you want to browse your ebook library from a web browser, just navigate to your new website! If you have ebook reader software that can utilize an OPDS catalog (I use Marvin), then just register it with the software (i.e. http://your.book-domain.com/index.xml) and you should be able to grab your ebooks on the fly. I’m extremely happy with the results and even more happy that I didn’t have to write software to accomplish it.