Installation guide

Typography

Commands starting with # must be run as root user.

Commands starting with $ must be run as ponytracker user.

Requirements

You need python. Versions 2.7, 3.2 or 3.4 (and probably others) are fine.

This installation guide install PonyTracker in a virtualenv. The corresponding packages names are python-virtualenv for python 2 and python3-virtualenv for python 3 (at least under Debian).

You need also supervisord to launch PonyTracker. You can install it with the package with the same name.

Installation

Clone and configuration

Be sure /srv/www exists:

# mkdir -p /srv/www

Create a dedicated user:

# useradd -r -m -d /srv/www/ponytracker ponytracker

The following commands are executed as ponytracker user:

# su ponytracker
$ cd /srv/www/ponytracker

Create the log and www directories:

$ mkdir log www

Clone the git repository and switch to the release branch:

$ git clone http://github.com/ponytracker/ponytracker
$ cd ponytracker # we are now in /srv/www/ponytracker/ponytracker
$ git checkout release

Copy the example configuration file:

$ cp ponytracker/local_settings.py.example ponytracker/local_settings.py

Set the SECRET_KEY value. You can generate a secret key with openssl:

$ openssl rand -base64 32

If you want email notifications, set BASE_URL, EMAIL_HOST (smtp relay) and DEFAULT_FROM_EMAIL.

If you want to use another database than the default one (SQLite), set DATABASES. You can find the syntax in the django documentation.

Set the static directory:

STATIC_ROOT = '/srv/www/ponytracker/www/static'

Create a virtualenv and activate it:

$ virtualenv env
$ source env/bin/activate

Install the requirements:

$ pip install -r requirements.txt

Initialize the database tables:

$ python manage.py migrate

Create an account for the administrator:

$ python manage.py createsuperuser

Install javascript libraries with bower:

$ python manage.py bower install

Collect static files in the STATIC_DIR:

$ python manage.py collectstatic --settings=ponytracker.local_settings

Run django

You can use gunicorn or uwsgi, both started by supervisord.

Using gunicorn

Install gunicorn:

$ pip install gunicorn

Create the new file /etc/supervisor/conf.d/ponytracker.conf containing:

[program:ponytracker]
command=/srv/www/ponytracker/ponytracker/env/bin/gunicorn ponytracker.wsgi:application
directory=/srv/www/ponytracker/ponytracker
environment=PATH="/srv/www/ponytracker/ponytracker/env/bin"
user=ponytracker
autostart=true
autorestart=true
redirect_stderr=true

Update the file ponytracker/wsgi.py to use local settings instead of default settings:

os.environ.setdefault("DJANGO_SETTINGS_MODULE", "ponytracker.local_settings")

In order not to have conflicts during an update, you can tell git to ignore this modification:

$ git update-index --assume-unchanged ponytracker/wsgi.py

Using uwsgi

Install uwsgi:

$ pip install uwsgi

Create the new file /etc/supervisor/conf.d/ponytracker.conf containing:

[program:ponytracker]
command=/srv/www/ponytracker/ponytracker/env/bin/uwsgi --ini uwsgi.ini
directory=/srv/www/ponytracker/ponytracker
environment=PATH="/srv/www/ponytracker/ponytracker/env/bin"
environment=DJANGO_SETTINGS_MODULE="settings.local_settings"
user=ponytracker
autostart=true
autorestart=true
redirect_stderr=true

Create the new file /srv/www/ponytracker/ponytracker/uwsgi.ini containing:

[uwsgi]
chdir=/srv/www/ponytracker/ponytracker
module=ponytracker.wsgi:application
master=True
pidfile=/tmp/ponytracker.pid
vacuum=True
max-requests=5000
http-socket = 127.0.0.1:8000

Verify

Start supervisord to run the server:

$ service supervisor start

You can check that the server is listening on localhost on port 8000:

$ lsof | grep LISTEN | grep ponytracker

You now need to install a real web server as a front-end. This documentation shows sample configuration files for both apache and nginx.

Front-end

Apache

<VirtualHost *:443>
    ServerName ponytracker.example.com
    ServerAdmin webmaster@example.com
    DocumentRoot /var/empty

    RewriteEngine on
    RewriteRule ^(.*)$ https://%{HTTP_HOST}$1 [R=301,L]
</VirtualHost>

