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 9 (stretch) and Ubuntu 18.04 LTS (bionic) using sudo for root access.
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 gcc git-core pandoc python-dev python-pip libjpeg-dev libpq-dev libxml2-dev libxslt1-dev rabbitmq-server redis-server tidy zip
The rabbitmq-server package might fail to start if your server's hostname is not resolvable.
A web server is 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
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/booktype/Booktype.git --branch master 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/or a production install with PostgreSQL. You may need to upgrade your version of setuptools first, if using it:
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
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
sudo chown www-data:www-data /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'),
)
In some configurations, you might need to set explicitly the servers allowed to make exports:
EXPORT_ALLOWED_HOSTS = ['127.0.0.1', 'booktype.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.
./manage_dev.py collectstatic
If you are using the production profile, you should also use the 'compress' option:
./manage_prod.py collectstatic
./manage_prod.py compress
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.
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.
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.
The celery task queue is used by Booktype when sending outputs to the various different file converters available. For development purposes, celery workers can be run from the command line so that you can watch messages being passed to the converters each time someone clicks the Export your book button on the Publish tab.
If you have a permanent installation of Booktype, you will need a process monitor to keep the celery workers running after server reboots. 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. Sample configurations for production and staging instances are created automatically in the conf directory of your instance, which you can copy to the configuration directory for supervisor as follows:
sudo cp /var/www/booktype/instance1/conf/supervisor_prod.conf /etc/supervisor/conf.d/booktype-instance1.conf
sudo nano /etc/supervisor/conf.d/booktype-instance1.conf
For the first Booktype instance in /var/www/booktype/instance1 with twenty workers, the contents of the file booktype-instance1.conf could be similar to:
[program:instance1_site-celery-worker]
directory=/var/www/booktype/instance1
command=/usr/bin/python -m celery worker --app=instance1_site --concurrency=20 -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
stopwaitsecs=60
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.
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
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_DB = 1
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
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:instance2_site-celery-worker] for the second instance. You should also update the paths for directory, command, stderr_logfile and stdout_logfile to point to the new instance:
[program:instance2_site-celery-worker] directory=/var/www/booktype/instance2 command=/usr/bin/python -m celery worker --app=instance2_site --concurrency=20 -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 stopwaitsecs=60
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.
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.