Installation¶

Updated on June 15th 2018 by @henrinie

These instructions are written for linux operating systems. For Windows or MacOS some parts might be relevant, look up python docs and django docs for further instructions for those operating systems.

Set up the environment¶

Clone the git repository, create a python virtual environment, install dependencies with pip, and configure the relevant settings.

Git repository¶

Clone the repository to your machine from GitHub:

$ git clone https://github.com/Signbank/FinSL-signbank.git

Python Virtual Environment¶

Create a virtual environment in python3:

$ cd FinSL-signbank
$ python3 -m venv venv
$ source venv/bin/activate

If you need to deactivate the environment write:

$ deactivate

Install dependencies with pip¶

Install required python dependencies:

$ pip install -r /path/to/requirements.txt
Example: $ pip install -r FinSL-signbank/requirements.txt

Configure settings¶

Edit settings files in FinSL-signbank/signbank/settings/ and change the paths in:

# settings/production.py & settings/development.py
LOCALE_PATHS = (
    '/path/to/FinSL-signbank/locale',
)
STATIC_ROOT = '/path/to/FinSL-signbank/static' # For development only! Production dir needs to be server by web server.
MEDIA_ROOT = '/path/to/FinSL-signbank/media' # For development only! Production dir needs to be server by web server.

# settings/development.py
LOGGING = {
...
'filename': '/path/you/want/debug.log'
...
}

# settings/production.py

# IMPORTANT: The hostname that this signbank runs on, this prevents HTTP Host header attacks
ALLOWED_HOSTS = ['yourhost.here.com']

STATIC_ROOT = '/path/to/static' # Served by the web server, e.g. /var/www/yourdomain/static
MEDIA_ROOT = '/path/to/media' # Served by the web server, e.g. /var/www/yourdomain/media

WSGI_FILE = '/path/to/FinSL-signbank/signbank/wsgi.py' # This will matter when you want to use a web server

Rename settings/settings_secret.py.template

$ mv settings/settings_secret.py.template settings/settings_secret.py

Edit settings/settings_secret.py

# settings/settings_secret.py

# Make SECRET_KEY unique and do not share it with anyone
# You may use characters available in ASCII
SECRET_KEY = 'yoursecretkey!"#¤%&/()=?'
ADMINS = (
    ('Your Name', 'your.email@address.com'),
)
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': '/path/to/signbank.db',
    }
}

Tip

Generate a random secret key

Databases¶

We kindly recommend using PostgreSQL with FinSL-signbank, because django-framework is optimized to run on PostgreSQL. We have used MySQL in the past, but at least in our case we started to experience some problems with migrations.

PostgreSQL¶

When you are ready to switch to a database server, PostgreSQL is our recommendation, see django docs for more information about setting django up with PostgreSQL: https://docs.djangoproject.com/en/stable/ref/databases/#postgresql-notes.

In your postgresql.conf make sure you have the following:

client_encoding = 'UTF8'
default_transaction_isolation = 'read committed'
timezone: 'UTC' # Because USE_TZ = True in FinSL-signbank

Edit settings/secret_settings.py

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql_psycopg2',
        'NAME': 'mydatabase',
        'USER': 'mydatabaseuser',
        'PASSWORD': 'mypassword',
        'HOST': '127.0.0.1',
        'PORT': '5432',
    }
}

Then install psycopg2 with pip when your virtual environment is activated.

$ pip install psycopg2

SQLite¶

Edit the following lines in settings/secret_settings.py:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.sqlite3',
        'NAME': '/path/to/signbank.db',
    }
}

MySQL¶

If your database of choice is MySQL, create my.cnf for your MySQL credentials

[client]
database = yourdatabasename
user = yourusername
password = "yourpassword"
host = host.name.com # Could be localhost, if the database is hosted on the local machine
port = 3306 # Or whichever is the correct one for your setting
default-character-set = utf8 # This is pretty much required with django

After done with my.cnf settings, make sure that the file is not accessible by anyone else than you

$ chmod 600 my.cnf

If you have problems with access by apache, place your my.cnf in a place where it can be accessed, or play with the user rights in the current location.

Edit settings/secret_settings.py

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.mysql',
        'OPTIONS': {
            'read_default_file': '/path/to/my.cnf',
            'init_command': 'SET storage_engine=INNODB',
        },
    }
}

Then install MySQL-python with pip when your virtual environment is activated.

$ pip install MySQL-python

On RHEL and CentOS you might need additional packages, if the pip installing of MySQL-python is not working, you might try to install mariadb-devel. For debian based distributions the package name might be different.

