README.md 4.46 KB
Newer Older
ale's avatar
ale committed
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23
liber
=====

Software to manage an ebook collection. It supports EPUB, MOBI and PDF
formats, and it will fetch metadata and cover images on external
sources (currently Google Books). It offers powerful search
functionality over a HTTP interface.

Another useful feature is the ability to synchronize remote
collections (currently in one direction only), making it possible for
a group of people to manage a centralized ebook repository.


## Installation

Binaries are available in the form of Debian packages. They will take
care of installing all the necessary dependencies. If this isn't an
option, you can build the software from source.

### Debian packages

Add this line to your `sources.list`:

ale's avatar
ale committed
24
    deb http://www.incal.net/ale/debian liber/
ale's avatar
ale committed
25 26 27 28 29 30 31 32 33

Then make sure the GPG key used to sign the repository is installed,
update the package sources, and install the `liber` package:

    $ wget -O- http://www.incal.net/ale/debian/repo.key \
        | sudo apt-key add -
    $ sudo apt-get update
    $ sudo apt-get install liber

ale's avatar
ale committed
34 35 36 37 38 39 40 41 42
*Note*: on Debian Wheezy, you will need to install the `libleveldb1`
package from the backports repository (see the
[Debian backports website](http://backports.debian.org/) for
instructions on how to set that up) before running the commands
mentioned above:

    $ apt-get install -t wheezy-backports libleveldb1


ale's avatar
ale committed
43 44 45 46 47 48 49 50 51 52 53
### Build from source

The source has a few dependencies:

* A working [Go](http://golang.org/) environment (note that the Go
  version in Debian wheezy is too old, you should install a more recent
  version from the Go website);
* LevelDB (and Snappy)

Some of the Go packages that `liber` depends upon have their own list
of dependencies ([Bleve](http://blevesearch.org/) in particular) which
ale's avatar
ale committed
54
you will also need to install. On a Debian-based system, the following
ale's avatar
ale committed
55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95
command should suffice:

    $ sudo apt-get install build-essential libleveldb-dev \
        libsnappy-dev libicu-dev libstemmer-dev

You should then install Bleve, enabling some necessary features:

    $ go get -u -tags 'leveldb icu libstemmer' github.com/blevesearch/bleve

And then download and install the `liber` source code:

    $ go get -d git.autistici.org/ale/liber
    $ go install git.autistici.org/ale/liber/...

This will place the resulting `liber` executable in `$GOPATH/bin`.


## Usage

`liber` will store its database in a local directory, `~/.liber` by
default. Use the `--db-dir` option if you'd like to change this.

If you want to manage a local collection, the assumption is that you
are storing all your ebooks in a single place (below a single
directory, possibly organized into further subdirectories). You can
control this with the (mandatory) option `--book-dir`.

### Indexing a local ebook collection

To index a local ebook collection, run the following command:

    $ liber --book-dir=/path/to/ebooks --update

The tool will attempt to identify books on Google Books. It is
possible that more than one match is found, in which case `liber` will
open a dialog box to ask you interactively to pick the right match.

You can run `liber --update` as many times as you like (for example
whenever you add an ebook to your collection), it will automatically
detect new files and files that have been removed.

ale's avatar
ale committed
96 97 98 99 100 101 102
#### Integration with Calibre

If you use Calibre to mantain your ebook collection, you can index it
with `liber` by simply pointing its `--book-dir` option at the Calibre
library directory. `liber` will read Calibre metadata files and cover
images, and it will not perform remote searches for book metadata.

ale's avatar
ale committed
103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134
### Searching

You can search the index from the command line, for example:

    $ liber --search "Das Kapital"

This will print a list of documents that match the query. For the full
query syntax, see
[the Bleve documentation](https://github.com/blevesearch/bleve/wiki/Query-String-Query).

### Synchronizing with a remote server

To upload the contents of the local database (including the file
contents themselves) to a remote `liber` server, run the following
command:

    $ liber --sync=http://remote.server.address/


### Running the HTTP interface

The HTTP interface can be started with:

    $ liber --http-server=:3000 --book-dir=/path/to/ebooks

This will start an HTTP server on port 3000, listening on all
interfaces. The HTTP server needs some templates and static content
which the Debian package installs in `/usr/share/liber/htdocs`.

The HTTP server will store uploaded files into the directory specified
by `--book-dir`. You should use the same value that you passed to
`liber --update`.