Web UI

The Purpose of the UKRDC Web User Interface is to be able to interact with the UKRDC database's depending which instance of the Web UI you are accessing (live, staging or dev). You can interact with Work Items, view file loading errors and view patient data.

Please read UKRDC-Web-User-Interface for more information about interacting with the User Interface.

Code design and Description

The application is split into two parts:

The Server side code:
- Repository: User-API
- Python django app, using django rest framework. There is only one special thing about it is that we add ukrdc_session and jtrace_session to request object. Both of them commit/rollback after request is finished. UKRDC3 and JTRACE settings are defined in the settings module and appropriate environment file (staging.py for staging, development.py for dev, etc.)
The Client side code:
- Repository: User-Client
- Angular app. Having several modules - viewer, errorbrowser, Workitems module is in the main app, but should be split into separate module.

TODO: Expand on how the both code bases work.

Deployment for Production/Testing

Deploying the complete UKRDC UI web app requires both the user-client code and the user-api code please see below diagram:

Both Gunicorn and NGINX are programs that when run on a server do the serving for websites, web applications and other web/network based services.

For the deployment of the UKRDC UI application Gunicorn serves the back end locally through port 9400, whilst NGINX acts as a Reverse Proxy for the back end, routing traffic through it and providing other services i.e. security features.

The user interacts with the application through the front end (the user-client code) which has to be compiled and is served from the /var/www/app directory on the server by NGINX. In contrast the back end code (the user-api code) does not need compiling and can be run with the correct dependencies, with Gunicorn, straight from a cloned version of it's BitBucket repository.

Deploying the Front End

Prerequisites:

Access to the User-Client and User-Api BitBucket repositories.
Node installed.
Angular CLI installed.
Python 3.6
Python 3.6 Virtual Environment
NGINX setup and running on server.

You will need to clone the user-client BitBucket repository, once this is done there is a bash script called "build.sh" this calls the Angular CLI to do a production build of the code, this can be run or simply type into the command line:

Build User-Client

ng build --base-href /app/ --prod

This will create an "app" directory in the "dist" folder of your cloned repository.

If you change into this directory open the "Index.html" file and check in the "<head>" section that the "href" attribute of the "<base>" element shows the path "/app/" :

Index.html

<base href="/app/">

This tells the browser where the other files are located in order to run correctly, the application will fail to load in the browser if it does not reference the folder the rest of the compiled code is in, and you may get error messages in the console e.g. A permission error as you do not have permission to access the location.

Once this is done change directory into the /var/www folder on the server you are deploying it too and if there is already an "app" folder rename it and copy/move your newly built "app" folder into it, that should be all that is required as NGINX will automatically serve the contents of this folder.

To check open a browser and type in the correct URL relating to the server you deployed to and you should see your front end, just to note depending on your changes you may get errors in the console if you need have altered the back end code too.

----

Deploying the Back End

Deploying the User-Api code is slightly more long winded but not much, usually NGINX will already be setup and running if not please setup and start NGINX.

If you log into the target server, in "/home/ukrdc" you will find a directory called "ukrdc-user-api" this is a cloned user-api Bit-bucket repository.

Git should already be installed on the system and you should have committed your changes to the repository and so a pull from master or checkout a branch (if you cannot find the branch try "git fetch") should update the local repository with your changes.

Make sure you have merged your branch with master if your deploying to staging or production as your branch should be a production candidate (deploying to staging) or fully tested and ready for production (deploying to production).

Once your local repository is up to date activate your python virtual environment make sure all the dependencies are installed by using pip and the "requirements.txt" file:

Install Dependencies with Pip

pip install -r requirements.txt

In order for this to work you need to be in the same folder as the file or include the path:

Include path

pip install -r /home/ukrdc/ukrdc-user-api/requirements.txt

If this is not done you will have "ModuleNotFound" errors which means the python interpreter cannot find the library that the code is trying to import in any of it's search path directories.

In the repo there should be a "run.pid" file with the current process ID in, you will need to kill that process if sending it a "HUP" signal will not load your changes:

kill hup

kill -HUP `cat run.pid`

In order to see if this has worked you can type:

ps aux

ps `cat run.pid`

Which will look in the "run.pid" file for the process ID and return details of the process:

ps

 PID TTY      STAT   TIME COMMAND
 4953 ?        S     11:17 /home/ukrdc/ukrdc-user-api/venv/bin/python3 venv/bin/gunicorn userapi.wsgi -b 127.0.0.1:9400 --name ukrdc_userapi --workers 2 --daemon --log-level=info --log-file=logs/gunicorn.log --access-logfile=logs/access.

This lets you know that everything is running properly, keep an eye on the "TIME" column as it should be the start time and will let you know whether it has restarted successfully.

If not get the process ID from the "run.pid" file and kill the process:

kill process

kill `cat run.pid`

Running "ps" again with the process ID will let you know the whether it has been killed.

Then all that needs to be done is run the "/bin/gunicorn-start.sh" script:

gunicorn-start.sh

#!/bin/bash

set -euo pipefail
IFS=$'\n\t'

if [ -z "${DJANGO_SETTINGS_MODULE:-}" ]
then
  echo "[ERROR] \$DJANGO_SETTINGS_MODULE variable is not set." >&2;
  echo "[ERROR] It needs to be set manually, e.g.:" >&2;
  echo "[ERROR] export DJANGO_SETTINGS_MODULE=userapi.settings.development" >&2;
  exit 4;
fi

logs_dir=logs;

if [ ! -e ${logs_dir} ]; then
    mkdir "${logs_dir}";
fi

venv/bin/gunicorn userapi.wsgi \
    -b 127.0.0.1:9400  \
    --name ukrdc_userapi \
    --workers 2 \
    --daemon \
    --log-level=info \
    --log-file=${logs_dir}/gunicorn.log \
    --access-logfile=${logs_dir}/access.log \
    --error-logfile=${logs_dir}/error.log \
    --timeout 300 \
    -p run.pid

This sets the "pipefail" option so the scripts returns the correct exit code if something fails as well as setting the Internal Field Separator "IFS". Once it has carried out these setup steps it checks to see if the "DJANGO_SETTINGS_MODULE" environment variable is set if not it exits. Then it checks whether the "logs" directory exists (which will be in the current working directory) if not it creates it and then it runs Gunicorn with the code in the "userapi/wsgi.py" file.

Running this script should give a new process ID in the "run.pid" file and doing the same process as we carried out above to check whether the process has worked will tell you whether it has worked this time.

After everything is deployed make sure you open a browser and make sure everything is accessible and is running smoothly.