Welcome to Pytition’s documentation!

Pytition is an application for privacy-friendly online petitions you can host on your own server. Pytition uses the renown Django framework and is easy to install.

Demo: https://pytitiondemo.sionneau.net/

Installation

Multi-domain installation example

Objectif

Mutualize Pytition’s code so that database and mediaroot directory stay separate for each organization. In practice, on a single hosting server, you will have for instance 2 organizations that will each have their own Pytition instance: pytition.orga1.org and pytition.orga2.org and each web site will share Pytition’s source code but will have its own independant database and mediaroot directory. Because the source code will be shared, it will be easier to keep all the web sites up-to-date, using a dedicated administration account.

Creating user accounts and directories

$ sudo useradd -m -s /bin/bash pytition-admin
$ sudo useradd -m -s /bin/bash orga1-user
$ sudo useradd -m -s /bin/bash orga2-user

pytition-admin will be the user account dedicated to Pytition’s code maintenance.

$ sudo mkdir -p /etc/pytition/{orga1,orga2,admin}
$ sudo touch /etc/pytition/{orga1,orga2,admin}/__init__.py
$ sudo touch /etc/pytition/__init__.py

/etc/pytition will contain database config and credentials as well as Pytition’s config file for each site.

$ sudo mkdir -p /srv/pytition/www/mediaroot/{admin,orga1,orga2}
$ sudo mkdir -p /srv/pytition/www/static

Install system dependencies

$ sudo apt update
$ sudo apt install git virtualenv python3-dev build-essential default-libmysqlclient-dev gettext libzip-dev libssl-dev apache2 uwsgi

Get the source, configure and initialize Pytition

Get the latest release git tag:

