Introduction

grical is a Django web application for maintaining and finding events. It is the Python software running behind grical.org and other sites.

Howto setup a development environment

The following setup uses sqlite3 as the database backend, virtualenv for the isolated Python environment and a GNU/Linux host system. Other combinations are possible like using PostgreSQL.

Clone the repository

cd ~
git clone git@github.com:wikical/grical.git

Install the OS requirement packages. For Ubuntu 14.04LTS there is a list of OS package requirements at grical/requirements/development.trusty.apt. You can install them with:

cat ~/grical/requirements/development.trusty.apt | tr '\n' ' '|xargs sudo apt-get install

For Ubuntu 15.04+ use:

cat ~/grical/requirements/development.xenial.apt | tr '\n' ' '|xargs sudo apt-get install

Create and activate a Python virtual environment, and setup Django:

mkdir ~/virtualenvs
virtualenv ~/virtualenvs/grical
source ~/virtualenvs/grical/bin/activate
pip install -r ~/grical/requirements/development.pip
python manage_development.py migrate
sqlite3 grical_db.sql "UPDATE django_site SET domain='localhost:8000', name='Grical development';"

Install bower:

cd ~/grical
sudo apt-get instal nodejs npm
sudo npm install bower -g

Install the required packages for grical with bower:

cd ~/grical/requirements
bower install --config.directory=../grical/static/bower_components

Start the Django Development Server

cd ~/grical && python manage_development.py runserver 0.0.0.0:8000

Now you can open the site in your browser by just visiting http://localhost:8000 and edit the source code.

To run the tests, install tox either using a OS package or with pip.

Run tests by issuing the tox command:

cd ~/grical
tox

Howto deploy grical

These instructions assume the installation is taking place in a GNU/Linux system. The database used will be PostgreSQL 9.5.

Create a system user grical and clone the repository

sudo adduser grical
su grical -c "cd /home/grical && hg clone ssh://hg@bitbucket.org/gridmind/grical"

Setup PostgreSQL 9.5, e.g. following http://tecadmin.net/install-postgresql-server-on-ubuntu/:

sh -c 'echo "deb http://apt.postgresql.org/pub/repos/apt/ `lsb_release -cs`-pgdg main" >> /etc/apt/sources.list.d/pgdg.list'
wget -q https://www.postgresql.org/media/keys/ACCC4CF8.asc -O - | apt-key add -
apt-get update
apt-get install postgresql-9.5 postgresql-9.5-postgis-2.2

Install the required OS packages:

cat ~/grical/requirements/production.apt | tr '\n' ' '|xargs sudo apt-get install

Create a DB user, a database, and the postgis extension for the database:

su postgres -c "createuser --pwprompt --no-createdb --no-createrole --no-superuser grical"
su postgres -c "createdb --owner grical -T template1 grical"
su postgres -c "psql -d grical -c 'CREATE EXTENSION IF NOT EXISTS postgis;'"

Keep the grical user password (you have been asked for) for the next step.

Copy grical/settings/development.py to grical/settings/settings.py, and in it:

• Set DEBUG = False
• Review and set CACHES, DATABASES, ADMINS, IMAP_*, GEONAMES_*, REPLY_TO, DEFAULT_FROM_EMAIL, SERVER_EMAIL, EMAIL_SUBJECT_PREFIX and EMAIL_*.
• Set a SECRET_KEY.

For DATABASES use user name, db name and password created above.

Optionally, have a look at settings_base.py for other customization options, documented inline.

Copy manage_development.py to manage.py and replace development in it with settings.

Install the Python requirements:

cd ~grical/grical/requirements
sudo pip install -r production.pip

Install the required JS and CSS packages with Bower:

sudo apt-get instal nodejs npm
sudo npm install bower -g
su grical -c "cd ~grical/grical/requirements && bower install --config.directory=../grical/static/bower_components"

Migrate the database and create a cache table:

su -grical -c "cd ~grical/grical && python manage.py migrate"
su -grical -c "cd ~grical/grical && python createcachetable cache"
psql -d grical_db -U grical_user -h localhost -p 5432 -c "UPDATE django_site SET (domain, name) = ('grical', 'GriCal')"

Setup a cron jobs for accepting events submitted as email. It should run periodically the custom Django management command imap.

Installing memcached is recommended as Grical will automatically use it for performance:

apt-get install memcached

Edit /etc/memcached.conf and restart memcached. Set the Django settings as appropriate.

Run a celery worker as a daemon. This is the best option for production. For the broker we suggest RabbitMQ. The broker setup for Celery and RabbitMQ is minimal and requires no options.

1. Install RabbitMQ:

   apt-get install rabbitmq-server
   

2. Add a user and a vhost:

   rabbitmqctl add_user guest guest
   rabbitmqctl add_vhost "/"
   rabbitmqctl set_permissions -p "/" guest ".*" ".*" ".*"
   

Refer further to Deploying Django. We recommend using uWSGI and nginx.