Join GitHub today
GitHub is home to over 31 million developers working together to host and review code, manage projects, and build software together.Sign up
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:
- Nb Application Settings
NB Directory Structure
NB Application Files
- Static Content (JS, icons, etc)
- Django Application 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`
On a typical Debian-like (Ubuntu etc...) distribution, NB requires the following packages: (packages in square brackets are optional)
- python (>= 2.6)
- postgresql (>= 8.4)
- 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:
On Ubuntu/Debian systems, install all prereqs by running:
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 https://www.djangoproject.com/download/).
cd ~ wget http://www.djangoproject.com/download/1.3.1/tarball --no-check-certificate tar xvzf Django-1.3.1.tar.gz cd Django-1.3.1 sudo python setup.py 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
host notabene nbadmin 127.0.0.1/0 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.
cd $NB_INSTALL_DIR/apps python manage.py 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.
cd $NB_INSTALL_DIR/apps cp settings_credentials.py.skel settings_credentials.py nano settings_credentials.py
Configure general NB settings
cd $NB_INSTALL_DIR/apps cp settings.py.skel settings.py nano settings.py
Finally, based on your settings, create media (pdf, png) storage directories:
sudo make create_dirs
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:
cd $NB_INSTALL_DIR 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:
cd $NB_INSTALL_DIR 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 manage.py shell python>>> from django.core.mail import EmailMessage python>>> email = EmailMessage('Subject', 'Body', to=['firstname.lastname@example.org']) 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 manage.py shell python>>> from base import models as m; python>>> print m.User.objects.all()