Installation & Configuration¶

Downloading¶

Pip Install Directions

v1.0.0 should be hosted on PyPi so installing is as easy as:

$ pip install acornaccounting

See The Hitchhiker’s Guide to Packaging for information on how to get that set up.

Git Clone Directions

Developers will want to clone the current source code repository:

$ git clone git@aphrodite.acorn:~/Acorn-Accounting.git/

The current public release is located on the master branch while new development occurs on the develop branch.

See Development Standards and Contributing for more information.

Install Prerequisites¶

You should install python 2 and pip via your package manager.

On Arch Linux:

$ sudo pacman -S python2 python2-pip

On Slackware:

$ sudo /usr/sbin/slackpkg install python
$ wget https://raw.github.com/pypa/pip/master/contrib/get-pip.py
$ sudo python get-pip.py

On Debian/Ubuntu:

$ sudo apt-get install python-pip

Optionally you may want to install virtualenv and virtualenvwrapper to manage and isolate the python dependencies.

$ sudo pip install virtualenv virtualenvwrapper

Make sure to do the initial setup for virtualenv:

$ export WORKON_HOME=~/.virtualenv/
$ mkdir -p $WORKON_HOME
$ source virtualenvwrapper.sh

Then you may create an environment for AcornAccounting:

$ mkvirtualenv AcornAccounting

You may then install dependencies into this virtual environment. There are multiple tiers of dependencies:

base - minimum requirements needed to run the application
test - requirements necessary for running the test suite
local - development prerequisites such as the debug toolbar and documentation builders
production - all packages required for real world usage

A set of dependencies may be installed via pip:

$ workon AcornAccounting
$ pip install -r requirements/develop.txt

Configuration¶

Some settings are set through environmental variables instead of files. These include settings with sensitive information, and allows us to keep the information out of version control.

You may set these variables directly in the terminal or add them to your virtualenv’s activate script:

$ DB_USER='prikhi' DB_NAME='DjangoAccounting' ./manage.py runserver
$ export DB_NAME='DjangoAccounting'
$ ./manage.py runserver

The required environmental variables are DJANGO_SECRET_KEY, DB_NAME and DB_USER.

Deployment¶

It is recommended to use uWSGI for serving the dynamic pages and either Apache or Nginx for serving your static files.

Create and Initialize the Database¶

You’ll need a new Database and User, if you use PostgreSQL you may run:

su - postgres
createuser -DERPS accounting
createdb accounting -O accounting

Set configuration values for the account you just created:

export DJANGO_SETTINGS_MODULE=accounting.settings.production
export DB_USER=accounting
export DB_PASSWORD=<accounting user password>
export DB_NAME=accounting

Then create the initial schema and migrate any database changes:

cd acornaccounting
python manage.py syncdb
python manage.py migrate

Collect Static Files¶

Next collect all the static files into the directory you will serve them out of:

python manage.py collectstatic

Configure uWSGI¶

You can use the following ini file to setup the uWSGI daemon:

[uwsgi]
uid = <your accounting user>
gid = %(uid)
chdir = <acornaccounting project root>

plugin = python
pythonpath = %(chdir)
virtualenv = </path/to/virtualenv/>
module = django.core.handlers.wsgi:WSGIHandler()

socket = 127.0.0.1:3031
master = true
workers = 10
max-requests = 5000
vacuum = True

daemonize = /var/log/accounting/uwsgi.log
pidfile = /var/run/accounting.pid
touch-reload = /tmp/accounting.touch

env = DJANGO_SETTINGS_MODULE=accounting.settings.production
env = DB_NAME=<database name
env = DB_USER=<database user>
env = DB_PASSWORD=<database password>
env = DB_HOST=
env = DB_PORT=
env = DJANGO_SECRET_KEY=<your unique secret key>
env = CACHE_LOCATION=127.0.0.1:11211

Make sure to review this and replace the necessary variables.

Note

If you do not have a secure, unique secret key, you may generate one by running the following in the Python interpreter:

