.. highlight:: bash Installation ============ 1. Install system components ---------------------------- BtB should work on unix systems; it has been tested on Linux and OS X. System requirements: * Python 2.6 or 2.7 (Python 3 not supported), and development headers * `poppler-utils `_ * `pdftk `_ * `imagemagick `_ * `wkhtmltopdf `_ >= 0.10 * `rubber `_ * `rabbitmq-server `_ * `git `_ (for obtaining the codebase) * `mercurial `_ (for installing python dependencies) * `python-virtualenv `_ * `compass `_ (for stylesheet compilation) * `coffee script `_ (for script compilation) 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 https://wkhtmltopdf.googlecode.com/files/wkhtmltopdf-0.11.0_rc1-static-i386.tar.bz2 | 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 \ rabbitmq-server # 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 https://wkhtmltopdf.googlecode.com/files/wkhtmltopdf-OSX-0.10.0_rc2-static.tar.bz2 tar jxvf wkhtmltopdf-OSX-0.10.0_rc2-static.tar.bz2 sudo cp wkhtmltopdf /usr/local/bin #XXX: need instructions for installing compass (http://compass-style.org) #XXX: need instructions for installing coffeescript (http://coffeescript.org) #XXX: need instructions for installing latex #XXX: need instructions for installing Gentium font (http://scripts.sil.org/cms/scripts/render_download.php?&format=file&media_id=Gentium_102_W&filename=Gentium_102_W.zip) 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:: cd $INSTALL_DIR git clone http://github.com/yourcelf/btb.git 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 ``example.settings.py`` to ``settings.py``, then edit it to reflect your settings:: cd $INSTALL_DIR/btb/scanblog cp example.settings.py settings.py 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 manage.py syncdb --noinput python manage.py migrate python manage.py loaddata btb/fixtures/initial_data.json # Create superuser python manage.py shell <<-EOF from sh import * u = User.objects.create(username='admin', is_superuser=True, is_staff=True) u.set_password('admin') u.save() exit() EOF 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 manage.py 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 ``example.com`` 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``).