142 lines
7.0 KiB
Markdown
142 lines
7.0 KiB
Markdown
# 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:
|
|
```shell
|
|
./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:
|
|
```shell
|
|
sudo apt-get install python3.9-dev
|
|
```
|
|
|
|
Otherwise after that script is run you can jump to [Building the Docker Images](#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](https://docs.docker.com/engine/install/ubuntu/)
|
|
|
|
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:
|
|
```shell
|
|
# 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):
|
|
```shell
|
|
./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](https://docs.docker.com/compose/compose-file/compose-file-v3/).
|
|
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:
|
|
```shell
|
|
./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:
|
|
```shell
|
|
./build.sh
|
|
```
|
|
There is an optional argument that can be included if the docker-compose file needs to be re-rendered:
|
|
```shell
|
|
./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-install`Runs 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:
|
|
```shell
|
|
./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:
|
|
```shell
|
|
./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:
|
|
```shell
|
|
./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
|
|
```shell
|
|
./start.sh
|
|
```
|
|
- Changes are made to the frontend code
|
|
- Rebuild the frontend webpack
|
|
```shell
|
|
./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](https://github.com/QuarterHomes/Quarterforms) 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:
|
|
```shell
|
|
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:
|
|
```shell
|
|
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](https://www.atlassian.com/git/tutorials/git-submodule).
|