Advanced User Guide

Advanced setup and fine tuning

Advanced usage  

From command line run ./flibgolite -help to see run options

Usage: flibgolite [OPTION] [data directory]

With no OPTION program will run in console mode (Ctrl+C to exit)
Caution: Only one OPTION can be used at a time

OPTION should be one of:
  -service [action]     control FLibGoLite system service
          where action is one of: install, start, stop, restart, uninstall, status 
  -reindex              empty book stock index and then scan book stock directory to add books to index (database)
  -config               create default config file in ./config folder for customization and exit
  -help                 display this help and exit
  -version              output version information and exit

data directory is optional (current directory by default)

Examples:

flibgolite                     #Run FLibGoLite in console mode

flibgolite -service install    #Install FLibGoLite as a system service
flibgolite -service start      #Start FLibGoLite service

./flibgolite                          #Run FLibGoLite in console mode

sudo ./flibgolite -service install    #Install FLibGoLite as a system service
sudo ./flibgolite -service start      #Start FLibGoLite service

./flibgolite                          #Run FLibGoLite in console mode

sudo ./flibgolite -service install    #Install FLibGoLite as a system service
sudo ./flibgolite -service start      #Start FLibGoLite service

Setup and fine tuning  

1. Main configuration file  

Self-explanatory configuration file config.yml with folder tree is created at the first program run. This file is stored in the config subfolder of the program location. For advanced setup you can edit it.
Default content is as follows:

• config.yml

library:
  # Book folders
  STOCK: "books/stock" # Book stock
  TRASH: "books/trash" # Error and duplicate files and archives will be moved to this folder 
  #NEW: "books/new" # Uncomment the line to have separate folder for new acquired books

genres:
  TREE_FILE: "config/genres.xml"
 
database:
  DSN: "dbdata/books.db"
  # Delay before start each new acquisitions folder processing
  POLL_DELAY: 30 
  # Maximum parallel new acquisitions processing routines
  MAX_SCAN_THREADS: 10
  # Book queue size
  BOOK_QUEUE_SIZE: 1000
  # File queue size
  FILE_QUEUE_SIZE: 1000
  # Maximum number of books in one transaction
  MAX_BOOKS_IN_TX: 1000

logs:
  # Logs are here
  # To redirect the log output to console (stdout) just comment out the appropriate line OPDS or SCAN
  OPDS: "logs/opds.log"
  SCAN: "logs/scan.log"
  # Logging levels: D - debug, I - info, W - warnings (default), E - errors
  LEVEL: "W" 

opds:
  # OPDS-server port so opds can be found at http://<server name or IP-address or localhost>:8085/opds
  PORT: 8085
  # OPDS-server title that is displayed in a book reader
  TITLE: "FLib Go Go Go!!!"
  # OPDS feeds entries page size
  PAGE_SIZE: 30
  # Do not convert FB2 to EPUB format
  #NO_CONVERSION: true

locales:
  # Locales folder. You can add your own locale file there like en.yml, ru.yml, uk.yml
  DIR: "config/locales"
  # Default english locale for opds feeds (bookreaders opds menu tree) can be changed to:
  # "uk" for Ukrainian, 
  # "ru" for Russian 
  DEFAULT: "en"
  # Accept only these languages publications. Add others if needed please.
  ACCEPTED: "en, ru, uk"

2. Setting folders location  

To change location of a folder just edit corresponding line in config.yml For example, if you need to setup separate folder for new acquired books uncomment line

NEW: "books/new"

and change books/new to the appropriate folder path.

3. OPDS tuning  

You can change OPDS default 8085 http port to yours

# OPDS-server port so opds can be found at http://<server name or IP-address>:8085/opds
PORT: 8085

Here you can set your desired OPDS server name

# OPDS-server title that is displayed in a book reader
TITLE: "FLib Go Go Go!!!"

You can change the number of books your bookreader will load at a time when you page (pulldown/update the screen)

# OPDS feeds entries page size
PAGE_SIZE: 30

Do not set this value more than default. With lower values it updates faster.

You can disable on the fly conversion of FB2 to EPUB format, just uncomment line to set NO_CONVERSION to true

# Do not convert FB2 to EPUB format
NO_CONVERSION: true

4. Localization tips  

For additional localization there are several simple settings.

4.1. By default new books processing is limited to English, Russian and Ukrainian books. You can expand this list by adding the necessary IETF tags  , such as de, fr, it, etc.

# Accept only these languages publications. Add others if needed please.
ACCEPTED: "en, ru, uk"

4.2. By default bookreader will show menus and comments in English en If you want in Russian or Ukrainian you can change this setting to ru or uk

# Default english locale for opds feeds (bookreaders opds menu tree) can be changed to:
# "uk" for Ukrainian, 
# "ru" for Russian 
DEFAULT: "en"

4.3. If your native language is other then three mentioned above for your convenience you can make language file and put it in config/locales folder

# Locales folder. You can add your own locale file there like en.yml, ru.yml, uk.yml
DIR: "config/locales"

For example, for German, copy en.yml to de.yml and translate the phrases into German to the right of the colon separator. Leave %d format symbols untouched. Something like this:

Found authors - %d: Autoren gefunden - %d

Don’t forget to replace alphabet string ABC to German. This will ensure that German names and titles are displayed and sorted correctly.

4.4. Genres tree selection language adaptation can be done by editing the file genres.xml in config folder

  TREE_FILE: "config/genres.xml"

This can be done by adding language specific lines in genres.xml file

<genre-descr lang="en" title="Alternative history"/>
<genre-descr lang="ru" title="Альтернативная история"/>
<genre-descr lang="uk" title="Альтернативна історія"/>
<genre-descr lang="de" title="Alternative Geschichte"/>

5. Book index database  

5.1. Book index is stored in SQLite database file books.db located in dbdata folder.

DSN: "dbdata/books.db"

  Caution

Database file is created at the first program run and is not intended for manual editing

5.2. If database file is lost or corrupted, it can be restored by reindexing the books stock folder

flibgolite -reindex

sudo ./flibgolite -reindex

sudo ./flibgolite -reindex

It may take some time to complete.

5.3. The process of registering new acquisitions is presented in the diagram.

In most cases, the process of registering new acquisitions does not require configuration, since its speed is determined mainly by the performance of the input/output system (controllers, disk types, etc.). If necessary, you can change the operation of the process using the following settings:

 # Delay before start each new acquisitions folder processing
  POLL_DELAY: 30 
  # Maximum parallel new acquisitions processing routines
  MAX_SCAN_THREADS: 10
  # Book queue size
  BOOK_QUEUE_SIZE: 1000
  # File queue size
  FILE_QUEUE_SIZE: 1000
  # Maximum number of books in one transaction
  MAX_BOOKS_IN_TX: 1000

6. Logging  

While running service writes opds.log and scan.log located in logs folder.

OPDS: "logs/opds.log"
SCAN: "logs/scan.log"

opds.log contains records about bookreaders requests.
scan.log contains records about new books and archive indexing.
To redirect the log output to console (stdout) just comment out the appropriate line OPDS or SCAN.

You don’t need to delete logs to free up disk space, as logs are rotated (overwrite) after 7 days.

You can setup logging level (verbosity) to one of: D - debug, I - info, W - warnings (default), E - errors

LEVEL: "W" 

Suggestions, bug reports and comments are welcome here