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, grunt-cli 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 .

One little pitfall: make sure you have the libmagic file type identification library installed in your system (if not install it - on a mac e.g. with brew). This one is needed for the messytables dependency.

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 ..
$ bower 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

Initialise the database:

$ spendb db migrate

Configuration

Having done all the stuff above, 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'

For the file upload to work you have to add your Amazon S3 bucket credentials (it is generally advisable to create both a new bucket and a new user for this, and not using the one your multi-billion-dollar company relies on):

AWS_KEY_ID = 'YOUR-AMAZON-S3-KEY-ID'
AWS_SECRET = 'YOUR-AMAZON-S3-SECRET'
AWS_DATA_BUCKET = 'NAME-OF-YOUR-BUCKET'

Generally: it doesn't hurt, if you fill in useful values for the other configuration options as well!

Running the application

Start the Flask development server with:

$ 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. Run the RabbitMQ server with:

$ sudo rabbitmq-server

And then lift up the Celery task queue with:

$ 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.

Connect the spendb installation with your local spendb.ui repository

Central file for serving the UI when running the spendb server is the spendb/templates/layout.html HTML template, bound to the / main entrypoint URL of the application in spendb/views/home.py. The template includes the spendb.ui javascript and CSS files.

Paths for these inclusions are set with the following two settings in spendb/default_settings.py:

ASSETS_PATH_PROD = 'https://dfmbkaoi4kurm.cloudfront.net/libs/spendb.ui/latest/build'
ASSETS_PATH_DEBUG = '/static/spendb.ui/build'

If you want to connect to your local spendb.ui repository, start a server in the build directory of the spendb.ui repository:

$ python -m SimpleHTTPServer 5005

Then add the server path in your local settings.py file:

ASSETS_PATH_PROD = 'http://127.0.0.1:5005'

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';

Compiling translation files

You can recompile the translation files with:

$ python setup.py compile_catalog