Ubuntu 14.04

These instructions were written for Ununtu 14.04.4 LTS, but should be able to be adapted for other versions.

This installation method is not recommended unless you have a particular use case. Docker is the most widely used installation method.

The basics

We are going to run Sal using the Gunicorn server - this is a server that is designed to run Python apps, and will sit behind your web server of choice (nginx or Apache if you're old school), and we are also going to set up the PostgreSQL database for Sal.

First off, let's get Python and PostgreSQL installed.

$ sudo apt-get update
$ sudo apt-get install python-pip python-dev software-properties-common libpq-dev postgresql postgresql-contrib git libffi-dev

Create the database and user

Next off is to set up the database and the user that Sal will connect to it with. First switch to the postgres user and then log into PostgreSQL

$ sudo su - postgres
$ psql

Now we can create the database:

CREATE DATABASE sal;

And you can choose your own username and password here:

CREATE USER sal_admin WITH PASSWORD 'sal_password';

Finally, give them permissions and quit, and exit out of the postgres user:

GRANT ALL PRIVILEGES ON DATABASE sal TO sal_admin;
\q
exit

Set up Python

Now we're going to install pip and create the virtual environment for Sal to run.

$ sudo pip install virtualenv

And now we need to set up a service user (as it's bad form to run these things as root)

$ sudo useradd -M sal_user
$ sudo usermod -L sal_user

Finally, let's make somewhere for our stuff to live and make our service account the user:

$ sudo mkdir -p /usr/local/sal_install
$ sudo chown sal_user /usr/local/sal_install

Now elevate yourself to root and switch to the sal_user:

$ sudo -i
$ su - sal_user

Let's create the virtualenv and activate it:

$ cd /usr/local/sal_install
$ virtualenv sal_env
$ source sal_env/bin/activate

Now let's download the latest release of Sal (please refer to the releases for the latest version number):

$ git clone https://github.com/salopensource/sal.git
$ cd sal
$ git checkout tags/3.0.3

Install Sal's dependencies:

$ pip install -r setup/requirements.txt
$ pip install psycopg2==2.5.3
$ pip install gunicorn==19.4.5

Customise Sal

We need to make a copy of the default settings file and open it in a text editor (I like nano, you can use whatever you want)

$ cp sal/example_settings.py sal/settings.py
$ nano sal/settings.py

You will see a section for configuring your database. Make it look like the below:

DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql_psycopg2',
        'NAME': 'sal',
        'USER': 'sal_admin',
        'PASSWORD': 'sal_password',
        'HOST': 'localhost',
        'PORT': '',
    }
}

Now we can populate the database:

$ python manage.py migrate
$ python manage.py collectstatic

And create the admin user:

$ python manage.py createsuperuser

We're done with our service account for now, so let's go back to root:

$ deactivate
$ exit

Gunicorn

As mentioned previously, we're using Gunicorn to run the app behind a web server. In your favourite editor, open up /etc/init/gunicorn.conf, and make it look like the below. You should change the number of workers to be the number of cores in your server + 1 (e.g. 3 workers for a 2 core server).

description "Gunicorn application server handling Sal"

start on runlevel [2345]
stop on runlevel [!2345]

respawn
setuid sal_user
setgid www-data
chdir /usr/local/sal_install/sal

exec /usr/local/sal_install/sal_env/bin/gunicorn --workers 3 -b 127.0.0.1:8000 sal.wsgi:application

The web server: nginx

It is recommended that if you're setting up from scratch, you should use nginx. Only use Apache if you are integrating with an existing install. This config will only set you up to use HTTP. It is recommended you get set up with SSL though - Digital Ocean has a great tutorial on that. This is assuming your server has the hostname sal.example.com.

$ sudo apt-get install nginx

And let's configure nginx.

$ sudo nano /etc/nginx/sites-available/sal.conf

And make it look like:

server {
    listen 80;
    server_name sal.example.com;

    location = /favicon.ico { access_log off; log_not_found off; }

    location /static/ {
        alias /usr/local/sal_install/sal/static/;
    }

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header X-Forwarded-Host $server_name;
        proxy_set_header Host $http_host;
        proxy_redirect off;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        add_header P3P 'CP="ALL DSP COR PSAa PSDa OUR NOR ONL UNI COM NAV"';
        port_in_redirect off;
        proxy_connect_timeout  300s;
        proxy_send_timeout  600s;
        proxy_read_timeout  600s;
    }
}

If Sal is the only app running on this server, you could make the section just inside the server block look like:

server {
    listen       80  default_server;
    server_name  _;
    # More things down here...

Now finally we need to activate the nginx configuration:

$ ln -s /etc/nginx/sites-available/sal.conf /etc/nginx/sites-enabled/sal.conf

Now to start the services:

$ service gunicorn restart
$ service nginx restart

Finally, we need to set up the task in cron to perform the search maintenance. Assuming you haven't changed any paths, you can just use the script in setup/search_maint.sh - if you have, you will need to update the paths to reflect what you have changed them to.

sudo contab -e

And add in:

*/5 * * * * sal_user /usr/local/sal_install/sal/setup/search_maint.sh > /dev/null 2>&1

Nginx with SSL (Let's Encrypt)

An example configuration file for Nginx with Letsencrypt could look something like this:

Where sal.example.com is the FQDN (/website address) of your site.

server {
  listen 80;
  server_name _;

  location / {
    return 301 https://$server_name$request_uri;
  }
}

server {
  server_name _;

  listen 443 ssl http2 default_server;
  listen [::]:443 ssl http2 default_server;

  ssl_certificate /etc/letsencrypt/live/sal.example.com/fullchain.pem;
  ssl_certificate_key /etc/letsencrypt/live/sal.example.com/privkey.pem;
  
  ssl_stapling on;
  ssl_stapling_verify on;
  ssl_trusted_certificate /etc/letsencrypt/live/sal.example.com/chain.pem;
  resolver 8.8.8.8 8.8.4.4 valid=300s;
  resolver_timeout 5s;

  location /.well-known/acme-challenge {
    root /var/www/letsencrypt;
  }

  location /static/ {
      alias /usr/local/sal_install/sal/static/;
  }

  location / {
      proxy_pass http://127.0.0.1:8000;
      proxy_set_header X-Forwarded-Host $server_name;
      proxy_set_header Host $http_host;
      proxy_redirect off;
      proxy_set_header X-Real-IP $remote_addr;
      proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
      add_header P3P 'CP="ALL DSP COR PSAa PSDa OUR NOR ONL UNI COM NAV"';
      port_in_redirect off;
      proxy_connect_timeout  300s;
      proxy_send_timeout  600s;
      proxy_read_timeout  600s;
  }
}

Updating Sal

Updating to the latest version of Sal follows almost all of the parts under the 'Setting up Python' section.

Start by elevating to root, and switching to the sal_user:

sudo -i
su - sal_user

Change to the sal_install directory

cd /usr/local/sal_install/

Activate the sal_env

source sal_env/bin/activate

Ensure you are in the sal/ directory

cd sal/

Run Git pull to get the latest code

git pull https://github.com/salopensource/sal.git

Migrate the database to enable new columns

cd /usr/local/sal_install/sal
source ../sal_env/bin/activate
python manage.py migrate

Refresh Sal in your browser and check that the version has changed.