Developer installation

Requirements

SpenDB requires the following packages to be installed either locally or on appropriate database/queue servers:

• Python >= 2.7, with pip and virtualenv
• PostgreSQL >= 9.3. A database needs to be set up as UTF-8, and a user account must be able to alter the database schema at run-time.
• RabbitMQ >= 2.6.1 or another processing queue supported by celery. For testing, non-queue processing is supported but not recommended.
• Node.js, NPM and global installations of less, uglifyjs and bower.

On a Debian/Ubuntu system, you can install all required dependencies with a command along the lines of:

$ add-apt-repository -y ppa:chris-lea/node.js && apt-get update
$ apt-get install -y nodejs libpq-dev rabbitmq-server postgresql-9.4 \
    git python2.7 python-pip build-essential python-dev \
    libxml2-dev libxslt1-dev libpq-dev apt-utils ca-certificates \
$ npm install -g bower less uglify-js grunt-cli

Installation through docker

We're experimenting with a docker-based setup mechanism for SpenDB. Since a database server and a queue are required, docker-compose will be used to orchestrate these different services. At the moment, that setup is not well-tested. You can use the existing Dockerfile to generate an image for the core software, though:

$ docker build .

Installation from source

First, check out the source code from the repository, e.g. via git on the command line:

$ git clone https://github.com/spendb/spendb.git
$ cd spendb

We also highly recommend you use a virtualenv_ to isolate the installed dependencies from the rest of your system.

$ virtualenv ./pyenv --distribute

Now activate the environment. Your prompt will be prefixed with the name of the environment.

$ source ./pyenv/bin/activate

Ensure that any in shell you use to complete the installation you have run the preceding command.

Having the virtualenv set up, you can install SpenDB and its dependencies. This should be pretty painless. Just run:

$ pip install -r requirements.txt -e .

Next, download the JavaScript front-end application and install it via bower:

$ git clone http://github.com/spendb/spendb.ui.git
$ cd spendb.ui
$ npm install
$ bower install
$ grunt
$ bower link
$ cd ..
$ grunt link spendb.ui

While coding on the UI, make sure to also run a terminal window to compile assets after changes:

$ grunt watch

To continue the installation, create a database - if you do not have one already - with the PostgreSQL createdb command:

$ createdb -E utf-8 --owner {your-database-user} spendb

Having done that, you can copy configuration templates:

$ cp prod_settings.py settings.py
$ export SPENDB_SETTINGS=`pwd`/settings.py

Ensure that the SPENDB_SETTINGS environment variable is set whenever you work with the application (if you externalize the command via .bashrc or .bash_profile you have to replace pwd with the absolute path version).

Edit the configuration files to make sure you're pointing to a valid database URL is set:

# TCP
SQLALCHEMY_DATABASE_URI = 'postgresql://{user}:{pass}@localhost/spendb'

Set the secret key to something uniquely unique:

SECRET_KEY = 'SOME-VERY-LONG-STRING-WITH-ALL-SORTS-OF-DIFFERENT-CHARACTERS'

Initialise the database:

$ spendb db migrate

Compile the translations:

$ python setup.py compile_catalog

Run the application:

$ spendb runserver

In order to use web-based importing and loading, you will also need to set up the celery-based background daemon. When running this, make sure to have an instance of RabbitMQ installed and running and then execute:

$ celery -A spendb.tasks worker -l info

You can validate the functioning of the communication between the backend and frontend components using the ping action:

$ curl -q http://localhost:5000/__ping__ >/dev/null

This should result in "Pong." being printed to the background daemon's console.

Test the install

Run the tests like this:

$ nosetests 

Create an Admin User

On the web user interface, register as a normal user. Once signed up, go into the database and do (replacing your-name with your login name):

UPDATE "account" SET admin = true WHERE "name" = 'username';