Deployment Guide

Deployment Guide

Application Architecture

Server Configuration

Database Server

The database must be Postgres 9.6+

If the database is running on a separate machine from the application server, the following actions are necessary to allow the application server to connect to the database:

• Update pg_hba.conf to allow md5 authentication from the API server
• Update postgresql.conf configuration to allow access via your desired port from the API server
• (SELinux) Allow your desired port access via the firewall
  • firewall-cmd --zone=public --add-port=PORT/tcp --permanent
  • firewall-cmd --reload

Application Server

(SELinux) Open Ports

If you are using an SELinux distribution, you must open ports you wish to listen on in the firewall. For each port, perform the following:

• firewall-cmd --zone=public --add-port=PORT/tcp --permanent
• firewall-cmd --reload

API Software Requirements

The following software is required to run the API layer on an application server

• Apache
  • mod_wsgi
• xmlsec1
• Python 3.6+
  • For SSL support
    • Ensure OS has SSL development packages (e.g. openssl-devel for RHEL)
    • Compile Python with configure --enable-shared

Create Virtual Environment

To install virtualenv, simply execute the following command:

pip install virtualenv

After virtualenv has been successfully installed, we can now make a virtual environment for the project. It can be located anywhere on the system, but it is generally recommended to place it alongside the project code for ease of location.

Locating Python 3.6

First, we need to determine the location of our Python 3.6 installation. Execute the following command to determine the location of the python executable. (If the shell command python is already aliased to Python 3.6, you can skip this step)

which python3.6

If python 3.6 is properly installed, this will return a path to the executable.

Creating the environment

The following command will create a virtual environment:

virtualenv -p <path to python 3.6> <desired location of the virtual environment>

If the python alias points to python 3.6, then the -p argument is optional. Examples:

virtualenv -p /usr/bin/python3.6 ~/Projects/talentmap-env

virtualenv ~/Projects/talentmap-env

Activating the Environment

To activate the environment in your terminal, execute the following command:

source ~/Projects/talentmap-env/bin/activate

If successful, the terminal prompt change to denote the active environment. To deactivate the environment, use the command deactivate.

Apache (API)

The following is an example of an API virtual host using wsgi

Listen 8000
<VirtualHost *:8000>
  ServerName XXX.XXX.XXX
 
  SSLEngine on
  SSLProtocol all +TLSv1.2
  SSLCertificateFile /path/to/cert.cer
  SSLCertificateKeyFile /path/to/key.key
 
  Alias /static /var/www/talentmap/api/talentmap_api/static 
 
  <Directory /var/www/talentmap/api/talentmap_api/static>
    Require all granted
  </Directory>
 
  <Directory /var/www/talentmap/api/talentmap_api>
    <Files wsgi.py>
      Require all granted
    </Files>
  </Directory>
 
  WSGIDaemonProcess talentmap_api python-path=/var/www/talentmap/api/talentmap_api python-home=/var/www/venv
  WSGIProcessGroup talentmap_api
  WSGIScriptAlias / /var/www/talentmap/api/talentmap_api/wsgi.py
  WSGIPassAuthorization On
 
</VirtualHost>

Apache

ProxyPass is used to relay requests from Apache to the Node application running in the background. Below is a sample configuration.

<VirtualHost *:80>
 ServerName www.application-server.gov
 DocumentRoot /var/www/html
 ProxyRequests Off

 <Proxy *>
  Order deny,allow
  Allow from all
 </Proxy>

 <Location /talentmap/>
  ProxyPass http://localhost:3000/talentmap/
  ProxyPassReverse http://localhost:3000/talentmap/
 </Location>
</VirtualHost>

Application Deployment

API

To install a new or updated set of code, perform the following tasks.

Activate Environment

To activate your environment, perform the following steps:

• source /path/to/virtualenv/bin/activate/
• source setup_environment.sh

Update dependencies

Execute pip install -r requirements.txt to install any new dependencies. This requires internet access; if that is unavailable, you will need to install the new dependencies from a tar or zip file directly into the virtual environment site-packages.

Perform migrations

Execute python manage.py migrate to perform database migrations

(Optional) Clear Database

If you are in a development or testing environment, you may wish to empty your database. To do this, execute python manage.py flush

Create base permissions

Create base permissions using python manage.py create_base_permissions

Restart HTTPD

If you are deployed via Apache, restart the HTTPD service

UI

The UI has two main deployment packages:

1 - static files - this is the index.html and assorted css, js and image files that make up the presentation layer. These are deployed under the normal Apache directory structure, ie, /var/www/html and generated via

source setup_environment.sh
node scripts/build.js

2 - node server - includes server.js, routes.js, saml2-config.js and node_modules

To start the node server

source setup_environment.sh
node /path/to/src/server.js

Application Configuration

API

Environment Variables

The API layer requires the configuration of multiple environment variables; this list is extensive and includes support for SAML based SSO, logging, and more. Please consult the full list

Logging

Please ensure the directory specified as the logging directory in setup_environment.sh has appropriate permissions for the apache user.

Recurring Synchronization of Data

Data can be pulled from SOAP web services described by the WSDL specified in setup_environment.sh. To automate this synchronization, use the following script with a cron job:

#!/bin/bash
source /path/to/virtualenvironment/bin/activate/
source /path/to/api/code/setup_environment.sh
cd /path/to/api/code/
python manage.py synchronize_data

UI

Environment Variables

The UI application requires the configuration of a multiple environment variables. These variables include:

• NODE_ENV - should be production
• PUBLIC_URL - the root directory under which the application runs
• STATIC_PATH - the path to static assets - css, js, images, etc
• LOGIN_MODE - basic or saml
• PORT - port number for Express web application, important in shared environments
• SAML configuration - necessary configuration to connect to SAML-based authentication
• Proxies - proxy HTTP routes for external services

An updated, running list is available here

Post-deployment checks

API

Ensure the API is accessible via the configured URL, and that data is returned when hitting an endpoint (such as /api/v1/position/)

UI

In a browser, connect to the front end via /login. Once the user is logged in ensure information in the profile - /profile/dashboard - is correct. Perform some basic searches to ensure proper API connection.