1. Install system components

BtB should work on unix systems; it has been tested on Linux and OS X.

System requirements:

System-specific instructions:

  • Ubuntu:

    sudo apt-get install git mercurial poppler-utils pdftk imagemagick rubber rabbitmq-server python-dev postgresql-server-dev-all rubygems nodejs npm texlive-fonts-extra texlive-fonts-recommended texlive-font-utils texlive-generic-recommended texlive-latex-extra texlive-latex-recommended ttf-sil-gentium
    cd /tmp
    curl -L | tar xjv > wkhtmltopdf
    sudo mv wkhtmltopdf /usr/local/bin
    sudo gem install compass
    sudo npm install -g coffee-script
  • OS X (using MacPorts – install that first):

    sudo port install \
        python26 \
        py26-virtualenv \
        git-core \
        mercurial \
        sqlite3 py26-sqlite \
        poppler \
        pdftk \
        rubber \
        imagemagick \
    # create symlinks to be compatible with other systems
    sudo ln -s virtualenv-2.6 /opt/local/bin/virtualenv
    sudo ln -sf easy_install-2.6 /opt/local/bin/easy_install
    cd /tmp
    curl -O
    tar jxvf wkhtmltopdf-OSX-0.10.0_rc2-static.tar.bz2
    sudo cp wkhtmltopdf /usr/local/bin
    #XXX: need instructions for installing compass (
    #XXX: need instructions for installing coffeescript (
    #XXX: need instructions for installing latex
    #XXX: need instructions for installing Gentium font (

2. Set up project directory

Set up a directory to put project files/etc in:

INSTALL_DIR=~/projects/ # or whatever you like...
mkdir -p $INSTALL_DIR

The rest of this documentation assumes there is a INSTALL_DIR environment variable.

3. Clone the repository

Download the code:

git clone btb

4. Set up virtualenv and install python library dependencies

Set up a virtualenv into which to install python dependencies. Python dependencies are listed in the file scanblog/requirements.txt:

VENV_DIR=$INSTALL_DIR/btb/venv # or whatever you like
virtualenv --no-site-packages $VENV_DIR
source $VENV_DIR/bin/activate
easy_install pip
pip install -r $INSTALL_DIR/btb/scanblog/requirements.txt

5. Configure BtB

Copy to, then edit it to reflect your settings:

cd $INSTALL_DIR/btb/scanblog

Be sure to change:

  • ADMINS and SERVER_EMAIL to a suitable name/email
  • TEXT_IMAGE_FONT to the Gentium font path, e.g., /usr/share/fonts/gentium/GenR102.TTF
  • Set the path to external executables as appropriate: NICE_CMD, PDFTK_CMD, WKHTMLTOPDF_CMD, RUBBER_PIPE_CMD, PDFINFO_CMD, PDFTOTEXT_CMD, CONVERT_CMD
  • Change SECRET_KEY to something long and random (it’s used for hashing authentication cookies).
  • If it’s a production site, you’ll want to use a database other than sqlite, as it doesn’t support concurrent writes. Set this in the DATABASES configuration. (sqlite works fine for development)

Due to this bug, as a work around to ensure that images and fonts are served properly in development mode, add symlinks to the compiled asset directory:

mkdirs -p $INSTALL_DIR/btb/scanblog/site_static/CACHE
cd $INSTALL_DIR/btb/scanblog/site_static/CACHE
ln -s ../../static/img .
ln -s ../../static/fonts .

6. Set up database

Load the initial database, and run initial migrations:

source $VENV_DIR/bin/activate
cd $INSTALL_DIR/btb/scanblog

python syncdb --noinput
python migrate
python loaddata btb/fixtures/initial_data.json

# Create superuser
python shell  <<-EOF
from sh import *
u = User.objects.create(username='admin', is_superuser=True, is_staff=True)

After running that script, there will be a single admin user with username “admin” and password “admin”. This can be changed in the Django admin site by navigating to http://localhost:8000/admin/.

7. Run the dev server!

Django ships with a built-in devserver. You can run this directly:

cd $INSTALL_DIR/btb/scanblog
source $VENV_DIR/bin/activate
python runserver

8. Set the site name in admin

In order to download documents as PDF’s, you’ll need to set the ‘Site’ object so that it isn’t the default (unless resolves as you :)).

To do this, navigate to the admin site: http://localhost:8000/admin/. Click Sites, and change the default site to a URL that will resolve (probably localhost:8000).