Sourcefabric Manuals

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

Booktype 2.3 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 ( It has been tested on Debian 8 (jessie) and Debian 9 (stretch).

Installing dependencies

You will probably need to install some of Booktype's Python dependencies using 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 ( and the tidy syntax checker. On Debian or Ubuntu, you can do this in a terminal with the apt-get command:

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

Redis server 2.8 or later is recommended, which is available in Debian 9 (stretch), 8 (jessie) and Ubuntu 14.04 LTS (trusty), but not in Debian 7 (wheezy) which reached end of life in May 2018.

Installing a web server

The standard 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 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 2.0 from the git repository to the /usr/local/src/booktype/ directory:

cd /usr/local/
sudo mkdir src/booktype/
sudo git clone --branch master --depth 1 src/booktype/

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

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 file. + Creating file.   [OK]
+ Creating file. + Creating file.   [OK]
+ Creating file. + Creating file.   [OK]
+ Creating instance1_site/ file.   [OK]
+ Creating instance1_site/settings/ file.   [OK]
+ Creating instance1_site/urls/ file.   [OK]
+ Creating instance1_site/settings/ file.   [OK]
+ Creating instance1_site/settings/ file.   [OK]
+ Creating instance1_site/settings/ file.   [OK]
+ Creating instance1_site/settings/ file.   [OK]
+ Creating instance1_site/settings/ 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 file.   [OK]
+ Creating instance1_site/urls/ file.   [OK]
+ Creating instance1_site/urls/ file.   [OK]
+ Creating instance1_site/urls/ 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 file for dev profile           -  Manage file for stage profile            -  Manage file for prod profile
   pytest.ini                -  Global py.test configuration               -  Py.test configuration with fixtures and db pre settings              -  Pandoc convertion script from epub to docx              -  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 file for Apache           -  WSGI file for Apache            -  WSGI file for Apache

     settings/               -  Settings configurations               -  Base configuration                -  Development configuration              -  Stage configuration               -  Production configuration               -  Testing configuration

     urls/                   -  URL routers                -  For Development profile              -  For Production profile               -  For Production profile

For further instructions read INSTALL file.

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

cd /var/www/booktype/instance1/
nano instance1_site/settings/

There are several sections of this file which need to be edited to suit your installation. First, set the name and email address of the system administrator:

    # ('Your Name', ''),

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


Enter the site name of your Booktype server:

BOOKTYPE_SITE_NAME = 'Booktype site'

Enter email and outgoing mail server details:


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/mpdf60/')

Enter the name of the default publisher, if none is specified:


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 below). 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_HOST = os.environ.get('BOOKTYPE_REDIS_HOST', 'localhost')
REDIS_PORT = os.environ.get('BOOKTYPE_REDIS_PORT', 6379)
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'


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

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

nano instance1_site/settings/

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


BOOKTYPE_URL = os.environ.get('BOOKTYPE_URL', '')

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

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

Press Ctrl+O to save the file and Ctrl+X to quit the nano editor. When you are ready to move to the production database, you can add the database details to the production settings file, such as:


and use the booktype_prod.env environment variables instead.

5. Load the environment variables for the dev profile:

. ./booktype_dev.env

6. Migrate the database:

./ migrate

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

7. Create a superuser account for the Booktype administrator:

./ createsuperuser

Enter the required information as prompted:

Username (leave blank to use 'www-data'): admin
E-mail address:
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.

./ collectstatic

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

./ update_permissions
./ update_default_roles

Installation is now complete. Return to your normal user prompt in the terminal with the command:


so that you are no longer entering commands as the www-data user. 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 while testing the instance:

     WSGIScriptAlias / /var/www/booktype/instance1/instance1_site/

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      SetEnv HTTP_HOST ""

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

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

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 in the example above.

Subdirectory installation

It is possible to serve a Booktype instance under a URL such as or similar. You would have to set the THIS_BOOKTYPE_SERVER value in the, or 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:

command=/var/www/booktype/instance1/ celery worker --concurrency=10 -l info

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 ( for publishing ebooks in the .mobi format ( 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.


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):


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/ 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/ 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


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:

command=/var/www/booktype/instance2/ celery worker --concurrency=10 -l info


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


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

<VirtualHost *:80>

     SetEnv HTTP_HOST ""

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.