RHEL 7

Red Hat Enterprise Linux 7

These instructions were written for RHEL 7. In theory, this should also work fine for CentOS 7 as well, but has not been tested.

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

The plan

We're running Sal using the Gunicorn server, which is a server designed to run Python apps. We will be using Apache as our web server, due to the official support from Red Hat in an enterprise environment. We'll also setup PostgreSQL as the database for Sal.

Prerequisites

First, we bring everything up-to-date. Log on to the server, switch to root and use yum to perform the installs:

$ sudo su - root
# yum update

Then install Python, PostgreSQL, OpenSSL, Git and Apache. Ensuring the 'apache' group exists beforehand.

# groupadd -o -g 48 -r apache
# yum install python-devel postgresql-libs postgresql-devel postgresql-server postgresql-contrib libffi-devel git httpd-devel httpd openssl-devel mod_ssl

Ensure the apache group has the same GID as the apache user:

# test "$(id -ng apache)" != "apache" && groupdel apache && groupadd -o -g $(id -g apache) -r apache

Configure PostgreSQL

Now, we setup the database and the user that Sal will connect to it with.

First, we'll create a new PostgreSQL database cluster:

# systemctl enable postgresql
# postgresql-setup initdb

By default, PostgreSQL does not allow password authentication. To fix that, we'll need to modify the host-based authentication (HBA) configuration. First, backup the file (as any good sysadmin knows):

# cp /var/lib/pgsql/data/pg_hba.conf /var/lib/pgsql/data/pg_hba.conf.backup[todays_date]

Then open the file with your favorite text editor:

# vim /var/lib/pgsql/data/pg_hba.conf

Go to the bottom of the file and find the lines that look like this:

host 	all 	all 	127.0.0.1/32	ident
host 	all 	all 	::1/128			ident

and then replace "ident" with "md5", so the lines look like this:

host 	all 	all 	127.0.0.1/32	md5
host 	all 	all 	::1/128			md5

Save the file and then exit. PostgreSQL is now configured to use password authentication. All we have to do now is start PostgreSQL.

# systemctl start postgresql

Create the database and user

Now, we need to setup the database and user that Sal will connect with. First, we need to switch to the postgres user and log in to PostgreSQL:

# su - postgres
$ psql

Now, we can create the database:

CREATE DATABASE saldb;

Once that is complete, you can chose your own username and password. (Tip: Feel free to use the apg package to generate your passwords, and then have KeyPass store those passwords.)

CREATE USER sal_admin WITH PASSWORD 'sal_password';

Lastly, give them permissions, then quit the database and exit out of the postgres user:

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

Setup Python environment

Now, we'll setup the virtual environment for python to run. First, we'll use pip to upgrade pip.

# easy_install pip
# pip install --upgrade pip

Then we'll install virtualenv.

# pip install virtualenv

Now, we need to setup the service user, as it's not a good idea to run services from root.

# useradd -m -d /srv/saluser -c "Sal User" saluser
# usermod -L saluser

This will add the saluser with with the home directory /srv/saluser. We then run usermod -L saluser to lock the account. This effectively disables passwords on the account. (NOTE: Filesystem Hierarchy Standards states that /srv/ is used for data services provided by the system)

Now, we log in as the saluser and to finish setting up the environment.

# su - saluser
# cd ~

Then, we log in and create the virtualenv and activate it:

$ virtualenv sal_env
$ cd sal_env
$ source bin/activate

Now, we'll use git to download the latest release of Sal (please refer to the releases section for the lastest version number).

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

Next, we need to install Sal's dependencies:

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

Finally, we have to modify the environmental variable SAL_ENV_DIR. Open sal.wsgi

$ cp sal.wsgi sal.wsgi.backup[todays_date]
$ vim sal.wsgi

And then find and modify this line:

SAL_ENV_DIR = '/srv/saluser/sal_env'

Customize Sal

We can now make our customizations to Sal. First, We have to copy the default settings file and then open it in your text editor of choice. Make sure you are still logged in to the virtualenv. (You should still see (sal_env) in front of the bash prompt).

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

Locate the database configuration section and add your settings.

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

After you configure settings.py to your specifications, you can populate the database.

$ python2.7 manage.py migrate
$ python2.7 manage.py collectstatic