$ version=$(curl -s https://api.github.com/repos/pytition/pytition/releases/latest | grep "tag_name" | cut -d : -f2,3 | tr -d \" | tr -d ,)

Create a Python3 virtualenv to install Pytitiont’s dependencies:

$ cd /srv/pytition/
$ sudo virtualenv -p python3 pytition_venv

Clone Pytition git repository and checkout latest release:

$ cd www
$ sudo git clone https://github.com/pytition/pytition
$ cd pytition
$ sudo git checkout $version

Set correct ownership and group to directories:

$ sudo chown -R pytition-admin:www-data /srv/pytition
$ sudo chown orga1-user:www-data /srv/pytition/www/mediaroot/orga1
$ sudo chown orga2-user:www-data /srv/pytition/www/mediaroot/orga2
$ sudo chmod g+s /srv/pytition/www/static/

Enter your virtualenv and install Pytition’s dependencies:

$ sudo su pytition-admin
$ source /srv/pytition/pytition_venv/bin/activate
(pytition_venv) $ pip3 install -r /srv/pytition/www/pytition/requirements.txt

Create db-pytition-orga, db-pytition-orga2, db-pytition-admin as well as associated SQL users db-user-orga1, db-user-orga2 and db-user-admin on your MariaDB SQL server.

You need to write a /etc/pytition/{orga1,orga2,admin}/my.cnf file for each organization.

[client]
host = your-data-base-server
database = db-pytition-orga1
user = db-user-orga1
password = YOUR_PASSWORD_HERE
default-character-set = utf8

For the administration account, you can use an sqlite3 database instead of creating a new database on MariaDB.

Create the /etc/pytition/{orga1,orga2,admin}/config.py file for each organization. You can start by copying the configuration example file /src/pytition/www/config_example.py

The my.cnf and config.py files must have the correct permissions.

E.g. for orga1:

$ sudo chown orga1:pytition-admin /etc/pytition/orga1/{my.cnf,config.py}
$ sudo chmod u=rw,g=r,o=--- /etc/pytition/orga1/{my.cnf,config.py}

Now you can edit your config file in pytition/pytition/settings/config.py according to Configuration.

You must at least configure the settings described in the Mandatory settings section of the Configuration page.

Those are:

  • SECRET_KEY

  • STATIC_URL

  • STATIC_ROOT

  • MEDIA_URL

  • MEDIA_ROOT

  • DATABASES

  • ALLOWED_HOSTS

Warning

Pay attention to the following config values:

STATIC_ROOT = "/srv/pytition/www/static"
MEDIA_ROOT = "/srv/pytition/www/mediaroot/orga1 (pour le config.py de l'orga1)

The DATABASE config value should point to /etc/pytition/orga1/my.cnf

Note

Do not forget to put a correct path to the my.cnf MySQL credential file in your each config DATABASES setting.

Initialize Pytition as well as its databases. You must be in the virtualenv while entering the following commands:

$ export PYTHONPATH="/etc/pytition"
$ cd /srv/pytition/www/pytition/pytition
$ sudo -u pytition-admin -- DJANGO_SETTINGS_MODULE="admin.config" python3 manage.py migrate
$ sudo -u pytition-admin -- DJANGO_SETTINGS_MODULE="admin.config" python3 manage.py collectstatic
$ sudo -u pytition-admin -- DJANGO_SETTINGS_MODULE="admin.config" python3 manage.py compilemessages
$ sudo -u pytition-admin -- DJANGO_SETTINGS_MODULE="admin.config" python3 manage.py createsuperuser
$ sudo -u orga1-user -- DJANGO_SETTINGS_MODULE="orga1.config" python3 manage.py migrate
$ sudo -u orga2-user -- DJANGO_SETTINGS_MODULE="orga2.config" python3 manage.py migrate

Note

You will be asked to enter a username, email and password for the administrator’s

Before trying to configure a web server you can try to see if your configuration is OK by running: E.g. for orga1:

$ DEBUG=1 DJANGO_SETTINGS_MODULE=orga1.config python3 ./manage.py runserver

You can then point your browser to http://yourdomain.tld:8000 and check that you can see Pytitiont’s home page and log-in with your newly created admin account.

Warning

If you’ve set USE_MAIL_QUEUE to True and MAIL_EXTERNAL_CRON_SET to False, running Pytition via manage.py runserver might not work well since you need to be run via uwsgi. Especially emails might not be sent.

Note

If you switch USE_MAIL_QUEUE from False to True at some point, you might have to re-run python3 manage.py migrate to create the database structures needed for the mail queues.

Apache and uwsgi configuration

Install uwsgi dependency:

$ sudo apt install uwsgi uwsgi-plugin-python3 python3-uwsgidecorators

and enable proxy_uwsgi on apache:

$ sudo a2enmod proxy_uwsgi

Here is an example of Apache configuration that you can put in /etc/apache2/sites-available/orga1:

<VirtualHost *:80>

ServerName pytition.orga1.org

Alias /static /srv/pytition/www/static
Proxypass /static !
Alias /mediaroot /srv/pytition/www/mediaroot/orga1/
Proxypass /mediaroot !

ProxyPass / unix:/var/run/uwsgi/app/pytition.orga1.org/socket|uwsgi://localhost/

<Directory /srv/pytition/www/static>
Require all granted
</Directory>

<Directory /srv/pytition/www/mediaroot>
Require all granted
</Directory>

CustomLog /var/log/apache2/access.log combined
CustomLog /var/log/apache2/pytition.orga1.org.log combined

</VirtualHost>

Here is an example of uwsgi configuration that you can put in /etc/uwsgi/app-available/. Don’t forget to create a symbolic link in /etc/uwsgi/app-enabled pointing to the previously created file.

[uwsgi]
chdir = /srv/pytition/www/pytition/pytition
module = pytition.wsgi
home = /srv/pytition/pytition_venv
master = true
enable-threads = true
processes = 5
vacuum = true
socket = /var/run/uwsgi/app/pytition.orga1.org/socket
uid = orga1-user
gid = www-data
chmod-socket = 664
pythonpath = /etc/pytition/
plugins = python3
env = DJANGO_SETTINGS_MODULE=orga1.config
stats = 127.0.0.1:9191
need-app = true
max-requests = 5000
max-worker-lifetime = 3600
reload-on-rss = 2048
worker-reload-mercy = 60
harakiri = 120
py-callos-afterfork = true
auto-procname = true
procname-prefix = orga1->

Start uwsgi and nginx servers:

$ sudo systemctl start uwsgi
$ sudo systemctl start apache2

Your Pytition home page should be available over there: http://pytition.orga1.org

Now it’s time to Configure your Pytition instance the way you want!

Regular maintenance (update)

In order to update all your Pytition sites, here is a bach script (run by pytition-admin user) which can be used in a cron task:

#!/bin/bash
set -e
DJANGO_MANAGE="/srv/pytition/www/pytition/pytition/manage.py"
source /srv/pytition/pytition_venv/bin/activate
export PYTHONPATH="/etc/pytition/"
echo
echo "###########################"
echo "Updating admin Pytition"
echo "###########################"
echo
DJANGO_SETTINGS_MODULE="admin.config" python3 $DJANGO_MANAGE maintenance_mode on
DJANGO_SETTINGS_MODULE="admin.config" python3 $DJANGO_MANAGE update
DJANGO_SETTINGS_MODULE="admin.config" python3 $DJANGO_MANAGE maintenance_mode off
for site in $(ls /etc/pytition|grep -vE "^admin$|^__init__\.py$")
do
echo
echo "#################################################"
echo "Updating $site Pytition"
echo "#################################################"
echo
  DJANGO_SETTINGS_MODULE="$site.config" python3 $DJANGO_MANAGE maintenance_mode on
  DJANGO_SETTINGS_MODULE="$site.config" python3 $DJANGO_MANAGE migrate
  DJANGO_SETTINGS_MODULE="$site.config" python3 $DJANGO_MANAGE maintenance_mode off
done
deactivate

Configuration

A configuration example is provided in pytition/settings/config_example.py. You should copy and edit it to configure Pytition.

Mandatory settings

You must set the following variables:

ALLOWED_HOSTS = ['127.0.0.1', 'localhost', '[::1]']
Enter the hostname(s) (aka VirtualHost(s)) Django should accept.
For instance mydomain.tld or petition.mydomain.tld

See also

Details on how to set this up are available in Django documentation: ALLOWED_HOSTS

Example:

ALLOWED_HOSTS = ['www.mysuperpetition.org', 'mysuperpetition.org']
DATABASES = {}
Enter a database setting.
This will tell Django what database engine you want to use (supported ones are listed there: https://docs.djangoproject.com/en/2.2/ref/settings/#std:setting-DATABASE-ENGINE)
It will also give parameters like user/password credentials, server host/port etc.

See also

Details on how to set this up are available in Django documentation: https://docs.djangoproject.com/en/2.2/ref/settings/#std:setting-DATABASES

In the following example, credentials are in my.cnf file:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'OPTIONS': {
            'read_default_file': '/home/pytition/my.cnf',
            'init_command': "SET sql_mode='STRICT_TRANS_TABLES'",
        },
    }
}
MEDIA_ROOT = ''
Enter the file system path to the directory that will be used to serve user uploaded files.
This must be an initially empty directory.
You must also configure a web server (apache, nginx or other) to serve
the content of this directory according to your MEDIA_URL setting
which default is '/mediaroot/' in the example config.