import random
print(''.join(
    [random.SystemRandom().choice(
        'abcdefghijklmnopqrstuvwxyz0123456789!@#$%^&*(-_=+)')
     for i in range(50)])
)

Depending on your OS, you may need to put this file in /etc/uwsgi/apps-available then link it to /etc/uwsgi/apps-enabled/. Or you may need to write an rc.d or init.d startup script:

#!/bin/bash
#
# Start/Stop/Restart the Accounting uWSGI server
#
# To make the server start at boot make this file executable:
#
#       chmod 755 /etc/rc.d/rc.accounting

INIFILE=/etc/uwsgi/accounting.ini
PIDFILE=/var/run/accounting.pid

case "$1" in
    'start')
        echo "Starting the Accounting uWSGI Process."
        uwsgi -i $INIFILE
        ;;
    'stop')
        echo "Stopping the Accounting uWSGI Process."
        uwsgi --stop $PIDFILE
        rm $PIDFILE
        ;;
    'restart')
        echo "Restarting the Accounting uWSGI Process."
        if [ -f $PIDFILE ]; then
            uwsgi --reload $PIDFILE
        else
            echo "Error: No Accounting uWSGI Process Found."
        fi
        ;;
    'status')
        if [ -f $PIDFILE ] && [ "$(ps -o comm= "$(cat $PIDFILE)")" = uwsgi ]; then
            echo "Accounting uWSGI Process is running."
        else
            echo "Accounting uWSGI Process is not running."
        fi
        ;;
    *)
        echo "Usage: /etc/rc.d/rc.accounting {start|stop|restart|status}"
        exit 1
        ;;
esac

exit 0

Apache VirtualHost¶

The Virtual Host should redirect every request, except those to /static, to the uWSGI handler:

<VirtualHost *:80>
    ServerName accounting.yourdomain.com
    DocumentRoot "/srv/accounting/"
    Alias /static /srv/accounting/static/
    <Directory "/srv/accounting/">
        Options Indexes FollowSymLinks MultiViews
        AllowOverride None
        Require all granted
    </Directory>
    <Location />
        Options FollowSymLinks Indexes
        SetHandler uwsgi-handler
        uWSGISocket 127.0.0.1:3031
    </Location>
    <Location /static>
        SetHandler none
    </Location>
    ErrorLog "/var/log/httpd/accounting-error_log"
    CustomLog "/var/log/httpd/accounting-access_log" common
</VirtualHost>

Note that in the above setup, /srv/accounting/ is linked to the Django project’s root directory acornaccounting.

1-Step Deployment¶

1-step deploy script and indepth instuctions, with example apache and uwsgi configs.

Look into fabric for automated deployment. Deploying Django with Fabric

Ideally we would be able to run something like fab deploy_initial and fab deploy.

We can use fab templates, putting samples/templates in the /conf/ directory.

v1.0.0 should include a 1-step build/deployment file.

Building the Documentation¶

pip may be used to install most prerequisites required:

$ pip install -r requirements/local.txt

Java is optional, but required to create the plantUML images. You can install it via your package manager.

On Arch Linux:

$ sudo pacman -S jre7-openjdk

On Debian:

$ sudo apt-get install default-jdk

On Slackware you must manually download the source from Oracle, available here. You may then use the slackbuild at http://slackbuilds.org/repository/14.1/development/jdk/ to install the package:

$ wget http://slackbuilds.org/slackbuilds/14.0/development/jdk.tar.gz
$ tar xfz jdk.tar.gz
$ cd jdk
$ mv ~/jdk-7*-linux-*.tar.gz .
$ ./jdk.SlackBuild
$ sudo installpkg /tmp/jdk-7u45-x86_64-1_SBo.tgz
# Add java to your $PATH:
$ sudo ln -s /usr/lib64/java/jre/bin/java /usr/bin/java

You can now build the full documentation in HTML or PDF format:

$ cd docs/
$ make html
$ make latexpdf

The output files will be located in docs/build/html and docs/build/latex.