Web application for sharing events
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Type Name Latest commit message Commit time
Failed to load latest commit information.
db_migration Updated legacy db migration instructions and script, after the actual… Jan 16, 2019
grical migration error https://trello.com/c/UzZX5Vsq/2576-initial-migration-… Feb 18, 2019
.gitignore fixed some packages in requirements for development Feb 15, 2019
AGPLv3.TXT improved event edit select field Sep 28, 2016
CHANGELOG.rst improved documentation Jan 6, 2017
README.rst Minor doc Jul 28, 2017
copyright.rst improved documentation Jan 6, 2017



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

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

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