SetupTheVotingPlatform - fnunnari/deeva GitHub Wiki

Set up a Deeva Voting Platform developer server

This sums up the steps to set up a development server for the Deeva voting platform. It is expected that Python 3.6 or newer and a MySQL server are already installed.

sudo apt-get install mysql-server
sudo apt-get install mysql-client
sudo service mysql start
sudo update-rc.d mysql enable
sudo mysql_secure_installation

(Currently running Ubuntu the mysqlclient package is not working correctly, you additionally need to install it via the systems package manager)

sudo apt-get install gcc
sudo apt-get install python3-dev libmysqlclient-dev

Set up a virtual environment

It is strongly recommended to work in a virtual environment while developing for the platform. It ensures a fixed environment of available packages that everyone can rely on.

  1. Install the virtual environment package if not done yet: pip3 install virtualenv
  2. Create a new environment with python3 -m venv deeva3
  3. Activate the environment with source ./deeva3/bin/activate
  4. Sometimes Python Wheel is needed for the install of some packages. Install it with pip install wheel

Install required packages

Install the packages required to run the voting platform by running:

pip install -r requirements.txt

Remember to crete a new package list when adding required packages by running:

pip freeze > requirements.txt` and pushing the file to the repository.

Set up the database server

The website needs a database and database access in order to work correctly. Currently it is setup to work with MySQL. The connection data the system uses can be found in deeva/deeva/setting.py in the variable DATABASES.

In order to set up the database with the current code proceed as follows:

  1. The MySQL deamon needs to be running (Ubuntu: sudo service mysql start)
  2. Open the MySQL console and log in as privileged user: mysql -u root -p
  3. Create the new database schema for developing : CREATE SCHEMA deeva_dev; (dont forget the semicolon...)
  4. Switch to the newly created schema: USE deeva_dev;
  5. Grant privileges for the django to access the database: GRANT ALL PRIVILEGES ON deeva_dev.* to deeva@localhost identified by '123';.
  6. Exit the MySQL console.

Create tables on the server

Django will alter table on the MySQL server by issuing the migrate and makemigrations command. On the first run it will create them. In the project folder deeva, where the manage.py file is located, run, in order:

  • python manage.py makemigrations
  • python manage.py migrate

Also, every time you alter the DJango tables, you must re-issue the makemigrations. Finally, every time you pull from git and someone else altered the tables, you must re-issue migrate

Create a django-root user

$ python manage.py createsuperuser
Username (leave blank to use 'fanu01'): admin
Email address:
Password:
Password (again):

Run the development server

Finally to run the development server run:

python manage.py runserver

and it will create a locally accessible server on port 8000. You can specify that it accessible from other computers or change the port like so:

pyhton manage.py runserver 0.0.0.0:8000

Login as administrator

This is needed if you want to create new experiments. With your browser, go to: http://localhost:8000/admin

Set up a Deeva Voting Platform deployment server

This is a step by step instruction on how to deploy deeva on a new debian/Ubuntu server with nginx and uwsgi for use in production.

Set up the MySQL server

First we set up the MySQL server so we have a database for the project. Start by installing the packages needed for mysql.

apt-get install mysql-server install mysql-client default-libmysqlclient-dev

You may be asked to set up a password for the server.

We need to set up the schema a grant access to it for the deeva project. Open a mysql shell.

mysql -u user -p

In the shell execute the following commands to create the schema and grant access. Replace PASSWORD by a secure unique password.

CREATE SCHEMA deeva CHARACTER SET utf8 DEFAULT COLLATE utf8_general_ci;
GRANT ALL PRIVILEGES ON deeva.* to deeva@localhost identified by 'PASSWORD';

Set up the Django project and environnement

Now we set up the Django project and environment as usual, but in the www folder of the server instead of the home folder of the user, so www-data can run and serve the files.

Install python, developer dependencies and the tool to create virtual environments.

apt-get install python python3-dev python3-venv

Create a new folder in www for django projects.

cd /var/www
mkdir django
cd django

This folder will hold the root folders of the django projects that will run on this server. Additionally we create a folder for the virtual environments of those projects and create the environment for Deeva.

mkdir virtualenvs
cd virtualenvs
python3 -m venv deeva

Pull the project code of deeva in the django folder.

cd /var/www/django
git clone [email protected]:fnunnari/deeva.git

We need to create a folder for static (css, js, static pictures) and media (uploaded content files for individuals) files.

cd deeva/VotingPlatform
mkdir media
mkdir static

Activate the virtual environment and install the needed packages for the project. Sometimes it is needed to install wheel, if it was not installed automatically.

source ../virtualenvs/deeva/bin/activate
pip install wheel
pip install -r deeva/VotingPlatform/requirements.txt

Go into the project and copy the template for the special_settings file. This file is unique to this server and contains the paths and passwords for the content files and database. Edit the file as needed. Do not push it to source control.

cd /var/www/django/deeva/VotingPlatform/deeva/deeva
cp special_settings_template.py special_settings.py
editor special_settings.py

In the end the file should look similar to this.

DEBUG = False #enable debug for developping
ALLOWED_HOSTS = ['*'] #allow local server to be host
MEDIA_ROOT = '/var/www/django/deeva/VotingPlatform/media/' #place to store uploaded media 
STATIC_ROOT = '/var/www/django/deeva/VotingPlatform/static/'  #place to store static media 

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql', 
        'NAME': 'deeva',
        'USER': 'deeva',
        'PASSWORD': 'PASSWORD',
        'HOST': 'localhost',   # Or an IP Address that your DB is hosted on
        'PORT': '3306',
    }
}

Now it should be possible to run the built-in development server of Django.

cd ..
python manage.py runserver 0.0.0.0:8000

Watch the output and see if it's missing any packages and install them.

It will probably report that migrations are missing (i.e. that no database tables we're created yet). Create the tables by running.

python manage.py migrate

It should now be possible to run the server (though it may only be accessible locally depending on firewall settings).

To prepare for normal server operation we need to collect the static files of the server in the previously created static folder. Run the collectstatic command to do this.

python manage.py collectstatic

The Django project is now now ready to be served by nginx and uwsgi.

Set up uwsgi and ngninx

To handle the requests by users we use nginx and uwsgi. nginx will handle calls to static files immediately and forward any requests for dynamic content (i.e. the views) to uwsgi. Uwsgi will handle the incoming request from nginx and run the python environment.

First, install uwsgi and nginx.

apt-get install uwsgi

Both daemons should run by default on start-up. If not you can run the follwing commands.

systemctl enable uwsgi
systemctl enable nginx

Configure uwsgi

First, we create a configuration file for uwsgi.

cd /etc/uwsgi/apps-available/
nano deeva.ini

The file should contain the following.

[uwsgi]
socket = :8000
buffer-size = 32768
chdir = /var/www/django/deeva/VotingPlatform/deeva
wsgi-file = deeva/wsgi.py
plugins = python36
processes = 4
threads = 2
virtualenv = /var/www/django/virtualenvs/deeva
uid = root

Now we need to link the file in the apps-enabled folder. Restart uwsgi for the changes to take effect.

sudo ln -s deeva.ini ../apps-enabled/deeva.ini
service uwsgi restart

You can try to access the server at port 8000. If there are no errors we can proceed to configure uwsgi.

If for some reason pyhton 3.6 is not available from package manger, see Python 3.6 below.

Configure nginx

Again we start by creating a configuration file for nginx.

cd /etc/nginx/sites-available/deeva
nano deeva.conf

The file should contain the following. Be sure to set the correct IP or FQDN and port.

# deeva.conf

# the upstream component nginx needs to connect to
upstream django_deeva {
    # server unix:///path/to/your/mysite/mysite.sock; # for a file socket
    server 127.0.0.1:8000; # for a web port socket 
}

# configuration of the server
server {
    # the port your site will be served on
    listen      80;
    # the domain name it will serve for
    server_name deeva.mmci.uni-saarland.de; # substitute your machine's IP address or FQDN
    charset     utf-8;

    # max upload size
    client_max_body_size 75M;   # adjust to taste

    # Django media
    location /media  {
        alias /var/www/django/deeva/VotingPlatform/media;  # your Django project's media files - amend as required
    }

    location /static {
        alias /var/www/django/deeva/VotingPlatform/static; # your Django project's static files - amend as required
    }

    # Finally, send all non-media requests to the Django server.
    location / {
        uwsgi_pass  django_deeva;
        include     /var/www/django/deeva/VotingPlatform/uwsgi_params; # the uwsgi_params file you installed
    }
}

Before we can enable this configuration we need to create an additional parameters file mentioned in the configuration.

nano /var/www/django/deeva/VotingPlatform/uwsgi_params

uwsgi_param  QUERY_STRING       $query_string;
uwsgi_param  REQUEST_METHOD     $request_method;
uwsgi_param  CONTENT_TYPE       $content_type;
uwsgi_param  CONTENT_LENGTH     $content_length;

uwsgi_param  REQUEST_URI        $request_uri;
uwsgi_param  PATH_INFO          $document_uri;
uwsgi_param  DOCUMENT_ROOT      $document_root;
uwsgi_param  SERVER_PROTOCOL    $server_protocol;
uwsgi_param  REQUEST_SCHEME     $scheme;
uwsgi_param  HTTPS              $https if_not_empty;

uwsgi_param  REMOTE_ADDR        $remote_addr;
uwsgi_param  REMOTE_PORT        $remote_port;
uwsgi_param  SERVER_PORT        $server_port;
uwsgi_param  SERVER_NAME        $server_name;

Now we can link the file in the sites-enabled folder. Restart nginx for the changes to take effect.

sudo ln -s deeva.ini ../sites-enabled/deeva.conf
service nginx restart

The website should now be available on the selected port.

Python 3.6

If Python 3.6 is not available from package manager you need to install it from source and generate an additional plugin for uwsgi.

This guide was derived from https://www.paulox.net/2017/04/04/how-to-use-uwsgi-with-python3-6-in-ubuntu/

Download python 3.6 form source and run

./configure —-shared-libraries
make
make install
ldconfig

Now we can create the plugin

export PYTHON=python3.6
uwsgi --build-plugin "/usr/src/uwsgi/plugins/python python36"
cp python36_plugin.so /usr/lib/uwsgi/plugins/
chmod 644 /usr/lib/uwsgi/plugins/python36_plugin.so

uwsgi should now work as desired.