ApplicantPortal/readme.md

Quarter Application Backend

Development Machine Setup

There is a helper script that can be run on the inital clone of this repo that will automate several of the instructions below, it is run with:

./scripts/initial_setup.sh

If that script fails to build the python virtual environments, ensure that python3.9-dev is installed on you machine, it can be installed with:

sudo apt-get install python3.9-dev

Otherwise after that script is run you can jump to Building the Docker Images.

Install Pre-requisites

This web app uses several tools to run:

• docker
• docker-compose
• python3.9

Docker can be installed by following the instructions on docker's website

As this application uses python 3.9, that must also be installed along with the python development tools

Set up the python virtual environments

This application makes use of python virtual environment, and all the scripts associated with it expect that you are running in the pyton virtual environment so these must also be set up:

# install the python virutalenv module (only needs to be done if you have not already installed the virtualenv package)
python3.9 -m pip install virtualenv
# create a python virutalenv
python3.9 -m virtualenv venv
# activate the python virtual environment
source venv/bin/activate
# install the requirements
pip install -Ur requirements.txt

NOTE:

• Whenever the reuirements.txt file is updated, the virutal environment must also be updated by running pip install -Ur requirements.txt from within the virtual environment.
• All the scripts in this repo are dependant on this virtual environment, so you must activate the virtual environment before trying to run any of them.

Creating the docker-compose environment file

Docker compose uses an environment file which holds environment specific values that needs to be created, there is a helper script for creating this environment file (like all scripts this must be run from the previously created venv):

./docker/bin/create_env.py

Rendering the docker-compose.yaml file

This app is run inside several docker containers, which simplifies both the initial environment set up and deployment of the application, this is dictated by a docker-compose file. Since this file contains several variables that are machine-specific, instead a "template" file is stored in the git repository as well a script which will "render" this template.

To render this template you must run:

./docker/bin/render_docker_templates.sh

Once those templates have been rendered, you can build the docker images

Building the Docker Images

In order to build the docker images that this app uses, there is a helper script you need to run:

./build.sh

There is an optional argument that can be included if the docker-compose file needs to be re-rendered:

./build.sh --render-templates

This script will build the docker images, and does not to be run for every code change that is made, instead it needs to be run if:

• The requirements.txt file is updated.
• Any changes are made to the dockerfiles which define these images.

In order to start these containers after they have been built, there is another helper script (./srart.sh) that is used to start containers from the docker images. This script has two optional arguments that can be included:

• -b|--build-webpack Builds the frontend webpack from the UI submodule (this is required if the UI submodule has been updated).
• -i|--npm-installRuns an npm install on the webpack in the UI submodule (only works if the --build-webpack flag is included, is only required if the requirements for the frontend webpack have been updated).

For the initial startup of the docker containers, both flags must be included:

./start.sh --build-webpack --npm-install

NOTE: It is not required to stop and start the docker conatiners for front-end only changes (changes to either the frontend webpack code in the UI submodule, or the flask template/static files). All that is required is

However after that these flags should only be included if the frontend submodule code has been changed.

There is also a helper script for stopping the containers (./stop.sh).

The final helper script is to restart all the containers for the application (./restart.sh), this it is required to restart the containers whenever there is a change to the code, but it is not required to do so for changes to the html templates or the frontend webpack (though this webpack does need to be rebuilt).

Building the Frontend Webpack

As mentioned above the frontend code is a submodule of this repository, when making changes to the frontend, there is a helper script that will build the webpack with the appropriate arguments:

./scripts/build_frontend_webpack.sh

This script does not by default install any npm packages that the frontend needs, if that is required (either on the first build or if the npm package requirements have changed) it can be run with the --npm-install flag:

./scripts/build_frontend_webpack.sh --npm-install

After building the frontend webpack, the new website will be viewable at /apply/home, it is NOT required to restart the docker containers to update this page, however you will need to refresh the page (possibly more than once) to view the new page. An example of this would be:

• Start the docker containers once

  ./start.sh
  

• Changes are made to the frontend code
• Rebuild the frontend webpack

  ./scripts/build_frontend_webpack.sh
  

• navigating to http://localhost/apply/home will not display the new webpack.

Note that the docker containers are never stopped in the above example since the compiled webpack is treated as "tempalte files" by the flask web app.

Using git submodules

This repository uses git submodules for the frontend components, these components are held in a separate git repository which is set up as a submodule in the UI folder.

Updating the Submodules

When you checkout or pull this repository, it is important to also make sure you are updating the submodules it has, this can be done with the following command:

git submodule update --init

NOTE: The --init flag is only required if the submodule directory (UI) is empty.

When a change is made to the code in the UI repository, and it needs to be included in this repository, you must commit the updated submodule. This is the same as adding/committing a file:

cd UI
# update to the latest "main" branch in the repository to include new changes
git pull
cd ..
# add and commit the new frontend code
git add UI/
git commit -m "Update the frontend"

For more information about submodules, see this article.