Install guide

computercolin edited this page Apr 26, 2012 · 3 revisions

NB Architecture

NB is packaged as a Django project and is designed for use with Postgres and Apache. In a simple single-server setup, Apache handles requests, serving static content directly from disk and sending all other requests to the NB django application over mod_wsgi. Other web servers may be substituted for Apache -- we only provide documentation for Apache installations.

Installing NB, you will configure the following services:

  • Apache
  • Postgres
  • Nb Application Settings

NB Directory Structure

NB Application Files

  • Static Content (JS, icons, etc)
  • Django Application Files

Media Files

  • Uploaded PDFs
  • Image cache (converted pngs) The typical installation places NB application files in the home directory of the Apache/Django user (www-data on Ubuntu/Debian) and the media files in /var/local/nb

Warning: config files, makefile in transition

The following instructions require the makefile and config file naming from branch colin_play. This will be merged into the Master branch, shortly, making this notice irrelevant.

1. Obtain NB

Download a packaged archive (link)

cd ~
tar xvzf nb-lksjfdsd.tar.gz
export NB_INSTALL_DIR=`pwd`
or pull from revision control (requires the Git client)
cd ~
git clone http://todo..

You may install NB in a user home directory (perhaps of server user such as www-data) or a more general location such as /opt . Take a moment and move NB to its final install location. The install scripts assume NB is located in the directory from which it will be run.

Ready? For convenience, store you location (not required).

cd nb
export NB_INSTALL_DIR=`pwd`

2. Dependencies

On a typical Debian-like (Ubuntu etc...) distribution, NB requires the following packages: (packages in square brackets are optional)

  • python (>= 2.6)
  • python-psycopg2
  • postgresql (>= 8.4)
  • imagemagick
  • [pdfedit]
  • postgresql-plpython-8.4
  • python-pypdf
  • context (for rich, i.e. annotated pdf generation)
  • apache (>= 2)
  • apache mod-wsgi

On Ubuntu/Debian systems, you can check whether you have these installed by running: make check_prereqs

On Ubuntu/Debian systems, install all prereqs by running: make install_prereqs

3. Obtain Django

Additionally, NB requires:

  • django (>=2.3)

Install Django from official release

At the time of this writing, Ubuntu and Debian do not have Django 1.3. If your linux variant has a Django 1.3 package, you are welcome to install it through your package manager, otherwise do the following to install the latest official release (derived from

cd ~
wget --no-check-certificate
tar xvzf Django-1.3.1.tar.gz
cd Django-1.3.1
sudo python install

You can check that Django is properly installed by running

python -c "import django" 

if you do not receive an error ("Traceback ..."), you are good to go.

4. NB Database

User-readable database schema for NB can be found in conf/nb_skeleton.sql, and a database "dump" that can be used to create an empty NB database is in conf/nb_skeleton.dump . The "dump" assumes the owner of the DB is 'nbadmin', so we must create that user now.

4.1 Create NB database and user

On Ubuntu/Debian user postgres has create user, create database privileges. Become the postgres user:

sudo su postgres

Create database user nbadmin:

createuser nbadmin -P #important to setup as superuser since only superusers can create a language (used for plpythonu)

Create the notabene database

createdb -U nbadmin -h localhost notabene

You may also have to allow remote connections add the following line to /etc/postgresql/8.4/main/pg_hba.conf

host notabene nbadmin password

if you make a mistake:

dropdb  -U nbadmin -h localhost notabene
createdb -U nbadmin -h localhost notabene

You probably don't want to stay user postgres; log out:


4.2 Build empty database

Tell Django to build your database.

python syncdb

Note: the syncdb command will not alter existing tables -- existing data should be safe. Django will ask you if you would like to create a superuser. Go ahead, create one.

5. NB Application Configuration

Return to the NB installation directory and give NB your database credentials.


Configure general NB settings


Finally, based on your settings, create media (pdf, png) storage directories:

sudo make create_dirs

Compile the javascript

make api
make apidev

6. Apache and Crontab Configuration

Now that NB is configured, lets configure your system. Apache and Crontab need to know about NB.

Create apache and cron config file:

make apache_config

You may need to customize the Apache VirtualHost configuration NB generates. If you do not intend to run other web-services on your server, you may remove the NameVirtualHost line.

TODO: Section about different Apache configurations.

Make Apache aware of NB. For Debian/Ubuntu:

sudo cp conf/nb_apache /etc/apache2/sites-available
cd /etc/apache2/sites-enabled
sudo ln -s ../sites-available/nb_apache .

TODO: If your server will not run any other web-services, disable the default Apache site. On Ubuntu/Debian

sudo rm /etc/apache2/sites-enabled/000-default

Create a cron settings for NB:

make cron_config

Make will create conf/nb_crontab and print instructions on importing the settings into cron. Do as instructed.

7. Start Your Engines

Restart Apache. On Ubuntu/Debian

sudo /etc/init.d/apache2 restart

And point your browser at your server (gently).

TODO: integrate into this guide

Test SMTP Settings

shell> cd NB_DIRECTORY/apps
shell> python shell
python>>> from django.core.mail import EmailMessage
python>>> email = EmailMessage('Subject', 'Body', to=[''])
python>>> email.send()


Debug NB through Django tools. For example, pull data from Django models by running the following

shell> cd NB_DIRECTORY/apps
shell> python shell
python>>> from base import models as m;
python>>> print m.User.objects.all()
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.