<VirtualHost *:443>
    ServerName ponytracker.example.com
    ServerAdmin webmaster@example.com
    DocumentRoot /srv/www/ponytracker/www

    SSLEngine on
    SSLCertificateFile /etc/apache2/ssl/ponytracker.example.com.pem
    SSLCertificateKeyFile /etc/apache2/ssl/ponytracker.example.com-Key.pem
    SSLCACertificateFile /etc/apache2/ssl/ponytracker.example.com-CA.pem

    <Location /static>
        ProxyPass !
    </Location>

    <Location />
        ProxyPass http://127.0.0.1:8000/
        ProxyPassReverse http://127.0.0.1:8000/
    </Location>

    ErrorLog /srv/www/ponytracker/log/error.log
    CustomLog /srv/www/ponytracker/log/access.log combined
</VirtualHost>

nginx

Forthcoming...

Send email asynchronously with the celery worker

By default, email notifications are sent during processing of pages. This behaviour can slow down the user experience. It is recommended to use a separated thread to asynchronously send the emails.

PonyTracker is designed to use celery as a worker to send emails. In order to get celery working, you need a broker. This guide uses the redis broker but you can find how to install another broker in the celery documentation.

Install redis:

# aptitude install redis

Enter in the virtualenv and install python requirements:

# su ponytracker
$ cd /srv/www/ponytracker/ponytracker
$ source env/bin/activate
$ pip install celery[redis]
$ pip install django-celery

Add djcelery to your enabled applications in your local settings (ponytracker/local_settings.py):

INSTALLED_APPS += ('djcelery',)

Enable celery specific commands for the manage.py script by adding these lines in your local settings:

import djcelery
djcelery.setup_loader()

Tell celery to use your redis broker by adding the BROKER_URL in your local settings:

BROKER_URL = 'redis://localhost:6379/0'

Run the celery worker:

$ python manage.py celery worker --loglevel=info --settings=ponytracker.local_setting

Forthcomming: how to launch celery from supervisord.

Use LDAP authentication

The python package providing LDAP support need to be compiled. Don’t worry, pip does it itself, but you need to install some requirements:

# apt-get install python-dev libldap2-dev libsasl2-dev libssl-dev

libssl-dev is required only if want to use a SSL connection to your LDAP server. libsasl2-dev is only required if you want to use SASL authentication.

Enter in the virtualenv and install needed packages:

# su ponytracker
$ cd /srv/www/ponytracker/ponytracker
$ source env/bin/activate
$ pip install python-ldap django-auth-ldap

Add django_auth_ldap.backend.LDAPBackend to your authentication back-ends in ponytracker/local_settings.py:

AUTHENTICATION_BACKENDS += (
    'django_auth_ldap.backend.LDAPBackend',
)

Configure the back-end by adding required variables in your local settings. You can find the documentation on the official website. A sample file is provided.

If you use posixGroup, import PosixGroupType instead of GroupOfNamesType and update the AUTH_LDAP_GROUP_TYPE variable.

Add the following line to synchronize your LDAP groups with django ones:

AUTH_LDAP_MIRROR_GROUPS = True

Setup emails answering

PonyTracker allow users to directly answer email in order to add a new comment to an issue. To enable this feature, add these two parameters in your configuration file:

REPLY_EMAIL = 'reply@ponytracker.example.com'
EMAIL_KEY = 'CHANGE ME'

Then, you need to handle all emails received on REPLY_EMAIL and do a post request on http://ponytracker.example.com/api/email/recv/` with them. The post request should contain the key key containing EMAIL_KEY value and the email as a Multipart-Encoded file named email.

For that, you can use a sieve filter with the filter plugin.

To activate the filter with dovecot, copy the file tools/ponytracker-sieve-filter to /usr/lib/dovecot/sieve-filter/ponytracker. Be sure to activate the vnd.devocot.filter in dovecot configuration, usually in /etc/dovecot/conf.d/90-sieve.conf:

sieve_extensions = +vnd.dovecot.execute

Then, you can use a similar sieve script:

require ["fileinto", "imap4flags", "vnd.dovecot.filter"];

if address :matches "To" "reply*@ponytracker.example.com" {
  filter "ponytracker" "EMAIL_KEY@http://ponytracker.example.com/api/email/recv/";
  addflag "\\Seen";
  fileinto "Trash";
}