For instance you can have this kind of setting:

MEDIA_ROOT = '/home/pytition/www/mediaroot'
MEDIA_URL = '/mediaroot/'

And then in your apache config:

Alias /mediaroot /home/pytition/www/mediaroot

Or in your nginx config:

location /mediaroot {
    alias /home/pytition/www/mediaroot;
}

See also

https://docs.djangoproject.com/en/2.2/ref/settings/#std:setting-MEDIA_ROOT for more details from Django Documentation

MEDIA_URL = '/mediaroot/'
enter the prefix that will be used for the url to refer to uploaded files.
it must end with a forward slash ‘/’.
you must also configure a web server (apache, nginx or other) to serve
the content of the directory configured as MEDIA_ROOT according to this setting
it defaults to '/mediaroot/' in the example config.

for instance you can have this kind of setting:

MEDIA_ROOT = '/home/pytition/www/mediaroot'
MEDIA_URL = '/mediaroot/'

and then in your apache config:

alias /mediaroot /home/pytition/www/mediaroot

or in your nginx config:

location /mediaroot {
    alias /home/pytition/www/mediaroot;
}

See also

https://docs.djangoproject.com/en/2.2/ref/settings/#std:setting-MEDIA_URL for more details from django documentation

SECRET_KEY = ''
Enter a random, unique and private secret key.
Pytition won’t start without it.
Never share it, don’t commit in git.
See https://docs.djangoproject.com/en/2.2/ref/settings/#std:setting-SECRET_KEY for more details from Django documentation
To generate it, you can use the following command from your virtualenv with Django installed:
$ python3 -c "from django.core.management.utils import get_random_secret_key as g; print(g())"

Example:

SECRET_KEY = 'my secret key here'
STATIC_ROOT = None
Enter the file system path to the directory that will be used to serve your static files.
This must be an initially empty directory.
You must also configure a web server (apache, nginx or other) to serve
the content of this directory according to your STATIC_URL setting
which default is '/static/' in the example config.

For instance you can have this kind of setting:

STATIC_ROOT = '/home/pytition/www/static'
STATIC_URL = '/static/'

And then in your apache config:

Alias /static /home/pytition/www/static

Or in your nginx config:

location /static {
    alias /home/pytition/www/static;
}

See also

https://docs.djangoproject.com/en/2.2/ref/settings/#std:setting-STATIC_ROOT for more details from Django Documentation

STATIC_URL = '/static/'
enter the prefix that will be used for the url to refer to static files.
it must end with a forward slash ‘/’.
you must also configure a web server (apache, nginx or other) to serve
the content of the directory configured as STATIC_ROOT according to this setting
it defaults to '/static/' in the example config.

for instance you can have this kind of setting:

STATIC_ROOT = '/home/pytition/www/static'
STATIC_URL = '/static/'

and then in your apache config:

alias /static /home/pytition/www/static