And then create the admin user (NOTE: Remember these credentials; you'll need them later):

$ python2.7 manage.py createsuperuser

You can now log out of the sal_env virtual environment

$ deactivate
$ exit

Gunicorn

As stated previously, gunicorn is used to run the app behind the web server. Since we're using RHEL/CentOS 7, we'll need to create a systemd unit to allow gunicorn to start automatically. Make sure you're logged on as root and navigate to:

# cd /etc/systemd/system

Next create the new gunicorn service and change the file mode bits:

# touch gunicorn.service
# chmod 755 gunicorn.service

Then, open the file with your favorite text editor (again, we'll use vim):

# vim gunicorn.service

And make it look as follows. Please change your workers for the number of cores in your server + 1 (e.g. 3 workers for a dual core server):

[Unit]
Description=Gunicorn
After=httpd.service
Requires=httpd.service

[Service]
User=saluser
Group=apache
WorkingDirectory=/srv/saluser/sal_env/sal
TimeoutStartSec=0
ExecStart=/srv/saluser/sal_env/bin/gunicorn --workers 2 -b 127.0.0.1:8000 sal.wsgi:application
ExecStop=/bin/kill -15 $MAINPID

[Install]
WantedBy=multi-user.target

Whenever you create a new unit file, you need to reload the systemd service:

# systemctl daemon-reload

Then you can enable and start the new service:

# systemctl enable gunicorn
# systemctl start gunicorn

The web server: Apache/httpd

Most enterprise environments prefer to run Apache, especially with RHEL systems. So, I'll go ahead and show you how we configured it here.

First, you'll need to enable Apache and start the service:

# systemctl enable httpd
# systemctl start httpd

Next, you need to make sure that the proper ports are open on the firewall:

# firewall-cmd --permanent --add-port=80/tcp
# firewall-cmd --permanent --add-port=443/tcp

And then reload the firewall:

# firewall-cmd --reload

Now, it's time to configure the Apache conf files.

# cd /etc/httpd/conf
# cp httpd.conf httpd.conf.backup[todays_date]
# vim httpd.conf

And modify this line to suite your needs. We will assume that your server hostname is sal.example.com:

ServerName sal.example.com:80

And then comment out the following line:

# Options Indexes FollowSymLinks

As per the original installation instructions, it is recommended to run Sal over SSL. You can follow the tutorial on Digital Ocean for a great tutorial on creating and requesting SSL Certificates.

Now, create the sal.conf file:

# cd ../conf.d/
# touch sal.conf

Non-SSL

If you choose not to use SSL, then input the following in sal.conf:

<VirtualHost *:80>
	ServerName sal.example.com
	Alias /static /srv/saluser/sal_env/sal/static
    <Directory /srv/saluser/sal_env/sal/static/>
        Require all granted
    </Directory>

    ProxyRequests Off
    ProxyPreserveHost On

    <Location />
        ProxyPass http://localhost:8000/
        ProxyPassReverse http://localhost:8000/
        Require all granted
    </Location>

    <Location /static>
        ProxyPass "!"
    </Location>
</VirtualHost>

SSL

If you plan on using SSL, then input the following in sal.conf:

<VirtualHost *:80>
	ServerName sal.example.com
	RewriteEngine On
	RewriteCond %{HTTPS} off
	RewriteRule (.*) https://%{HTTP_HOST}%{REQUEST_URI}
</VirtualHost>

Next, make a backup of the original ssl.conf file:

# cp ssl.conf ssl.conf.backup[todays_date]

And make it look as follows. I've removed all the commented lines for ease of reading for this documentation:

Listen 443 https

SSLPassPhraseDialog exec:/usr/libexec/httpd-ssl-pass-dialog
SSLSessionCache         shmcb:/run/httpd/sslcache(512000)
SSLSessionCacheTimeout  300
SSLRandomSeed startup file:/dev/urandom  256
SSLRandomSeed connect builtin
SSLCryptoDevice builtin

<VirtualHost [server_ip_address]:443>
	ErrorLog logs/ssl_error_log
	TransferLog logs/ssl_access_log
	LogLevel warn

	SSLEngine on
	SSLProtocol all -SSLv2
	SSLCipherSuite HIGH:MEDIUM:!aNULL:!MD5:!SEED:!IDEA
	SSLCertificateFile /path/to/cert/file.crt
	SSLCertificateKeyFile /path/to/cert/key/file.key
	SSLCACertificateFile /path/to/ca/cert/file.crt

	<Files ~ "\.(cgi|shtml|phtml|php3?)$">
		SSLOptions +StdEnvVars
	</Files>

	<Directory "/var/www/cgi-bin">
		SSLOptions +StdEnvVars
	</Directory>

	BrowserMatch "MSIE [2-5]" \
         nokeepalive ssl-unclean-shutdown \
         downgrade-1.0 force-response-1.0
	CustomLog logs/ssl_request_log \
          "%t %h %{SSL_PROTOCOL}x %{SSL_CIPHER}x \"%r\" %b"
	ServerName sal.example.com
	Alias /static/ /srv/saluser/sal_env/sal/static/

	<Directory /srv/saluser/sal_env/sal/static/>
		Require all granted
	</Directory>

	ProxyRequests Off
	ProxyPreserveHost On

	<Location />
		ProxyPass http://localhost:8000/
		ProxyPassReverse http://localhost:8000/
		Require all granted
	</Location>

	<Location /static>
		ProxyPass "!"
	</Location>
</VirtualHost>

Finishing up

Finally, grant all permissions on the saluser directory so that apache can read and execute from the root of that directory

# chmod -R 755 /srv/saluser
# systemctl reload httpd

Once that is complete, you should be able to go to http://sal.example.com.

If you configured SSL, you will be redirected to https://sal.example.com.

Log in using the credentials you created when you ran the createsuperuser python script.