Calibre2Opds Installing

Home Page	Calibre2opds User Guide						Developers Guide
	Overview	Installing	Generating	Publishing	Using	Troubleshooting

Calibre2opds Installation

This section of the documentation covers the steps required to get calibre2opds installed and running on your system.

It is split into the following main topic areas:

Pre-Requisites

You will need to have downloaded the following to be able to install calibre2opds:

• Java Runtime Environment(JRE):
  calibre2opds is written in the Java programming language. Therefore before you can use calibre2opds you need the Java runtime system installed. This tends to come as standard with Linux and Mac systems but not with Windows systems.
  • Calibre2opds 3.5 and earlier requires Java 6 or later
  • Calibre2opds 3.6 and later requires Java 7 or later. This only likely to be an issue on old 32-bit systems (e.g Windows XP, Mac OSX 10.6) as all modern systems can be expected to have Java 7 or Java 8.
  • The latest version of Java can always be obtained from the Java web site.
  • It has been found that on Windows system (especially 64 bit systems that the information to allow the calibre2opds launcher to function correctly is not always set up. It is a good idea if either the Java binaries folder needs to be added to the PATH environment variable, or the JAVA_HOME environment variable needs to be set up. If using Windows 7/Windows Vista, the easiest way to do this is as follows:
    UPDATE: The calibre2opds launcher has been upgraded so that the following steps are now optional although they are still a good idea.
    
    • Go to the Start Menu and right-click Computer and select Properties from the menu displayed
    • Select the Advanced System Settings option
    • Click the Environment Variables button
    • In the System Variables area, scroll down until you can see the JAVA_HOME environment variable. Click on this to highlight it and press the Edit button if it is shown, or press the New button if it is not shown.
    • If you had to press the New button then give the name JAVA_HOME to the environment variable.
    • Add the Java binaries install location in the value field. It will vary according to where you installed Java, but is typically something like 'C:\Program Files\Java\jre6. Press OK to accept the changes. You may have to press OK on several times to close down all the dialog.You can check your changes by starting a new Command Prompt window (it must not be an existing Command Prompt window as you need a new one to pick up the change you have just made). Typing SET PATH which will display the current setting of the PATH environment variable with all variables expanded. The path to the Java binaries should now be in the list if you have made the change correctly.

Downloading calibre2opds

Calibre2opds downloads are now hosted on Google Drive. You can always download the latest available files from there. We also provide information on the latest versions of calibre2opds that is available for download on the Calibre2opds Downloads page.

You can get older calibre2opds releases from the GoogleCode download page which is friendlier than GoogleDrive. However Google have disabled the option to add new downloads to GoogleCode which is why we have switched to GoogleDrive for newer downloads.

NOTE
When using Google Drive we have noticed that if you want the ZIP file then the Google Drive web site seems to default to showing the contents of the ZIP file with the Open link highlighted. You instead need to click on the Download link to the right of that to get such files. Other file types seem to default to downloading so are easier to handle. If anyone knows how to change this behavior we would welcome knowing the details!

For each full release of calibre2opds, there are several packages that you can download :

• A .zip file, for manual install on all platforms
• A .jar file, which is an automatic installer for all platforms
• A .exe file, automatic installer for Windows
• A .dmg file containing a Mac application

You should download the version that is appropriate for the system on which you wish to install calibre2opds. The ZIP file version does not include an installation program and requires manual installation steps. This can be appropriate on systems where the system specific installer does not work for some reason.

For beta releases we tend to only provide the ZIP file version. To use this you can either extract the contents of the ZIP file over-writing the previous calibre2opds installation. If you have no previous calibre2opds installation you can follow the process detailed below for a manual installation.

Go to the appropriate section for your operating system for more information on the steps needed to complete the installation.

Installing calibre2opds

Using the Install Packages

Windows

NOTE: There appear to be problems running the Windows installer on 64-bit versions of Windows. This seems to happen if you are using 64-bit Java on 64-bit Windows. If you are using 32-bit Java then the Installer runs without problems. If you have such a problem then use the NOINSTALLER manual method based on the ZIP file. The main calibre2opds program is quite happy with 64-bit Java - it is only the Installer that doesn't like it for some reason.

The following steps show installing using the calibre2opds Windows package calibre2opds. on a Windows 7 system. Some of the details will differ slightly on earlier versions of windows and the dialogs displayed in the screenshots could look slightly different.

calibre2opds is supplied in the form of a Windows setup program. The exact name may vary according to the release, but is typically something like calibre2opds-2.2-WINDOWS.exe To start the install you run the calibre2opds-2.2-WINDOWS.exe file.

If you have not got Java installed then you will get an error message saying that windows does not know how to handle this file type.

When the install starts up if you are running under Windows Vista or Windows 7 you will get a warning dialog that looks like the one shown below. This is standard when installing software on Windows Vista or Windows 7. This dialog will not appear on Windows XP.

If you are running on Windows 7 and do not get this dialog, then you may have to right-click the .EXE file and select the "Run as Administrator" option for the install to be successful.

You are then asked to select the language to be used.

Once you have done that you are shown the welcome dialog.

Press Next to proceed. You are now shown the ReadMe pertinent to this release. This gives general background information about calibre2opds

Press Next to proceed. You are now shown the Release Notes pertinent to this release of calibre2opds. You are strongly advised to read them before you proceed.

calibre2opds is licensed under the Open Software Foundation GPL license so this is displayed for you to read and accept.

You need to accept the license before you are allowed to proceed. Press Next to accept the license.

You are now asked to specify the install location for calibre2opds.

If the default is not what you want change it to the desired value. Press Next to proceed.

NOTE
On Windows 7, Windows 8 and Vista you may get warnings about not having relevant access permissions to the folder that you have specified should be used for installing calibre2opds. If this occurs then create the desired program folder manually, and then set the access permissions so that ordinary users have Full Control.

If the folder already exist then a warning dialog is displayed:

This is standard if you are upgrading calibre2opds. Press Next to proceed.

You are now asked to confirm some details about the installation:

Set them to the desired values. Press Next to proceed.

NOTE
If the option to set "All users" to have the shortcut is not selectable then this means you do not have Administrator privileges.

Installation of the calibre2opds files will now start. While they are being installed a dialog like the following will be displayed:

When they have completed the following dialog will be displayed:

Press Done to exit the installation program.

calibre2opds is now installed and ready to be used.

Linux

The following steps are

• Downloaded the .jar file as mentioned above

• Run the downloaded .jar file. This should invoke the java based installer

The dialogs that are displayed during the install will look like those shown for the Windows install above.

As there are many variants of Linux, if you have any problems with the Linux specific install package of calibre2opds that is supplied, then you can try the Manual install method mentioned in the previous section which is operating system agnostic.

In particular there are a very wide variety of alternative Desktops on the various Linux variants, and it is quite likely that the installer may fail to setup the menu entries required to start Calibre2opds. In such cases you will need to set up any wanted menu entries manually. The section below on the manual install may help with how to do this.

Mac

Installing with an image disk

Install on the Mac is very easy

• Download the .dmg file as mentioned above

• Open the disk image and drag the application icon to your Applications folder.

• Note that for MacOS X 10.7 and newer, there are a few security barriers and other issues that must be circumvented or worked around as follows:

1. The *.dmg file for version 3.3 (current release) is damaged. This is easily repaired using the Disk Utility app found in /Applications/Utilities. Just select the *.dmg file and click Repair Disk.
2. Because the Calibre2OPDS application is not signed by a "known" developer, it cannot be opened in the usual fashion (double-clicking). Instead, one must Control-click the repaired *.dmg file. This will invoke a dialog where you will be able to explicitly give permission to opening this suspect app without changing security settings. Read more about Apple's Gatekeeper here: http://support.apple.com/kb/HT5290?viewlocale=en_US&locale=en_US
3. The Calibre2OPDS app expects to be run from /Applications and nowhere else for some reason, not even a subfolder of the Applications folder.

Adjusting memory

When running calibre2opds you may sometimes get an error message saying there is not enough memory to generate an image thumbnail.

If you have chosen a manual install, you can fix this by increasing java heapspace memory :

• locate calibre2opds script : run.sh

• change the command line inside the script like this:
  java -Xms512m -Xmx1024m -cp ./OpdsOutput-3.0-SNAPSHOT.jar Cli $*

( ajust memory values ( here 512 and 1024) if necessary.

• Execute again run.sh to build the OPDS catalog.

NAS

If you did put your calibre library on a NAS disk, you should access your library using a file network protocol that supports locks. Otherwise calibre2opds won't be able to generate the OPDS catalog.

The following setup had been tested on Snow Leopard ( MacOS 10.6.X), using NFS to mount the NAS folder.

Suppose your calibre library is on NAS folder called /DataVolume/bibliotheque , shared through NFS with read/write access granted to everyone without authentication.

Open a terminal :

• list your NAS shares
  

 > showmount -e nas_ip_address
Exports list on nas_ip_address:
/DataVolume/bibliotheque *

• create a mount point ( for example /Volumes/bib )
  >mkdir /Volumes/bib
• mount the NAS folder
  > sudo mount -t nfs -o locallocks nas_ip_address:/DataVolume/bibliotheque /Volumes/bib/

If you prefer to use a graphical tool to mount the share see this post. Don't forget to put locallocks in the options field.

Manual Install (All Platforms)

This version of the install should work on all systems, but it does require a number of manual steps and a little understanding of how to do things at the Operating System level.

The steps involved are:

• Unpack the calibre2opds ZIP file that has been downloaded to a folder of your choice.

• The calibre2opds GUI can now be started by running the appropriate rungui file. The rungui.cmd file should be used on Windows based systems, and the rungui.sh file on Linux or Mac based systems. These are simple text based command files so if you want to you can use a text editor to look at their (very simple) contents.

• You can then (optionally) set up a shortcut to run the calibre2opds program. The easiest thing to do is to set up a shortcut to the rungui files mentioned above to provide the appropriate setting for such shortcuts.

If you re-use an existing folder, then make sure that it is empty of any files from the previous install. If you do not do this then you may encounter issues when system components are updated and you end up with both the old and new versions of the system component in the install folder.

Windows

As an example the properties of a Menu shortcut for a Windows system might look like the following

although you will need to amend the paths shown if calibre2opds has not been installed into the C:\Program Files\Calibre2Opds folder

TIP: you probably want to this the value of the Run option to say minimised. This stops a DOS Coommand Window briefly appearing while calibre2opds is launching

Linux

The steps on Linux are:

• Download the ZIP version of the software

• Unzip the contents of the ZIP download to a folder of your choice

• You can now run Calibre2opds using the rungui.sh (GUI mode) or run.sh (Batch mode) script files that are provided with Calibre2opds. You may well want to set up menu shortcuts to invoke these - the exact method by which you do this varies with different Linux distributions.

Mac

A manual install on a Mac follows a similar process to other platforms:

1. Download the ZIP package version of calibre2opds.
2. unzip the downloaded ZIP file to a folder of your choice.
3. start calibre2 pods by going into that folder and running rungui.sh (GUI mode) or run.sh (Batch mode).
4. If there are problems starting calibre2opds then running those commands from a terminal session may result in useful diagnostic information being written to the terminal window.

On a Mac it is probably easier to start by doing an install via the dmg method, and then do an upgrade via the method based on using the ZIP file. For MacOS X 10.7 and newer, there are a few security barriers and other issues that must be circumvented or worked around as follows:

1. The *.dmg file for version 3.3 (current release) is damaged. This is easily repaired using the Disk Utility app found in /Applications/Utilities. Just select the *.dmg file and click Repair Disk.
2. Because the Calibre2Opds application is not signed by a "known" developer, it cannot be opened in the usual fashion (double-clicking). Instead, one must Control-click the repaired *.dmg file. This will invoke a dialog where you will be able to explicitly give permission to opening this suspect app without changing security settings. Read more about Apple's Gatekeeper here: http://support.apple.com/kb/HT5290?viewlocale=en_US&locale=en_US
3. The Calibre2Opds app expects to be run from /Applications and nowhere else, not even a subfolder of the Applications folder.

Upgrading via the ZIP package

In most cases one can simply upgrade by following the same procedure that one used for your initial install of calibre2opds. However in some cases (particularily for test or beta releases) the full install packages are not made available. In such cases it is normally easy to upgrade an existing installation by using the ZIP version of the software.

The steps involved are:

• Download the ZIP version of the software to a know location on your computer.

• Extract the contents of the ZIP file over-writing the files in the current installation

Windows

No special steps are required - the generic instructions above should be sufficient.

Linux

No special steps are required - the generic instructions above should be sufficient.

Mac

To upgrade on a Mac using the ZIP package you use the "open package" Finder menu command on the Calibre2Opds application, and then replace all the files in the Contents/Resources/Java folder with the files in the ZIP archive.

You will then need to change the rungui.sh file so that is set to be an 'executable' file. To make it executable, open a terminal window and drag the icon of the folder where the file lives into the terminal window. That will cause the path to the folder to be displayed in the Terminal window.

Enter the command

 cd thatpath

(where thatpath is the path you saw from dragging the folder). This will leave you posisitoned in nthe folder containing the rungui.sh file. You now use the command

 chmod +x rungui.sh

After that, double-clicking on rungui.sh will execute it as a shell command and it will start up calibre2opds.

Mobile/Portable Calibre2opds

There have been requests for Calibre2opds to be run as a "mobile" application. This means the ability to run it from something like a USB stick without the need to install it on the machine that the USB stick is plugged into. Calibre can already be run in this mode so it would allow you to carry around your eBook library and associated software to manage it on a USB stick.

You can also do this using the Calibre2opds program. There is one pre-requisite in that the Java Runtime Environment (JRE) must be installed on the host machine. This is not normally an issue with Linux and Mac machines as Java typically comes pre-installed. On Windows machines this is not the case so Java needs to have been downloaded and installed before trying to run Calibre2opds in a portable mode.

If you cannot guarantee that the host system will have Java installed, then you may instead be able to take advantage of the fact that PortableApps.Com has Java working off a USB stick

The steps involved in setting up a portable installation are:

• The easiest way is to use the manual install (ZIP) version of the package and unzip it to a folder on the portable media. Alternatively you can run the normal Calibre2opds install, but instead of accepting the default location you tell it to install to the removable media that you want to run from.
• Create a batch file to start up Calibre2opds. A sample batch file for Windows is shown below. The one thing you need to do that is specific to the Calibre2opds Portable mode is to set up the CALIBRE2OPDS_CONFIG environment variable to point to to the location where the Configuration information is being stored on the USB Stick. If this environment variable is not set then the Calibre2opds software will look in the home directory of the user on the host machine - not what you want if your are trying to run in portable mode.
• Start Calibre2opds by running the batch file you have just created.
• That's it!

A sample batch file for running the Calibre2opds GUI on a Windows system would be something along the lines of:

 SET CALIBRE2OPDS_CONFIG=%cd%/Calibre2opdsConfig
 RUNGUI.CMD

The above assumes that you have created the batch file in the Calibre2opds installation folder and that within that folder you have created a Calibre2opdsConfig folder to hold the calibre2opds configuration information.

If you want to run the Command Line option of calibre2opds to generate catalogs using the saved parameters, then the corresponding batch file to set Calibre2opds in batch mode would be:

 SET CALIBRE2OPDS_CONFIG=%cd%/Calibre2opdsConfig
 RUN.CMD

As an alternative you can edit the supplied rungui.cmd and run.cmd files and add the

 SET CALIBRE2OPDS_CONFIG=%cd%/Calibre2opdsConfig

line just before the line near the end of these files that starts Calibre2opds. The disadvantage of this approach is that if you later update Calibre2opds new versions of these two files will be installed so you would have to re-apply the change.

Starting with Calibre2Opds v3.2 the supplied run.cmd/run.sh files it have been enhanced to look for the Calibre2opdsConfig folder being present. Therefore you no longer need to create a batch file, simply create the Calibre2opdsConfig folder within the Calibre2opds install folder and then start Calibre2opds using the rungui.cmd file.

Customizing Calibre2opds

There are a number of ways that Calibre2opds can be customized to suit a particular users needs. These include items such as:

• Extending the list of supported formats
• Changing the look and feel of the generated HTML catalogs
• Changing the icons that are used within the catalog.

Details of how to achieve this are found in the "Customizing Calibre2opds" section of the Developers Guide.