cops/README

= COPS =

COPS stands for Calibre OPDS (and HTML) Php Server.

COPS output is valid the unofficial OPDS validator : 
http://opds-validator.appspot.com/

= Why ? =

In my opinion Calibre is a marvelous tool but is too big and has too much 
dependencies to be used for its content server.

That's the main reason why I coded this OPDS server. I needed a simple 
tool to be installed on a small server (Seagate Dockstar in my case).

I initially thought of Calibre2OPDS but as it generate static file no
search was possible.

Later I added an simple HTML catalog that should be usable on my Kobo.

So COPS's main advantages are :
 * No need for many dependencies.
 * No need for a lot of CPU or RAM.
 * Not much code.
 * Search is available.
 * With Dropbox / owncloud it's very easy to have an up to date OPDS server.
 * It was fun to code.

= Prerequisites =

1. 	PHP 5.3 or 5.4 with GD image processing & SQLite3 support.
2. 	A web server with PHP support. I only tested with various version of Nginx.
    Other people reported it working with Apache and Cherokee.
3.  The path to a calibre library (metadata.db, format, & cover files).

On any Debian base Linux you can use :
 aptitude install php5-gd php5-sqlite

= Install =

1.  Extract the zip file to a folder in web space (visible to the web server).
2.  If a first-time install, copy config_default.php to config_local.php
3.  Edit config_local.php to match your config.

In my case I installed COPS in a subdomain. Here is my nginx config file :
server {

    listen [::]:80;

    server_name opds.mydomain.com;

    access_log  /var/log/nginx/opds.access.log;
    error_log /var/log/nginx/opds.error.log;
    root   /var/www/opds;
    index feed.php;

    location /download/ {
      rewrite ^/download/(\d+)/.*\.(.*)$ /fetch.php?data=$1&type=$2 last;
      break;
    }

    location ~ ^/images.*\.(gif|png|ico|jpg)$ {
            expires 31d;
    }

    location ~ .(js|css)$ {
            expires 31d;
    }
    
    location ~ \.php$ {
       include /etc/nginx/fastcgi_params;
       fastcgi_param   SCRIPT_FILENAME  $document_root$fastcgi_script_name;
       fastcgi_pass    unix:/tmp/fcgi.sock;
    }

    location /Calibre {
        root /home/calibre/Dropbox;
        internal;
    }
}

Beware in this case my Calibre database is in /home/calibre/Dropbox/Calibre/ so
the internal location of nginx has to split like that.

I use a Kobo eReader Touch and its browser cannot download through php file (the 
extension has to be known). To allow downloading on my ereader I added some
url rewriting (location /download/). More on rewriting later.

If your Calibre database is inside your web directory then there is no need for
an internal location.

If you choose to put your Calibre directory inside your web directory then you
will have to edit /etc/nginx/mime.types to add this line :
application/epub+zip epub;

= Notes on Opensearch =

Opensearch allow searching through an OPDS catalog. After many tests, I've been 
able to make it work Mantano Reader.

It seems that Aldiko didn't implement it properly so it won't work with COPS or
any other custom OPDS catalog.

Moon+ Reader will only work if you change the default 
configuration (cops_generate_invalid_opds_stream).

= URL rewriting =

 * Nginx :
 
    location /download/ {
      rewrite ^/download/(\d+)/.*\.(.*)$ /fetch.php?data=$1&type=$2 last;
      break;
    }
    
 * Apache (Thanks to gaspine : http://www.mobileread.com/forums/showpost.php?p=2120724&postcount=48) :
    the .htaccess :
        RewriteEngine on
        RewriteOptions inherit
        RewriteRule ^download/(.*)/.*\.(.*)$ fetch.php?data=$1&type=$2 [L]
    if you have not mod_xsendfile, in the config file simply set :
        $config['cops_x_accel_redirect'] = "location"; 
 
 * Cherokee (Thanks to Christophe) :
   * Add a Behavior of type Regular Expression : /cops/download/(.*)/.*\.(.*)$
   * Choose the handler Redirection
   * Add the substitution regexp : "/cops/download/(.*)/.*\.(.*)$" --> "/cops/fetch.php?data=$1&type=$2"

= Known problems =

 * Only tested by me with Nginx but confirmed to work with Apache and Cherokee.
 * Contain Nginx specific code (that could be changed with a config item).
 * certainly many many more.

= Disclaimer =

I only tested on Debian with Nginx so I have stricly no idea if it works
with Apache or any other web server.

On the OPDS client side I mainly tested with FBReader and Aldiko on Android.

It also seems to work with Stanza.

= Credits = 

 * All localization informations come from Calibre2OPDS (http://calibre2opds.com/)
 * Locale message handling is inspired of http://www.mind-it.info/2010/02/22/a-simple-approach-to-localization-in-php/
 * str_format function come from http://tmont.com/blargh/2010/1/string-format-in-php
 * All icons come from the package Web0 by naf1971 : http://naf1971.deviantart.com/art/Web0-182067054
 * Thanks to all testers
 
External libraries used : 
 * JQuery : http://jquery.com/
 * Fancyapps : http://fancyapps.com/fancybox/
 * Php-epub-meta : https://github.com/splitbrain/php-epub-meta with some modification by me
                   https://github.com/seblucas/php-epub-meta
 * TbsZip : http://www.tinybutstrong.com/apps/tbszip/tbszip_help.html

= Copyright & License =

COPS - 2012-2013 (c) S<>bastien Lucas <sebastien@slucas.fr>

See COPYING and file headers for license info