Installation of planop on a linux server

These instructions assume you have an internet connection available to download the necessary dependencies. The examples assume you downloaded the planop installation file into your home folder. These instructions are based on Ubuntu server 14.04, but should apply more or less to any Debian based distribution.

This document does NOT address standard server configuration like networking, ssh, firewall etc.

1. python

You linux server probably has python installed. Any version higher than 2.5 will do, but NOT version 3, so you should be fine here.

2. setup tools

To install our packages, we need easy_install, which is part of the setuptools package:

sudo apt-get python-setuptools

3. virtualenv

Create a virtual environment using virtualenv. Virtualenv is a tool to build isolated Python environments.

First, install virtualenv:

sudo easy_install virtualenv

In the examples in this document, we assume you will install your virtualenvs in the following folder:

/srv/virtualenvs/

Then, create a virtual environment for your planop install:

cd /srv/virtualenvs/
virtualenv planop --no-site-packages

Now activate your virtual environment:

cd planop
source bin/activate

4. planop

To install planop and its dependencies (make sure your virtualenv is active):

pip install ~/planop-3.2.x.zip

This will install planop and its dependencies.

5. PostgreSQL database

These instructions assume you will use PostgreSQL as your database. Off course you are free to use any of the other databases supported by django:

sudo apt-get gcc build-essential python-dev libpq-dev postgresql python-psycopg2

Create a database user and a database:

sudo su - postgres
createuser -P dbuser
    (no to all questions)
createdb --encoding=UNICODE dbname --owner=dbuser
exit

Remove sameuser from postgres conf for postgres user and make it allow password connections:

edit the file /etc/postgresql/9.3/main/pg_hba.conf
--> local all all password

Restart postgres:

sudo /etc/init.d/postgresql restart

6. Nginx webserver

This block describes the install using an nginx front-end and a gunicorn backend. We will use supervisord to monitor the different services.

Install nginx:

sudo apt-get install nginx

Copy the example nginx config file:

sudo cp /srv/virtualenvs/planop/lib/python2.7/site-packages/planop/configs/nginx.planop.conf /etc/nginx/sites-enabled/

and edit the file to adjust the configuration.

This configuration assumes you are setting up your uploads file in the following location:

/srv/uploads/

and your static files in the folder:

/srv/static/

For this you need to put the following in your local_settings.py file:

UPLOAD_ROOT = '/srv/uploads/'
STATIC_ROOT = '/srv/static/'

Reload nginx config and restart:

sudo /etc/init.d/apache2 reload
sudo /etc/init.d/apache2 restart

Install gunicorn as the backend server (make sure your virtualenv is still activated):

pip install gunicorn

Now we will use supervisor to start and monitor the servers:

sudo apt-get install supervisor

Copy the example supervisor config file:

sudo cp /srv/virtualenvs/planop/lib/python2.7/site-packages/planop/configs/supervisor.planop.conf /etc/supervisor/conf.d/planop.conf

and edit the file to adjust the configuration.

PS: this file assumes you will be using celery (see point 10).

7. Planop configuration

Go to the planop base folder:

cd /srv/virtualenvs/planop/lib/python2.7/site-packages/planop

Create the local configuration file:

copy local_settings.py.template local_settings.py

Now edit the local settings file:

nano local_settings.py

Edit the configuration as needed. You will need to configure your database. The following snippet configures planop to use a PostgreSQL database:

DATABASES = {
    "default": {
        "ENGINE": 'django.db.backends.postgresql_psycopg2',
        "NAME": 'dbname',
        "USER": 'dbuser',
        "PASSWORD": 'dbuserpassword',
    },
}

8. Creating the database

After you configured your database, you can create the necessary database tables (make sure your virtualenv is still active):

cd /srv/virtualenvs/planop/lib/python2.7/site-packages/planop
python manage.py createdb configs/auth_groups.json

Now prepare the static files:

python manage.py collectstatic

9. Create a superuser

You should create a user that has admin rights on your planop installation and that you can use to login to planop the first time:

python manage.py createsuperuser

You can create extra users and manage their permissions via the planop application later.

10. Celery

Celery is the task broker that allows planop to execute asynchronous tasks, like creating pdf files and mailing them. It needs a task queue to pass its messages around.

The recommended queue is rabbitmq.

Installing rabbitmq: since the rabbitmq version in the Debian/Ubuntu repositories is quite old, it is better to install it from the rabbitmq servers:

echo "deb http://www.rabbitmq.com/debian/ testing main" > /etc/apt/sources.list.d/rabbitmq.list
wget http://www.rabbitmq.com/rabbitmq-release-signing-key.asc
apt-key add rabbitmq-release-signing-key.asc
apt-get update
apt-get install rabbitmq-server -y

Configure rabbitmq.

  • add a user:

    sudo rabbitmqctl add_user name passwd

  • add a vhost:

    sudo rabbitmqctl add_vhost vhostname

  • set permissions:

    sudo rabbitmqctl set_permissions -p vhostname user ".*" ".*" ".*"

Add this setting to your local_settings file, matching the vhostname, user and password you just created:

BROKER_URL = 'amqp://username:passwd@127.0.0.1:5672/vhostname'

To let planop know that celery is available, you will need to change the following setting in your local_settings.py file:

USE_CELERY = True

This will enable the options and buttons in planop that depend on the availability of the asynchronous processing via celery.

11. Cron jobs

It is a good idea to setup cron jobs for the following tasks:

  • backup the database
  • clean up the sessions table
  • create daily versions

Backup the database, eg with a command like this:

pg_dump planop > /srv/backups/planop.dump

You can clean up the sessions table with the following command:

/srv/virtualenvs/planop/bin/python /srv/virtualenvs/planop/lib/python2.7/site-packages/planop/manage.py cleanup

Create daily versions:

/srv/virtualenvs/planop/bin/python /srv/virtualenvs/planop/lib/python2.7/site-packages/planop/manage.py create_version

12. Final configuration

Set the site domain via http://your.domain/admin/sites/site/

Add users via http://your.domain/users/