|Calibre2opds User Guide||Developer Guide|
Publishing Calibre2opds Catalogs
This section of the User Guide provides information on publishing your Calibre2opds catalog.
It is split into the following main topic areas:
To be able to use your generated Calibre2Opds catalogs you need to make them visible on the network.
NOTE: If you are using calibre2opds in Nook mode then you do not need to publish your catalogs as they will have been copied (together with their associated eBooks) to the Nook and held there as local files
The basic requirements are that:
- The method chosen provides a network path to the top level file in the generated Calibre2Opds catalog.
- The method allows all catalog files and book files to be accessed as a path relative to that of the top level catalog file.
This will tend to break down into 2 distinct families of servers:
- Standard Web server.
This can be your own private server, or one run by someone else on which you have space provided for you own web content. This could be an ISP provided web space - but if this is the case please read the caution about controlling access.
- "Cloud" file storage.
This is the generic term used to describe facilities where you can have files that are located on your own PC or Mac replicated to servers on the Internet so that they can be accessed from anywhere. Dropbox which is described here is an example of such a service, but it is far from being the only one available, although it is the only one that is definitely known to work with Calibre2opds catalogs.
Security will not be an issue if you have your library on your home system, and set up so that it can only be accessed from devices that are part of your home network.
If you make your Calibre library visible on the public Internet then you need to make sure your books are not easily accessible by unauthorised users. Depending on where you live, failure to do so may mean that you are infringing copyright
This would typically involve providing a username/password challenge or making sure the URL used is not easily found (which is what most "cloud" services use). Calibre2opds provides an option to 'encrypt' filenames used within the catalog to make the filenames less predictable.
 Web Server
Many users run web servers on their own home network, or alternatively make use of space on web servers that are provided by their ISP. The details of these can vary, but the following should provide some general guidance.
- Copy your entire Calibre library folder to a location that is visible to the web server that you are using. This will include the Calibre2Opds generated catalogs as a sub-folder of the location holding the author folders from the Calibre library.
- If you are using a public web server then they will normally tell you what URL should be used to access the files you have just uploaded.
- If you are using a NAS (Network Addressable Storage) device then you can set up calibre to directly work with the files on the NAS thus avoiding the copying requirement.
- If you are using a web server on you owwn local WiFi network and only want to access the Calibre2Opds catalogs while at home that is probably all you have to do.
If you are running on your own private web server and want to make the Calibre Library and Calibre2Opds catalogs visible on the public Internet then some additional steps will be required:
- You will need an externally visible IP address and port that can be used for accessing your private web server.
- If you are a Cable user then although strictly speaking you are probably using DHCP to get your external IP address assigned to you it tends to change very rearely so you can probably just query your modem/router to find out whqat address you are currently assigned and use that address directly. You still need to be aware that it can change.
- If you are an ADSL user connecting via a telephone line then typically the address only persists for a limited period so you need a way of gettign a more dynamic mapping of the external IP address to something you can use. there are service that provide such a capability such as XXX. Note that there is nothing that stops cable customers using such a service as well.
- Set up some NAT (Network Address Translation) entries in your router to allow an external IP port on the router to be mapped to a particular IP-Address/Port combination on your local network. This will be the IP_address:Port that is being used by the web server hosting your Calibre library and Calibre2Opds catalogs.
- Make sure you have some sort of security mechanism in place to stop unauthorised access.
Many web servers have the concept of a default page that is loaded if the user does not specify an explicit page in the URL they use to access the web site. Typically this is a file called index.htm or index.html located in the web servers document root. If you include a text file of this sort that contains content allong the lines of the following
<html> <head> <meta http-equiv="refresh" content="0;url=_catalog/index.html"> </head> <body> </body> </html>
then this will automatically redirect the user to the first catalog page without the user having to know the full URL.
 Using lighthttpd
 Server optimization
lighthttpd is a lightweight web server that can work on a NAS with low memory. If the web server crashes while you're browsing the library, add the following line in the server configuration file (lighttpd.conf):
server.event-handler = "poll"
and then restart the web server.
 Using Windows Home Server (WHS)
There is a very good blog post that covers using the web server built into Windows Home Server (WHS) to host the catalog produced by calibre2opds. Although it has not been validated the steps probably apply to anyone using Internet Information Server (IIS) on a Windows system to host the catalog.
Note in particular the requirement to set up the Mime types for the ebook types you want to be able to download. This is required because IIS ignores the Mime types set by calibre2opds in the HTML and sets it according to the file extension. If you do not know the Mime type for a particular ebook file type then you can load the HTML produced by calibre2opds; find the line for downloading a particular ebook file; and then look at the value for the 'type' parameter on the download link.
 Cloud Services
Many users want to use Cloud based services in conjunction with Calibre2opds.
At this point the only one we know definitely works is Dropbox.
It has been reported that new DropBox users no longer have the use of a Public folder that supports the use of relative URL's between files in that folder. If so, then that will mean that Dropbox is no longer a suitable candidate for holding a Calibre2opds generated catalog.
The Calibre2Opds development all started with a thread on MobileRead, where David Pierron explained how he used Dropbox (a free synching and sharing service) to publish his calibre library on the internet, and access it from his iPhone (using Stanza). This thread is available on the MobileRead Calibre forum.
Jane Lite has written a nice tutorial on her website :
The steps are:
- Install Dropbox; this creates, somewhere in your file system, a Dropbox directory (usually called "My Dropbox" or "Dropbox"). As it is explained in the Dropbox FAQ, every file you put in this directory, on in a subfolder, will automatically be published to the Dropbox "cloud", and synchronized on other computers that are linked to your Dropbox account.
- There is a special folder here, which is your public Dropbox folder; it is called "Public". Everything you put in there will be public, which means that if you give the internet address of this folder in the Dropbox "cloud" to someone else, he will be able to access your files without your Dropbox password. This is important, because for the moment this is the only place where files get consistent web addresses, and we will need this later.
- Configure Calibre to set up its library in this Public folder (or in a subfolder there) : you can do this by opening up preferences and choosing a new folder location. This will take a while.
- Wait until Dropbox has uploaded all your books (it may take a while, depending on your upload capacity). By the way, Dropbox is free for the first two gigabytes only ; for some of us, who have a lot of books, this may not be enough... Time to shell out some cash ;). DropBox also has a referral program as a way of getting additional space on free accounts.
- Download and install the calibre2opds tool, and use it to generate the catalogs as a sub-folder of the Calibre library folder you have just set up under Dropbox.
When using Dropbox it is a good idea to set the "minimise changes" option when generating a catalog as this minimises the number of files that change in DropBox between runs and thus need uploading by Dropbox after the catalog is generated. You are likely to want to also consider using the option to reuse the Calibre cover images for the catalog thumbnails and cover images as this will save space in Dropbox (at the expense of having to download a bit more data when accessing the catalog, but this is normally a good trade-off for Dropbox users where space may be more important).
- Again, wait until Dropbox has uploaded all the catalogs and thumbnails.
- Configure your ebook reader (MeagaReader/QuickReader, i2Reader, Stanza, Aldiko, another OPDS reader, or a simple browser) to access your published catalog. The exact format of the URL will depend on your Dropbox username and how you named your calibre library.
You're done !
If you need more info, if this FAQ is not clear enough, please ask a question in the forum
 Google Drive
You should NOT use Google Drive with Calibre libraries.
This is because Google Drive will silently remove the values in brackets in book folder names which are used by Calibre to track books. This invalidates the Calibre library as it breaks the links between the Calibre metadata.db file and the underlying file system..