Advanced User Guide

Advanced setup and fine tuning

Run options  

To view the run options, type ./flibgolite -help at the command prompt

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

Fine tuning  

1. Main configuration file  

Self-explanatory configuration file config.yml in 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: 300 
  # Maximum parallel new acquisitions processing routines
  MAX_SCAN_THREADS: 10
  # Book queue size
  BOOK_QUEUE_SIZE: 20000
  # File queue size
  FILE_QUEUE_SIZE: 20000
  # Maximum number of books in one transaction
  MAX_BOOKS_IN_TX: 20000
  # Level of checking new books for duplicates: N - no check, F - fast check (default) by CRC32, S - slow check by CRC32 or title and plot comparison
  DEDUPLICATE_LEVEL: "F"

logs:
  # Logs are here
  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: 20
  # Latest books period in days
  LATEST_DAYS: 14
  # Do not convert FB2 to EPUB format if set to true, default: false
  NO_CONVERSION: false

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 book folder location  

By default, FLibGoLite adds books from the books/stock folder to the OPDS catalog and does not move them anywhere. To change the folder location, simply edit the corresponding line in config.yml

  STOCK: "books/stock" # Book stock

and change books/stock to the appropriate folder path.

  Caution

In paths, use forward slash / instead of backslash \.

You can also do this by creating a link to another folder on the disk where your books are located.
For example:

mklink /J .\books D:\path\to\books

ln -s /path/to/books ./books

3. OPDS tuning  

3.1. 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

3.2. Here you can set your desired OPDS server name

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

3.3. 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: 20

  Warning

Do not set this value significantly higher than the default. This may make page refreshing or scrolling uncomfortable.

3.4. You can disable on the fly FB2 to EPUB format conversion when downloading books to the e-reader, 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 possible 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 files books.db located in dbdata folder.

DSN: "dbdata/books.db"

  Caution

Database files are created at the first program run and are not intended for manual editing

5.2. If database files are lost or corrupted, they can be restored by reindexing the books stock folder

flibgolite -reindex

sudo ./flibgolite -reindex

It may take some time to complete.

  Note

The same can be done manually: stop the service, delete the database files and start the service again.

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: 300 
  # Maximum parallel new acquisitions processing routines
  MAX_SCAN_THREADS: 10
  # Book queue size
  BOOK_QUEUE_SIZE: 20000
  # File queue size
  FILE_QUEUE_SIZE: 20000
  # Maximum number of books in one transaction
  MAX_BOOKS_IN_TX: 20000

6. Logging  

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

  # Logs are here
  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.

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

  # Logging levels: D - debug, I - info, W - warnings (default), E - errors
  LEVEL: "W" 

Suggestions, bug reports and comments are welcome here