Sourcefabric Manuals

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

Booktype 2.2 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/sourcefabric/Booktype/). It has been tested on Debian 7 (wheezy) and Debian 8 (jessie).

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/) and the tidy syntax checker. On Debian or Ubuntu, you can do this in a terminal with the apt-get command:

sudo apt-get 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 8 (jessie) and Ubuntu 14.04 LTS (trusty) but not currently available in Debian 7 (wheezy). If your Debian server runs wheezy, make sure you have the wheezy-backports apt repository set up. There should be a line similar to:

deb http://ftp.debian.org/debian wheezy-backports main

in your /etc/apt/sources.list file, or a file with the .list extension in the /etc/apt/sources.list.d/ directory. If you need to add a line for wheezy-backports, you can find a list of mirror sites at https://www.debian.org/mirror/list

To install Redis server 2.8 from wheezy-backports, enter the commands:

sudo apt-get update
sudo apt-get -t wheezy-backports install redis-server

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 https://docs.djangoproject.com/en/1.7/howto/deployment/wsgi/modwsgi/ for more details.

You can install the Apache web server (the Prefork MPM version is recommended) and the WSGI module with the command:

sudo apt-get install apache2-mpm-prefork 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 https://github.com/sourcefabric/Booktype.git --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 the dev profile and a postgresql database in the /var/www/booktype/instance1 directory:

sudo su -s /bin/sh www-data
cd /usr/local/src/booktype/scripts/
./createbooktype -p dev --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 South 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.env file.   [OK]
+ Creating manage.py file. + Creating manage.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/prod.py file.   [OK]
+ Creating instance1_site/urls/dev.py file.   [OK]
+ Creating instance1_site/urls/prod.py file.   [OK]
+ Creating booktype.wsgi file.   [OK]
+ Creating wsgi.apache file.   [OK]
+ Creating gunicorn.nginx file.   [OK]
+ Creating factcgi.nginx file.   [OK]

Check [/var/www/booktype/instance1] directory for created files:
   booktype.env        -  Environment variables
   manage.py           -  Manage file

   conf/                 -  Configuration files
     wsgi.apache         -  Apache config file
     gunicorn.nginx      -  Nginx config file
     fastcgi.nginx       -  Nginx config file

   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.py             -  WSGI file for Apache

     settings/           -  Settings configurations
       base.py           -  Base configuration
       dev.py            -  Development configuration
       prod.py           -  Production configuration

     urls/               -  URL routers
       dev.py            -  For Development 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. 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 = 'localhost' EMAIL_PORT = 25

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

DEFAULT_PUBLISHER = "Unknown"

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 STUFF
REDIS_HOST = 'localhost'
REDIS_PORT = 6379
REDIS_DB = 0
REDIS_PASSWORD = 'myredispassword'

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

TIME_ZONE = 'Europe/London'

LANGUAGE_CODE = 'en-gb'

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 = 'booktype.example.com'
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.

Set the path to the mPDF renderer, your PHP installation and Booktype's mPDF script:

MPDF_DIR = '/var/www/mpdf60/'
PHP_PATH = '/usr/bin/php'
MPDF_SCRIPT = '/usr/local/src/booktype/scripts/booktype2mpdf.php'

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:

instance1_site/settings/prod.py

and update the DJANGO_SETTINGS_MODULE environment variable in the file booktype.env from dev to prod:

 export DJANGO_SETTINGS_MODULE=instance1_site.settings.prod

5. Load the environment variables:

. ./booktype.env

6. Migrate the database:

./manage.py migrate

The server might respond with migrations such as:

Running migrations for djcelery:
 - Migrating forwards to 0004_v30_changes.
 > djcelery:0001_initial
 > djcelery:0002_v25_changes
 > djcelery:0003_v26_changes
 > djcelery:0004_v30_changes
 - Loading initial data for djcelery.
Installed 0 object(s) from 0 fixture(s)

7. Create a superuser account for the Booktype administrator:

./manage.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. If you are using the production profile, you should also compress files:

./manage.py collectstatic
./manage.py compress

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

./manage.py update_permissions
./manage.py update_default_roles

Installation is now complete. You can now start a test server for the instance, or skip to Apache configuration for production use.

Testing a Booktype instance

In the instance directory such as /var/www/booktype/instance1/ the www-data user can start a test server with the dev.py development profile on a port which is not in use, such as 8005. Enter the command:

./manage.py runserver 0.0.0.0:8005

Leaving this terminal running, open another terminal in the same directory, switch to the www-data user, and run the celery workers with the command:

cd /var/www/booktype/instance1/
sudo su -s /bin/sh www-data ./manage.py celery worker --concurrency=10 -l debug

Open your web browser on the specified port at the IP address of the server, for example http://127.0.0.1:8005/ for the localhost.

Alternatively, if you are running Booktype on a virtual machine such as VirtualBox, then you should use the IP address of the virtual GNU/Linux server. You can use bridged mode in VirtualBox network setup to obtain a real address on the local network for the virtual machine.

If all is well, you should see the Booktype dashboard in your browser. The gravatar associated with the superuser email address, if you have one, will be displayed in the People box.

Booktype test server

You can sign in using the superuser account details that you created in the installation step above.

Once you are confident that Booktype is installed correctly, you can press Ctrl+C in the terminal to shut down the test instance. Then return to your normal user prompt in the terminal with the command:

exit

so that you are no longer entering commands as the www-data user.

Apache configuration

1. If you are using the production profile, update DJANGO_SETTINGS_MODULE in /var/www/booktype/instance1/instance1_site/wsgi.py as follows:

os.environ["DJANGO_SETTINGS_MODULE"] = "instance1_site.settings.prod"

2. Copy the wsgi.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.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

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>

     # CHANGE THIS
     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:

    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 without mod_access_compat installed:

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

You may need to set the paths for static image, CSS and JavaScript files used in the interface, to point to the paths where you installed Booktype. 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. Restart the Apache webserver with the command:

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 persistent 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-get 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.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-get install calibre

If you are running Debian 7 (wheezy) on your server, you might experience .mobi export failure, due to the css_to_xpath function from LXML moving into a separate python-cssselect package. The solution is to install a later version of Calibre from the wheezy-backports repository (see https://backports.debian.org/Instructions/) with the command:

apt-get -t wheezy-backports 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.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>

     # CHANGE THIS
     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, 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-get 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.