INSTALL

Installing Booki
----------------

Note : there are three components to the Booki Tool Set. This doc
covers only the Booki (editor/book manager) component and not Espri
(importer) or Objavi (exporter). By default Booki is hardwired to the
FLOSS Manuals install of Objavi and Espri so you still acquire that
functionality. To detach yourself from the FLOSS Manuals mothership
you need to install Espri and Objavi and configure your install of
Booki accordingly.

This document describes how to install the latest stable versions of 
Django, simplejson, and Redis, using python's easy_install.  If you 
have a sufficiently recent distribution (e.g., Debian Squeeze), you 
can just use the distro versions.  In that case, skip the easy_install 
steps and do whatever is appropriate with your package manager.


Booki prerequisites
-------------------

Command examples are for Debian/Ubuntu.

 - Python, minimum 2.5 (http://www.python.org/) and headers

       $ sudo apt-get install python-dev

 - PostgreSQL (recommended) or Sqlite3 (not recommended)
       
       $ sudo apt-get install postgresql
      or 
       $ sudo apt-get install sqlite3

 - Psycopg (must use this adapter with PostgreSQL)

       $ sudo apt-get install python-psycopg2

 - git repository manager (http://git-scm.com/)

       $ sudo apt-get install git-core

 - Python Set Up Tools

       $ sudo apt-get install python-setuptools

 - Django, minimum 1.2 (http://http://www.djangoproject.com/)

       $ sudo easy_install django
       or
       $ sudo apt-get install python-django

 - SimpleJSON

       $ sudo easy_install simplejson

 - Redis (http://redis.io/)

       $ sudo apt-get install redis-server

 - South (http://south.aeracode.org/)

       $ sudo easy_install South

 - lxml (http://codespeak.net/lxml/)

       $ sudo apt-get install libxml2-dev and libxslt-dev
       $ sudo easy_install lxml
      

Installing from the git repository
----------------------------------

This install doc uses sqlite3 (it is recommended to use PostgreSQL) as its the 
easiest to setup so make sure sqlite3 is installed. Do all of the steps as regular 
user or www-data user.

1. Clone Booki

   git clone git://booki-dev.flossmanuals.net/git/booki.git

2. Change dir to 'booki/scripts'

   cd booki/scripts

3. Create booki instance. If you have write permissions, script will create directory /var/www/mybooki/. If you don't
   have write permissions, administrator should create that directory first.
      sudo mkdir /var/www/mybooki/
      sudo chown www-data:www-data /var/www/mybooki/

   ./createbooki --database sqlite /var/www/mybooki/  

4. Change directory

   cd /var/www/mybooki/

5. Edit settings

   vi settings.py

6. Load environment variables

   . ./booki.env

7. Initialize database

   django-admin syncdb

8. Migrate

   django-admin migrate

9. Start redis (If you are using the distro's Redis server, this may
not be necessary or desirable).

   redis-server &

10. Start the whole thing 

   django-admin.py runserver

Then if all is well open your browser and point to something like:
http://127.0.0.1:8000/


How to use Booki with Apache and mod_wsgi
-----------------------------------------

To install Booki with Apache, you need to use WSGI or FCGI/SCGI.  Consult the
Django documentation at
http://docs.djangoproject.com/en/dev/howto/deployment/.

Createbooki script has created booki.wsgi script for the Apache. Use that
file as part of your Apache config.


How to migrate to latest Booki
------------------------------

1. The following should be added to settings.py:

# lulu.com export credentials that override Objavi settings
LULU_USER = None
LULU_PASSWORD = None
LULU_API_KEY = None


How to migrate to Booki 1.2
---------------------------

1. There are new template files. Be aware if you have changed template files.

   reader/book_info.html       (new file)

   reader/book_view.html       (used to be reader/book.html)
   reader/book_chapter.html    (used to be reader/chapter.html)

   reader/draft_book.html      (used to be reader/book.html)
   reader/draft_chapter.html   (used to be reader/chapter.html)

2. There are new named URL patterns.

   book_view         (used to be view_book, does not have book version argument anymore)
   book_chapter      (used to be view_chapter, does not have book version argument anymore)

   book_info         (new)
 
   draft_book        (used to be view_book)
   draft_chapter     (used to be view_chapter)
   draft_attachment

   For instance. If you had in your template:
    
       {% url view_chapter  book.url_title book_version chap.url_title %}

   Now you must use this syntax (notice there is no book version argument):

       {% url book_chapter  book.url_title  chap.url_title %}

3. You must add new default template directory to settings.py file. This is how TEMPLATE_DIR should look like:

   TEMPLATE_DIRS = (
      '%s/templates/' % BOOKI_ROOT,
      '%s/templates/' % os.path.dirname(booki.__file__)
   )

4. Read lib/booki/messaging/README.txt how to install new Messaging app.

   

How to migrate to Booki 1.1
---------------------------

1. Install Booki again with 'createbooki' script

2. Change configuration in new setting.py file (compare it with old configuration)

3. Change attachment path in database. Please change OLD_PATH and NEW_PATH to point to new directories. If you don't do this, attachments will not be accessable.

   $ django-admin shell
   >>> from booki.editor import models
   >>> OLD_PATH = '/Users/aerkalov/Work/git/booki/site_media/static/'
   >>> NEW_PATH = '/Users/aerkalov/Work/git/mybooki/data/books/'
   >>>
   >>> for att in models.Attachment.objects.all():
   ...     print '>> ', att.attachment.name
   ...     name = att.attachment.name.replace(OLD_PATH, NEW_PATH)
   ...     att.attachment.name = name
   ...     att.save()
   >>>
   >>> from django.contrib.auth.models import User
   >>> OLD_PATH = '/Users/aerkalov/Work/git/booki/site_media/static/_profile_images/'
   >>> NEW_PATH = '/Users/aerkalov/Work/git/mybooki/data/profile_images/'
   >>>
   >>> for u in User.objects.all():
   ...     p = u.get_profile()
   ...     print '>>> ', p.image.name
   ...     name = p.image.name.replace(OLD_PATH, NEW_PATH)
   ...     p.image.name = name
   ...     p.save()