diff --git a/README.md b/README.md index d553275..2e006bc 100644 --- a/README.md +++ b/README.md @@ -10,41 +10,39 @@ We use static variables combine these to create unique ports for each container: `PREFIX` is always defined as 2 and is found in the [.env](.env) file as `PORT_PREFIX=2`. This is needed in order for the full port to be on the form 2XXXX, to avoid crashing with established ports. -`GROUP_ID` is defined by your group number on BlackBoard, found in the [.env](.env) file as `GROUP_ID=XX`. This is always 2 numbers, so groups 1-9 have leading zeros, i.e., group 3 has `GROUP_ID=03`. - +`GROUP_ID` is defined by your group number on BlackBoard, found in the [.env](.env) file as `GROUP_ID=XX`. This is always 2 numbers, so groups 1-9 have leading zeros, i.e., group 3 has `GROUP_ID=03`. `STAGE` is defined as: + - development: 1 - staging: 2 - production: 3 - -The related variables can be found in the [.env](.env) file as `DEV_POSTFIX=1`, `STAG_POSTFIX=2`, and `PROD_POSTFIX=3`. + +The related variables can be found in the [.env](.env) file as `DEV_POSTFIX=1`, `STAG_POSTFIX=2`, and `PROD_POSTFIX=3`. `CONTAINER_ID` is defined as: + - backend: 4 - frontend: 5 - gateway: 6 - -The related variables can be found in the [.env](.env) file as `BACKEND_POSTFIX=4`, `FRONTEND_POSTFIX=5`, and `GATEWAY_POSTFIX=6`. +The related variables can be found in the [.env](.env) file as `BACKEND_POSTFIX=4`, `FRONTEND_POSTFIX=5`, and `GATEWAY_POSTFIX=6`. -The *ports* section of each compose file ([docker-compose.dev.yml](docker-compose.dev.yml), [docker-compose.stag.yml](docker-compose.stag.yml), and [docker-compose.yml](docker-compose.yml)) define which images are accessible from outside the isolated Docker network. Currently, all images are available in development and staging, while only the gateway is available in production. +The _ports_ section of each compose file ([docker-compose.dev.yml](docker-compose.dev.yml), [docker-compose.stag.yml](docker-compose.stag.yml), and [docker-compose.yml](docker-compose.yml)) define which images are accessible from outside the isolated Docker network. Currently, all images are available in development and staging, while only the gateway is available in production. -To make ports available from outside the server, you'll need to either modify firewall/routing on the server or (as we have elected to do for this project) use a backward proxy. This is defined through the [./nginx_template.txt](./nginx_template.txt) file, which, when used with the ```$ envsubst < nginx_template.txt``` command, replaces the variables with the environment variables set by the [.env](.env) file (how to do this properly is left as part of task 1 in exercise 2). +To make ports available from outside the server, you'll need to either modify firewall/routing on the server or (as we have elected to do for this project) use a backward proxy. This is defined through the [./nginx_template.txt](./nginx_template.txt) file, which, when used with the `$ envsubst < nginx_template.txt` command, replaces the variables with the environment variables set by the [.env](.env) file (how to do this properly is left as part of task 1 in exercise 2). The default setup to make the application available from the outside is to listen on ports `PREFIX + GROUP_ID + STAGE + 7` (and port 80 for production), mapping to their related gateways `PREFIX + GROUP_ID + STAGE + 6`. -One note on this is to make sure the ```proxy_set_header Host $http_host;``` is set with `$http_host` and not `$host` (as it normally is) in order to forward the port being used (otherwise, it assumes port 80 based on the default HTTP protocol). - +One note on this is to make sure the `proxy_set_header Host $http_host;` is set with `$http_host` and not `$host` (as it normally is) in order to forward the port being used (otherwise, it assumes port 80 based on the default HTTP protocol). ### Port examples -| **Group Number** | **Stage** | **Image** | **Port** | -| :---: | :---: | :---: | :---: | -| 04 | development | backend | 20414 | -| 21 | staging | gateway | 22126 | -| 00 | production | frontend | NA (not available) | - +| **Group Number** | **Stage** | **Image** | **Port** | +| :--------------: | :---------: | :-------: | :----------------: | +| 04 | development | backend | 20414 | +| 21 | staging | gateway | 22126 | +| 00 | production | frontend | NA (not available) | ## Deploy with Docker @@ -58,6 +56,7 @@ Windows hosts must use Education or more advanced versions to run Docker \ Download: [https://innsida.ntnu.no/wiki/-/wiki/English/Microsoft+Windows+10](https://innsida.ntnu.no/wiki/-/wiki/English/Microsoft+Windows+10) ### Install: + In your github, fork this repository ([https://git.ntnu.no/mathialm/secfit](https://git.ntnu.no/mathialm/secfit)) ```console @@ -67,35 +66,38 @@ $ cd secfit ### Run: -In this project, we have three docker-compose files you can use to set up the containers. +In this project, we have three docker-compose files you can use to set up the containers. -`docker-compose.dev.yml` is used to make the backend, frontend, and gateway containers with all ports open. These are intended to be used as development containers (i.e., enabling CI/CD and updating as code is pushed). +`docker-compose.dev.yml` is used to make the backend, frontend, and gateway containers with all ports open. These are intended to be used as development containers (i.e., enabling CI/CD and updating as code is pushed). `docker-compose.stag.yml` is used to make the backend with a different configuration (in [./backend/tests/Dockerfile.test](./backend/tests/Dockerfile.test)). This is intended to be used for testing your code and should only run when tests are run. You can expand this to also set up the frontend and gateway if implemented tests require it. `docker-compose.yml` is used to make the backend, frontend, and gateway containers, with only the ports on the gateway open. These are intended to be used as production containers and should, as such, ensure persistent volumes and proper migration where needed. Verify compose configuration file: + ```console $ docker compose -f --verbose config ``` Build and run containers defined in configuration file + ```console $ docker-compose -f up --build -d ``` ## Using GitHub actions + Managing GitHub actions is done from your repository's `Actions` tab. -From here, you can add, modify, and read the logs from all workflows. +From here, you can add, modify, and read the logs from all workflows. The workflow files are stored in the [.github/workflows/](.github/workflows/) folder. Documentation and tutorials for GitHub Actions can be found at [https://docs.github.com/en/actions](https://docs.github.com/en/actions) - ## Technology + - **deployment** - Docker/Docker Compose/GitHub actions - **web** - Nginx - **database** - SQLite 3 @@ -103,7 +105,6 @@ Documentation and tutorials for GitHub Actions can be found at [https://docs.git - **frontend** - HTML5/CSS/JS, React 4 - **authentication** - JWT - ## Backend code and structure - **secfit/** django project folder containing the project modules @@ -111,7 +112,7 @@ Documentation and tutorials for GitHub Actions can be found at [https://docs.git - **migrations/** - directory containing django migrations enabling _mostly_ automatic modifications to your data models, see [https://docs.djangoproject.com/en/5.1/topics/migrations/](https://docs.djangoproject.com/en/5.1/topics/migrations/) - **admin.py** - file containing definitions to connect models to the Django admin panel - **apps.py** - defined the application for this directory - - **forms.py** - definitions of forms. Used to render html forms and verify user input + - **forms.py** - definitions of forms. Used to render html forms and verify user input - **models.py** - contains data models - **parsers.py** - contains custom parsers for parsing the body of HTTP requests - **permissions.py** - contains custom permissions that govern access @@ -130,14 +131,13 @@ Documentation and tutorials for GitHub Actions can be found at [https://docs.git - **manage.py** - entry point for running the project. - **requirements.txt** - Python requirements - ## Local setup + It's recommended to have a look at: https://www.djangoproject.com/start/ Just as important is the Django REST guide: https://www.django-rest-framework.org/ Create a virtualenv https://docs.python-guide.org/dev/virtualenvs/ - ### Django Installation with examples for Ubuntu. Windows and OSX is mostly the same @@ -145,8 +145,8 @@ Installation with examples for Ubuntu. Windows and OSX is mostly the same Fork the project and clone it to your machine. #### Setup and activation of virtualenv (env that prevents python packages from being installed globally on the machine) -Navigate into the project folder, and create your own virtual environment +Navigate into the project folder, and create your own virtual environment #### Install python requirements @@ -170,14 +170,12 @@ $ python manage.py createsuperuser Only username and password is required - #### Start the app ```console $ python manage.py runserver ``` - #### Add initial data You can add initial data by going to the URL the app runs on locally and adding `/admin` to the URL. @@ -185,7 +183,9 @@ You can add initial data by going to the URL the app runs on locally and adding Add some categories and you should be all set. ## Assumptions + The file .env would normally not be uploaded together with the code since that is bad practice allowing for sensitive data exposure. The file is however essential to run the application, and needs to stay where it is. If any other secret values needs to be stored 'outside' the code repository, this is where it should be put. If you use a different file, it should still be added to the repository, but you should state it here as an assumption. +## An update triggering workflow -## Making a change to check if whenever the code is updated, it is deployed on the server +Let's update this file :)