Sourcefabric Manuals

 English |  Español |  Français |  Italiano |  Português |  Русский |  Shqip

Booktype 2.4 for Authors and Publishers

Manual installation on GNU/Linux

This chapter covers installing Booktype manually from the command line, based on the Booktype repository at GitHub (https://github.com/booktype/Booktype/). It has been tested on Debian 8 (jessie) and Debian 9 (stretch) using sudo for root access.

Installing dependencies

You will probably need to install some of Booktype's Python dependencies using pip (https://pypi.python.org/pypi/pip) or easy_install. This is because most GNU/Linux distributions do not supply the specific versions of packages required to run Booktype.

First, install the development packages, RabbitMQ server, Redis server (http://redis.io/), pandoc converter and the tidy syntax checker. On Debian or Ubuntu, you can do this in a terminal with the apt command:

sudo apt install git-core pandoc python-dev python-pip libjpeg-dev libpq-dev libxml2-dev libxslt1-dev rabbitmq-server redis-server tidy

Installing a web server

The Apache web server can be used to serve your Booktype instance to other authors and project collaborators, either on the public Internet or local networks. To use Booktype with Apache, you need to install the module for WSGI (the Web Server Gateway Interface). You can read the Django documentation at https://docs.djangoproject.com/en/1.9/howto/deployment/wsgi/modwsgi/ for more details.

You can install the Apache web server and the WSGI module with the command:

sudo apt install apache2 libapache2-mod-wsgi

Installing Booktype from the git repository

The git repository is an online collaboration server which contains the most up-to-date version of Booktype available.

1. Download a copy of Booktype from the git repository to the /usr/local/src/booktype/ directory:

cd /usr/local/
sudo mkdir src/booktype/
sudo git clone https://github.com/sourcefabric/Booktype.git --branch master --depth 1 src/booktype/

2. Optionally, you might wish to use a Python virtual environment, for example if you are developing other Python applications with different library requirements on the same server. This step can be omitted on a server which only runs Booktype.

sudo apt install python-virtualenv virtualenv
sudo virtualenv venv
source venv/bin/activate

3. Install the requirements for development and a production install with PostgreSQL. You may need to upgrade your version of setuptools first:

sudo easy_install -U setuptools
sudo pip install -r /usr/local/src/booktype/requirements/dev.txt sudo pip install -r /usr/local/src/booktype/requirements/prod.txt

Creating a Booktype instance

1. Create a directory for the Booktype instances such as /var/www/booktype/ and make sure it is owned by the www-data user which runs the web server:

sudo mkdir /var/www/booktype/
sudo chown www-data:www-data /var/www/booktype/

Distributions other than Debian or Ubuntu, including Red Hat Enterprise Linux and CentOS, may have the web server running under another username, such as httpd.

Optionally, if you will be using the nano text editor to configure the Booktype server, you might wish to create a preferences directory for the www-data user to write to:

sudo mkdir /var/www/.nano

2. Switch to the www-data user and create the first Booktype instance with a postgresql database in the /var/www/booktype/instance1 directory:

sudo su -s /bin/sh www-data
cd /usr/local/src/booktype/scripts/
./createbooktype --check-versions --database postgresql /var/www/booktype/instance1

The server will respond:

+ Trying to import Django.   [OK]
+ Trying to import booktype.   [OK]
+ Trying to import lxml.   [OK]
+ Trying to import Python Imaging Library (PIL/Pillow).   [OK]
+ Trying to import Redis module.   [OK]
+ Trying to import Unidecode module.   [OK]
+ Creating data directory.   [OK]
+ Creating logs directory.   [OK]
+ Creating static directory.   [OK]
+ Creating lib directory.   [OK]
+ Creating conf directory.   [OK]
+ Creating instance1_site directory.   [OK]
+ Creating settings directory. [OK]
+ Creating urls directory. [OK]
+ Creating templates directory. [OK]
+ Creating locale directory. [OK]
+ Creating static directory. [OK]
+ Creating data/books directory.   [OK]
+ Creating data/profile_images directory.   [OK]
+ Creating data/cover_images directory.   [OK]
+ Creating booktype_dev.env file.   [OK]
+ Creating booktype_stage.env file.   [OK]
+ Creating booktype_prod.env file.   [OK]
+ Creating manage_dev.py file. + Creating manage_dev.py file.   [OK]
+ Creating manage_stage.py file. + Creating manage_stage.py file.   [OK]
+ Creating manage_prod.py file. + Creating manage_prod.py file.   [OK]
+ Creating instance1_site/__init__.py file.   [OK]
+ Creating instance1_site/settings/__init__.py file.   [OK]
+ Creating instance1_site/urls/__init__.py file.   [OK]
+ Creating instance1_site/settings/base.py file.   [OK]
+ Creating instance1_site/settings/dev.py file.   [OK]
+ Creating instance1_site/settings/stage.py file.   [OK]
+ Creating instance1_site/settings/prod.py file.   [OK]
+ Creating instance1_site/settings/prod.py file.   [OK]
+ Creating booktype2mpdf.php file.   [OK]
+ Creating epub2icml_content file.   [OK]
+ Creating epub2docx_content file.   [OK]
+ Creating pytest.ini file. + Creating pytest.ini file.   [OK]
+ Creating conftest.py file.   [OK]
+ Creating instance1_site/urls/dev.py file.   [OK]
+ Creating instance1_site/urls/stage.py file.   [OK]
+ Creating instance1_site/urls/prod.py file.   [OK]
+ Creating booktype.wsgi_dev file.   [OK]
+ Creating booktype.wsgi_stage file.   [OK]
+ Creating booktype.wsgi_prod file.   [OK]
+ Creating supervisor_stage.conf file. [OK]
+ Creating supervisor_prod.conf file. [OK]
+ Creating wsgi_stage.apache file.   [OK]
+ Creating wsgi_prod.apache file.   [OK]
+ Creating gunicorn_stage.nginx file.   [OK]
+ Creating gunicorn_prod.nginx file.   [OK]
+ Creating factcgi_stage.nginx file.   [OK]
+ Creating factcgi_prod.nginx file.   [OK]
+ Copying themes

Check [/var/www/booktype/instance1] directory for created files:
   booktype_dev.env          -  Environment dev variables
   booktype_stage.env        -  Environment stage variables
   booktype_prod.env         -  Environment production variables
   manage_dev.py             -  Manage file for dev profile
   manage_stage.py           -  Manage file for stage profile
   manage_prod.py            -  Manage file for prod profile
   pytest.ini                -  Global py.test configuration
   conftest.py               -  Py.test configuration with fixtures and db pre settings
   epub2docx.sh              -  Pandoc convertion script from epub to docx
   epub2icml.sh              -  Pandoc convertion script from epub to icml
   booktype2mpdf.php         -  Configuration and convertion script for mpdf

   conf/                     -  Configuration files
     wsgi_stage.apache       -  Apache config file for stage instance
     wsgi_prod.apache        -  Apache config file for prod instance
     gunicorn_stage.nginx    -  Nginx config file for stage instance
     gunicorn_prod.nginx     -  Nginx config file for prod instance
     fastcgi_stage.nginx     -  Nginx config file for stage instance
     fastcgi_prod.nginx      -  Nginx config file for prod instance
     supervisor_stage.conf   -  Supervisor config file for stage instance
     supervisor_prod.conf    -  Supervisor config file for prod instance

   lib/                      -  Local python libraries
   static/                   -  Deployed static files
   data/                     -  Attachments, Covers, ...

   instance1_site            -  Booktype project
     locale/                 -  Local translations
     templates/              -  Local templates
     static/                 -  Local static files
     wsgi_dev.py             -  WSGI file for Apache
     wsgi_stage.py           -  WSGI file for Apache
     wsgi_prod.py            -  WSGI file for Apache

     settings/               -  Settings configurations
       base.py               -  Base configuration
       dev.py                -  Development configuration
       stage.py              -  Stage configuration
       prod.py               -  Production configuration
       test.py               -  Testing configuration

     urls/                   -  URL routers
       dev.py                -  For Development profile
       stage.py              -  For Production profile
       prod.py               -  For Production profile

For further instructions read INSTALL file.

3. Change to the instance directory that was just created, and edit the base.py file which contains basic settings for the instance:

cd /var/www/booktype/instance1/
nano instance1_site/settings/base.py

There are several sections of this file which need to be edited to suit your installation. All values need to be in either single or double quotes. First, set the name and email address of the system administrator:

ADMINS = (
    # ('Your Name', 'your_email@example.com'),
)

Set the active profile to 'dev' for development or 'prod' for production:

PROFILE_ACTIVE = 'dev'

Enter the site name of your Booktype server:

BOOKTYPE_SITE_NAME = 'Booktype site'

Enter email and outgoing mail server details:

DEFAULT_FROM_EMAIL = 'robot@example.com'
REPORT_EMAIL_USER = 'booktype@example.com'

EMAIL_HOST = os.environ.get('BOOKTYPE_EMAIL_HOST', 'localhost')
EMAIL_PORT = os.environ.get('BOOKTYPE_EMAIL_PORT', 25)

If you are using mPDF for PDF output, set the path to the mPDF renderer:

MPDF_DIR = os.environ.get('BOOKTYPE_MPDF_DIR', '/var/www/mpdf-6.1.3/')

For DOCX or ICML output, set the path to the pandoc converter. If you have installed the official Debian or Ubuntu package of pandoc, this will be /usr/bin/pandoc as follows:

PANDOC_PATH = os.environ.get('BOOKTYPE_PANDOC_PATH', '/usr/bin/pandoc')

Enter the name of the default publisher, if none is specified by the book author or editor:

DEFAULT_PUBLISHER = "My Publisher"

If you have more than one application using the local Redis server, you will need to change the value of REDIS_DB to a number other than zero. (See Multi-instance installation). The default for REDIS_PASSWORD is None, but if your Redis server requires a password, it must be surrounded by single or double quotes.

REDIS_PASSWORD = os.environ.get('BOOKTYPE_REDIS_PASSWORD')
REDIS_DB = os.environ.get('BOOKTYPE_REDIS_DB', 0)

Set the instance time zone and language code, for example in the case of Great Britain:

TIME_ZONE = 'Europe/London'

LANGUAGE_CODE = 'en-gb'

The translations of the Booktype interface are independent of the language used in the books. For example, an editor working on a book in Punjabi can use the Japanese interface, if they wish. You can remove any of the default interface translations that you do not require from the list.

LANGUAGES = (
    ('en', gettext('American English')),
    ('en-gb', gettext('British English')),
    ('ca', gettext('Català')),
    ('cs', gettext('Česky')),
    ('de', gettext('Deutsch')),
    ('el', gettext('Ελληνικά')),
    ('es', gettext('Español')),
    ('et', gettext('Eesti keel')),
    ('fr', gettext('Français')),
    ('it', gettext('Italiano')),
    ('ja', gettext('日本語')),
    ('ko-kr', gettext('한국어')),
    ('hu', gettext('Magyar')),
    ('nl', gettext('Nederlands')),
    ('nb', gettext('Norsk (Bokmål)')),
    ('pa', gettext('ਪੰਜਾਬੀ')),
    ('pl', gettext('Polski')),
    ('pt', gettext('Português')),
    ('pt-br', gettext('Português do Brasil')),
    ('ru', gettext('Русский')),
    ('sq', gettext('Shqipe')),
    ('fi', gettext('Suomi')),
    ('tr', gettext('Türkçe')),
    ('uk-ua', gettext('українська мова')),
)

When you have completed your changes, press Ctrl+O to save the file and Ctrl+X to quit the nano editor.

4. Edit the dev.py file which contains development settings for the instance:

nano instance1_site/settings/dev.py

Enter the domain name and URL of your Booktype development server:

THIS_BOOKTYPE_SERVER = os.environ.get('BOOKTYPE_SERVER', 'booktype.example.com')

BOOKTYPE_URL = os.environ.get('BOOKTYPE_URL', 'http://booktype.example.com')

The database connection parameters should be similar to the following example:

DATABASES = {
'default': {
'ENGINE': 'django.db.backends.postgresql_psycopg2',           'NAME': 'booktype-db',           'USER': 'booktype-user',           'PASSWORD': 'booktype-password',           'HOST': 'localhost',           'PORT': ''
     } }

where booktype-password is the password that you set for the booktype-user when you created the booktype-db database in PostgreSQL. See the chapter Setting up the database for details.

With these settings completed, press Ctrl+O to save the file and Ctrl+X to quit the nano editor.

5. Load the environment variables for the dev profile:

. ./booktype_dev.env

(When you are ready to move to the production database, you can add the database details to the production settings file, such as instance1_site/settings/prod.py and use the booktype_prod.env environment variables instead).

6. Migrate the database:

./manage_dev.py migrate

The server might respond with a list of migrations it is applying.

7. Create a superuser account for the Booktype administrator:

./manage_dev.py createsuperuser

Enter the required information as prompted:

Username (leave blank to use 'www-data'): admin
E-mail address: your_email@example.com
Password:
Password (again):
Superuser created successfully.

8. Collect static files from the Booktype component applications into a single directory, using the 'collectstatic' option. If you are using the production profile, you should also use the 'compress' option.

./manage_dev.py collectstatic

9. Fetch all installed Django applications and update their permissions, then update the default roles for registered and anonymous users:

./manage_dev.py update_permissions
./manage_dev.py update_default_roles

Installation is now complete. Return to your normal user prompt and deactivate the virtualenv, if you are using one, with the commands:

exit
deactivate

so that you are no longer entering commands as the www-data user in the virtualenv called venv. You can now configure Apache to serve your new Booktype instance.

Apache configuration

1. Copy the wsgi_prod.apache file generated during the creation of the instance to the Apache configuration directory for virtual hosts:

sudo cp /var/www/booktype/instance1/conf/wsgi_prod.apache /etc/apache2/sites-available/booktype-instance1.conf

3. Edit the virtual host configuration file for the instance:

sudo nano /etc/apache2/sites-available/booktype-instance1.conf

Set the value of WSGIScriptAlias to the development profile wgsi_dev.py while testing the instance:

     WSGIScriptAlias / /var/www/booktype/instance1/instance1_site/wsgi_dev.py

You should change at least the values for ServerName, ServerAdmin and SetEnv HTTP_HOST to match the domain name configured for the server.

<VirtualHost *:80>

     ServerName booktype.example.com      SetEnv HTTP_HOST "booktype.example.com"
ServerAdmin admin@example.com

You should also set the locale for time zone and language if they are not correct:

    SetEnv LC_TIME "en_GB.UTF-8"
    SetEnv LANG "en_GB.UTF-8"

For Location and Directory stanzas, uncomment Require all granted for Apache 2.4 unless you have mod_access_compat installed:

     <Location "/">
       #Require all granted
       Options FollowSymLinks
     </Location>

The paths for static image, CSS and JavaScript files used in the interface should point to the path where you installed your Booktype instance. Using these paths, any custom changes to the static files would be overwritten on upgrade. If you wish to customise the appearance of the instance, you should make a copy of the static files outside of the Booktype installation directory, then update these alias paths in the Apache virtual host configuration.

Alias /static/ "/var/www/booktype/instance1/static/"
     <Directory "/var/www/booktype/instance1/static/">
       Require all granted
       Options -Indexes
     </Directory>

Press Ctrl+O to save the file and Ctrl+X to quit the nano editor.

4. Enable the Booktype virtual host for the instance, and disable the default site if you aren't using it, with the commands:

sudo a2ensite booktype-instance1.conf
sudo a2dissite 000-default.conf

5. Ensure the WSGI module is loaded, then restart the Apache web server:

sudo a2enmod wsgi
sudo invoke-rc.d apache2 restart

You should now be able to browse your Booktype instance at the URL defined in the VirtualHost configuration, such as http://booktype.example.com/ in the example above.

Subdirectory installation

It is possible to serve a Booktype instance under a URL such as http://www.example.com/booktype/ or similar. You would have to set the THIS_BOOKTYPE_SERVER value in the base.py, dev.py or prod.py settings file, and adjust your Apache configuration file to point to that subdirectory.

Running celery with supervisor

If you have a permanent installation of Booktype, you will need a process monitor to keep the celery workers running. You can install supervisord on Debian or Ubuntu GNU/Linux with the command:

sudo apt install supervisor

The supervisord program should then start up, and be configured to start automatically on the next reboot of the server. Next, we have to create a configuration file to use with Booktype and celery:

sudo nano /etc/supervisor/conf.d/booktype-instance1.conf

For the first Booktype instance in /var/www/booktype/instance1 with ten workers, the contents of the file booktype-instance1.conf should be similar to:

[program:celeryd]
command=/var/www/booktype/instance1/manage_dev.py celery worker --concurrency=10 -l info
autostart=true
autorestart=true
startretries=3
stderr_logfile=/var/www/booktype/instance1/logs/booktype-celery.error.log
stdout_logfile=/var/www/booktype/instance1/logs/booktype-celery.output.log
user=www-data

After saving the booktype-instance1.conf file, re-read and update the supervisord configuration with the commands:

sudo supervisorctl reread
sudo supervisorctl update

The supervisorctl program can also be used to check that supervisord is running celeryd:

sudo supervisorctl

The output of this command should be similar to:

celeryd                          RUNNING    pid 24182, uptime 0:13:19

To exit from the supervisorctl program, which has its own command prompt, use the quit command:

supervisor> quit

This quit command does not stop supervisord itself.

Installing Calibre for .mobi publishing

Optionally, Booktype can use calibre (http://calibre-ebook.com/) for publishing ebooks in the .mobi format (http://wiki.mobileread.com/wiki/MOBI). Calibre is a large program with many dependencies, so you may prefer not to install it on your Booktype server unless you actually need .mobi output.

On Debian or Ubuntu, you can install Calibre with the command:

sudo apt install calibre

Multi-instance installation

You can have more than one Booktype instance on your server, with each instance having a unique URL, and a distinct set of users and books. To do this, create multiple Booktype instances under different filesystem paths such as /var/www/booktype/instance2, /var/www/booktype/instance3 and so on. Then you should customise the Redis, RabbitMQ, Supervisor and Apache configuration for each instance, as follows.

Redis

Each Booktype instance on the same server has to connect to a different Redis database. The default setting of REDIS_DB is zero. For the second instance, this value might be 1 (assuming nothing other than Booktype is using Redis on the system):
REDIS_DB = 1

RabbitMQ

To create a new RabbitMQ virtual host for the second instance and allow the default guest user to access it, you can use the commands:

sudo rabbitmqctl add_vhost instance2
sudo rabbitmqctl set_permissions -p instance2 guest ".*" ".*" ".*"

By default, RabbitMQ is set to use its root directory in the Booktype instance's settings/base.py file, indicated by the slash after the port number 5672:

BROKER_URL = 'amqp://guest:guest@localhost:5672/'

After you create a new RabbitMQ virtual host instance2 the configuration in settings/base.py for Booktype's second instance might be:

BROKER_URL = 'amqp://guest:guest@localhost:5672/instance2'

The guest account with a password of guest can only be used on the localhost, for security reasons. To create a new password-protected account for RabbitMQ to use instead of guest, see http://www.rabbitmq.com/access-control.html

Supervisor

Each instance must have it's own file in /etc/supervisor/conf.d/ with a unique name for the program being supervised, such as [program:celeryd-instance2] for the second instance. You should also update the paths for command, stderr_logfile and stdout_logfile to point to the new instance:

[program:celeryd-instance2]
command=/var/www/booktype/instance2/manage_dev.py celery worker --concurrency=10 -l info
autostart=true
autorestart=true
startretries=3
stderr_logfile=/var/www/booktype/instance2/logs/booktype-celery.error.log
stdout_logfile=/var/www/booktype/instance2/logs/booktype-celery.output.log
user=www-data

Apache

Copy the Apache2 configuration from each Booktype instance to the Apache configuration directory /etc/apache2/sites-available/ under unique names, such as:

/etc/apache2/sites-available/booktype-instance2.conf

for the second instance, editing the ServerName and SetEnv HTTP_HOST values for each file.

<VirtualHost *:80>

     ServerName booktype2.example.com
     SetEnv HTTP_HOST "booktype2.example.com"
ServerAdmin admin@example.com

You will need to ensure that the new domain names you have chosen are appropriately configured in DNS. Finally, enable each instance with the a2ensite command and restart the Apache server.

The path to use for static image, CSS and JavaScript files for the Booktype interface depends on whether you wish all instances to have the same appearance.

SSL/TLS support

If you wish to serve Booktype over https:// from Ubuntu 14.04 LTS (trusty), there are some extra installation requirements due to the version of Python being less than 2.7.9. During the installation of dependencies, you should also install the packages:

apt install build-essential python-dev libffi-dev libssl-dev

In the active Python virtual environment, install the packages:

pip install pyopenssl ndg-httpsclient pyasn1

These extra steps should not be necessary on Debian stable and other platforms which have Python 2.7.9 or later.

There has been error in communication with Booktype server. Not sure right now where is the problem.

You should refresh this page.