Configuring your system for Bookworm

Bookworm installation requires setting up some servers, and then installing Bookworm itself.

Apache setup

Apache is not required for Bookworm; you can run it locally through a python webserver. But if you want to share interactive charts with others, it is highly recommended. Apache setup is pretty easy: there are any number of sources for configuring your default apache installation to work.

Bookworm requires files in a web directory: for convenience, it's much easier if you name that folder the same as the name of the database. (So maps to the SOTU database). If using the D3 web interface, that should be sufficient to get you started (although the default search may need to be changed); if using the polish highcharts setup, some additional work may be necessary.

MySQL setup

For a small Bookworm, the exact version of the server doesn't matter: for a large one, some features like subquery caching, implemented in mariadb, greatly increases speed.

To install on Ubuntu 14.04, some strange invocations are required: sudo apt-get install mariadb-server-core-10.0 after setting up your repositories.

Bookworm uses a heavily customized my.cnf file for MySQL, though, in order to facilitate the creation of large b-tree indexes. This mostly involves things like allowing obscenely large temporary tables which makes index creation an order of magnitude faster. (Although still quite slow on a large Bookworm). We do not know of any substantial performance hits for this file. (For instance, MySQL is still quite snappy as a wordpress host).

You'll also need to set up mysql so that you can create tables. The best way to test this is to do the following. First, in the shell type mysql. That should log you on. (If you have problems here, you may need to edit your ~/.my.cnf file.) Then in MySQL type:

DROP DATABASE testing123;

If those fail, you don't have appropriate privileges to use MySQL on your server.

After this, you'll need to configure your mysql preferences to allow different levels of access. Typing bookworm config mysql will lead create an interactive prompt to lead you through this process. If you're trying to script creation of Bookworm on a VM or remote server infrastructure, bookworm config --force mysql attempts to guess at a number of sane defaults. This requires that the account running it be able to invoke sudo privileges without a password, which is standard on many VM architectures.

Install other dependencies

A few other tools help Bookworm build. You may learn what they are through build errors: the ones you are least likely to have are, in decreasing order:

  1. GNU parallel

You may also need:

  1. python-devtools
  2. libmysqldev

Install Bookworm

Bookworm is installed as a python module. Clone the core Bookworm module, navigate to the directory, and type

pip install .

If you get errors relating to permissions, you may need to change folders (such as /usr/lib/cgi-bin) to be writeable by your current user. Or you can just use sudo pip install . instead.

Next, you need to set up various mysql permissions. To do this interactively, type

bookworm config mysql

After this, you should be installed.

To test the installation by building a small bookworm of the Federalist Papers, type:

cd tests && python && python

If this fails, you can try posting an issue to the project page.