$ sudo yum install mariadb-devel

It might be required that you install MySQL-python again with pip. Remove it and install it again without using the cache.

$ pip uninstall MySQL-python
$ pip install MySQL-python --no-cache

Other settings¶

Change these settings in settings/base.py according to your needs

# settings/base.py
TIME_ZONE = 'Europe/Helsinki'
LANGUAGE_CODE = 'fi' # examples: 'en-us', 'de', 'se'

# Enter the desired languages under this setting. These languages can be translated in the app.
LANGUAGES = (
    ('fi', _('Finnish')),
    ('en', _('English')),
)

Database migration¶

Once we have handled all the settings, we can migrate the database.

Make sure you are in your environment

$ source /path/to/venv/bin/activate

First create migrations for django flatpages app to add translation fields with django-modeltranslation:

$ python FinSL-signbank/bin/develop.py makemigrations

Then migrate:

$ python FinSL-signbank/bin/develop.py migrate

Load fixture for flatpages:

$ python FinSL-signbank/bin/develop.py loaddata flatpages_initial_data

Note: In MySQL you might need to change the default collation, if the utf8_general_ci doesn’t match your languages alphabetical order. You might need to do this to all the tables of the signbank app (not on the ones that begin with django_ or auth_). Take a look at: http://dev.mysql.com/doc/refman/5.7/en/charset-unicode-sets.html and https://docs.djangoproject.com/en/stable/ref/databases/#collation-settings

Run djangos test/development server to see if it works

# Run locally, only accessible from the machine you are running signbank with
$ python FinSL-signbank/bin/develop.py runserver localhost:8000

# Or run in your network/internet by entering your IPaddress or your hostname
$ python FinSL-signbank/bin/develop.py runserver 80.12.16.10:8000 # Change the port if needed

Apache (httpd)¶

Apache + mod_wsgi¶

This process can differ between linux distributions. Take a look at django documentation.

You can read about the settings in django documentation. These settings work with CentOS7 and apache httpd 2.4. The location of the configurations vary between linux distributions. It is important to note that you should definitely store FinSL-signbank and django files outside of the path your webserver serves to the web (f.ex. /var/www/), I suggest that you store the files inside your /home/ folder. This way you avoid the risk of your settings, code and files being accessible from the web. Your wsgi.py file should be located at FinSL-signbank/signbank/wsgi.py.

#/etc/httpd/conf/httpd.conf
# These lines set the WSGI directories for FinSL-signbank and django
WSGIScriptAlias / /path/to/FinSL-signbank/signbank/wsgi.py
WSGIDaemonProcess FinSL-signbank python-path=/path/to/FinSL-signbank:/path/to/FinSL-signbank/venv/lib/python3.x/site-packages
WSGIProcessGroup FinSL-signbank

<Directory /path/to/FinSL-signbank/signbank>
    SetEnvIfNoCase Host your\.domain\.com VALID_HOST
    Require env VALID_HOST
    Options +FollowSymLinks -ExecCGI
    <Files wsgi.py>
        Require env VALID_HOST
    </Files>
</Directory>

# Creates alias for /media as /static
# This will be the directory where static files are collected to, the web server should serve them not django.
Alias /static /path/to/static # For example /var/www/yourdomain/static ,
# Sets robots.txt to be accessible at /robots.txt, you need to create the robots.txt file to suit your needs
Alias /robots.txt /path/to/static/robots.txt
# Sets favicon.ico to be accessible at /favicon.ico, you need to create a favicon
Alias /favicon.ico /path/to/FinSL-signbank/favicon.ico

# Create alias for /media/ directory
Alias /media /path/to/media # For example /var/www/yourdomain/media
# Gives access to /media directory
<Directory /path/to/media>
    SetEnvIfNoCase Host your\.domain\.com VALID_HOST
    Require env VALID_HOST
</Directory>

Apache envvars¶

If you are running Signbank with apache (or probably any web server), make sure it is running on the right locale. For example in CentOS Apache seemed to run on LANG=C by default. To avoid problems with non-ascii characters, add these values to your web server evnvvars (in CentOS /etc/sysconfig/httpd):

LANG='en_US.UTF-8'
LC_ALL='en_US.UTF-8'

HTTPS¶

It is strongly recommended that you run your production server with HTTPS. For this take a look at the HTTPS specific settings in the settings files. Have a look at the django docs: https://docs.djangoproject.com/en/stable/topics/security/#ssl-https And also configure your domain properly for HTTPS. If you need free certificates check out LetsEncrypt at https://letsencrypt.org/.