or in your nginx config:

location /static {
    alias /home/pytition/www/static;
}

See also

https://docs.djangoproject.com/en/2.2/ref/settings/#std:setting-static_url for more details from django documentation

Not mandatory but important settings

You are highly encouraged to set the following variables in a production environment:

Pytition specific settings

USE_MAIL_QUEUE = False
Set it to True if you want email sending to retry upon failure.
Email transmition naturally have retries if the first SMTP server accepts it
If your SMTP server refuses to handle the email (anti-flood throttle?) then it
is up to you to retry, and this is what the mail queue does for you.
This is especially needed if you don’t own the first-hop SMTP server
and cannot configure it to always accept your emails regardless of the sending
frequency.
It is HIGHLY recommended to set this to True.
If you chose to use the mail queue, you must also either

  • set a cron job (automatic task execution), or

  • serve the Django app through uwsgi (recommended setup)

Warning

The first time you switch this setting from False to True, you must run the DJANGO_SETTINGS_MODULE=pytition.settings.config python3 pytition/manage.py migrate command again. Beware to run it while being in your virtualenv.

ALLOW_REGISTER = True
Whether you want to allow anyone to create an account and host petitions
on your Pytition instance.
Set it to False for a private instance.
Set it to True for a public instance.
DEFAULT_NOREPLY_MAIL = 'noreply@domain.tld'
Default address for ‘Reply to’ field in mail sent on account creation

Django settings

The following settings are important to set so that the email sent by Pytition are less likely to be considered as spam/junk. You should configure a real SMTP email account and not just rely on “fake” email address from local sendmail:

Other optional settings

Those are things you can configure to customize your Pytition instance:

SITE_NAME = 'Pytition'
The name of your Pytition instance.
FOOTER_TEMPLATE = None
Leave it set to None for no footer.
This should contain the relative path to your footer template.
That would be the location for any “legal mention” / “GDPR” / “TOS” link.

Example:

FOOTER_TEMPLATE = 'layouts/footer.html.example'
DISABLE_USER_PETITION = False
If set to True, users won’t be able to create petitions in their name, but only for an organization
RESTRICT_ORG_CREATION = False
If set to True, regular users won’t be able to create new organizations.
Only superusers will be allowed to

Update

Backup your files

Backup your media files, those are the pictures uploaded by your users in the petition contents and metadata.

The files to backup are in the mediaroot directory that you configured in your settings in the MEDIA_ROOT variable.

$ source path/to/pytition_venv/bin/activate
$ export DJANGO_SETTINGS_MODULE="pytition.settings.config" # path to your config
$ backup_dir=pytition_backup_$(date +%Y%m%d_%H%M%S)
$ mediaroot_dir=$(python3 pytition/manage.py shell -c 'from django.conf import settings; print(settings.MEDIA_ROOT)')
$ rsync -av $mediaroot_dir $backup_dir

Backup your Database

For this, I would advise to use the tools provided with your database server.

  • SQLite: just copy your .db file and you’re done!

  • PostgreSQL: use pg_dump to backup and psql to restore

  • MariaDB / MySQL: use mysqldump to backup and mysql to restore

You can also try to backup using the django tool:

$ source path/to/pytition_venv/bin/activate
$ export DJANGO_SETTINGS_MODULE="pytition.settings.config" # path to your config
$ # let's dump data
$ python3 pytition/manage.py dumpdata --all --output data.json
$ # now let's restore it
$ python3 pytition/manage.py loaddata data.json

Warning

Always test your backup mechanism. If not tested, you can only suppose your backups are worthless. You need to try to restore them on a dummy and empty instance, in order to make sure the backup is OK. Untested backups do not work.

Update to a newer Pytition version

You can simply run the update command of the manage.py CLI:

$ source pytition_venv/bin/activate
$ python3 pytition/manage.py update

Or go through the following document and do it manually.

Download latest Pytition release tarball or update your git clone:

$ git stash && git pull
$ version=$(curl -s https://api.github.com/repos/pytition/pytition/releases/latest | grep "tag_name" | cut -d : -f2,3 | tr -d \" | tr -d ,)
$ git checkout $version

Then upgrade Pytition’s dependencies:

$ source pytition_venv/bin/activate
(pytition_venv) $ pip3 install --upgrade -r requirements.txt

Then update your database scheme, update static files, compile new translation files:

$ export DJANGO_SETTINGS_MODULE="pytition.settings.config" # path to your config
$ python3 pytition/manage.py migrate
$ python3 pytition/manage.py collectstatic
$ python3 pytition/manage.py compilemessages

Then restart your web server, be it apache or nginx, and also your application server (uWSGI). Congratulations! You should now be OK with a brand new Pytition release!

Indices and tables