Update README.md (#127)

* Update README.md

* Update README.md again

* Update README.md

Author: Mr-Oregano

README.md

@@ -6,31 +6,34 @@ The portal is a public-facing website that allows students to submit a request f
 
 The recent loss of a previous tutoring portal is a major motivation for the development of this project. In addition, the transition to online classes and online tutoring has driven inspiration for some new features as well, such as marking tickets as online/on-campus depending on whether the student has been helped remotely or in person and auto-calculating the time spent on helping a student (which was previously manually provided by a tutor). These features will help in providing useful statistics about the kind of help students are requesting from the tutoring center and how often.
 
+Visit the [docs](https://claytonmsafranek.github.io/UNO-CSLC-Ticket-Portal/) for more info.
+
 ## Release Notes
 
-The application is currently a work in progress. The following is a list of currently existing features in the application:
+The following is a list of currently existing features in the application:
 
 - Form for submitting a ticket.
 - Page for viewing tickets.
 - Ability to claim/close tickets.
 - Editable tickets (can update most fields set for the ticket).
-- Front-end for administrative console. 
+- Administrative console backend for adding tutors, courses, configuring the portal app and downloading reports.
+- Tutor, Admin and Owner permissions (restrict views for authenticated users based on permission level).
 - A home page that asks to log in or shows username when logged in.
 - Login management; only authenticated users can view certain pages (Unauthenticated users will be redirected to Microsoft sign-in).
 - Automatically generated, self-signed SSL certificates for HTTPS connections
 
-Next Milestone [Milestone 5](https://github.com/claytonmsafranek/UNO-CSLC-Ticket-Portal/milestone/5) (still working on):
-
- - Creating automated unit tests for selenium.
- - Automatic deployment to Azure Dynamic Web Apps.
- - Administrative console backend for adding tutors, courses, configuring the portal app and downloading reports.
- - Tutor and Admin permissions (restrict views for authenticated users based on permission level).
-
-Visit the [docs](https://claytonmsafranek.github.io/UNO-CSLC-Ticket-Portal/) for more info.
+Next Milestone [Milestone 6](https://github.com/claytonmsafranek/UNO-CSLC-Ticket-Portal/milestone/6).
 
 ## Configuration
 
 ### Flask
+The program can be run locally for testing and development. The main file is `portal/app/__init__.py` which contains a definition for the `create_app()` factory function (flasks expect this and automatically calls the function). Before you can run the app, you need to install the dependencies via `pip install -r portal/requirements.txt` (assuming your current working directory is in the root folder of this project). This installs the core dependencies for the project, you can also install the development dependencies located in `portal/requirements/dev.txt` if you intend on running tests and linting. The following commands are one way to locally run the program:
+
+```
+export FLASK_APP=portal/app
+flask run --debug
+```
+
 The flask app (located in `portal/`) has a `default_config.py` script providing some default configuration for the project. *This does not need to be changed to configure the project*. If you would like to set additional options or override existing ones, then create a `.env` file in the `portal/` directory which sets the options to the desired values (prefixed with `FLASK_`).
 
 Example `portal/.env`:
@@ -43,16 +46,12 @@ FLASK_SECRET_KEY=my_secret
 
 These values will override any values specified in `default_config.py`.
 
-### Nginx
-The Nginx web server can be configured via its `nginx/nginx.conf` file. This configuration file is simply copied into the docker container which is generated by docker-compose and replaces the default configuration for Nginx.
-
-When using URLs or connections to applications in different containers make sure you provide the name of the container as the hostname. Example: `http://portal:8000` would connect to the application on port 8000 in the "portal" container using the HTTP scheme.
-
-### MySQL
-By default, the docker-compose file will auto-generate a docker MySQL image and set the `FLASK_SQLALCHEMY_DATABASE_URI` env variable (this will override any settings in `default_config.py` and in `portal/.env`). The MySQL database can be configured via its configuration file located in `mysql/mysql.cnf`, which will extend/override any default configurations existing in the MySQL image.
+Using flask debug mode is recommended for getting feedback on errors rather than HTTP internal server error status codes. The local flask app will use a local sqlite3 database (which should be created in `portal/instance/` at runtime). This should make it easy to ensure that the application is saving objects to the database correctly. The application needs to be configured with an *owner* account by setting the `FLASK_DEFAULT_OWNER_EMAIL` to a desired email environment variable in the `.env` file. **This is necessary in deployment and development for using the application as certain routes are restricted to higher permission levels only (of which owner is the highest)**. NOTE: You will need to configure Microsoft authentication to login, which is explained later.
 
-The Flask app will use the local MySQL docker database when running in production (via docker-compose). However, if you wish to use a custom remote MySQL server then you will need to change the `FLASK_SQLALCHEMY_DATABASE_URI` in the `docker-compose.yml` file to refer to that database. The default installed database connector is `PyMySQL`, if a different one is desired it will need to be installable via pip (so that docker can install it in the container), otherwise, this will require manual intervention from the user.
+#### Visual Studio Code
+Additionally, if you are using Visual Studio Code you can configure a `launch.json` and `settings.json` file for debugging and automatic linting. You can download and use the sample [launch.json](https://gist.github.com/Mr-Oregano/9873bebd7f8d871e36e5c5361b4bad9d) and [settings.json](https://gist.github.com/Mr-Oregano/388bbff7736d6fd7f166b697cb6ed48d) files and copy them into a `.vscode/` folder in the root directory of the project. *Make sure you have [flake8](https://pypi.org/project/flake8/) and [pytest](https://pypi.org/project/pytest/) installed!*. You can install these via `pip install -r portal/requirements/dev.txt`
 
+For other IDE/editors you are on your own in terms of setup.
 ### Microsoft Azure App Directory Authentication
 
 The application uses the Azure App Directory API for authentication and will need to be registered as a legitimate application in the app directory at https://portal.azure.com/. This requires some configuration on behalf of the user.
@@ -81,20 +80,20 @@ Subservices will exist inside isolated docker containers and will communicate wi
 
 Clients will interface with the application through a browser and an internet connection.
 
-### Local Development
-Running the program locally is recommended for testing and development rather than actual deployment. The main file is `portal/app/__init__.py` which contains a definition for the `create_app()` factory function (flasks expect this and automatically calls the function). The following commands are one way to locally run the program:
+### Nginx
+The Nginx web server can be configured via its `nginx/nginx.conf` file. This configuration file is simply copied into the docker container which is generated by docker-compose and replaces the default configuration for Nginx.
 
-```
-export FLASK_APP=portal/app
-flask run --debug
-```
+When using URLs or connections to applications in different containers make sure you provide the name of the container as the hostname. Example: `http://portal:8000` would connect to the application on port 8000 in the "portal" container using the HTTP scheme.
 
-Using flask debug mode is recommended for getting feedback on errors rather than HTTP internal server error status codes. The local flask app will use a local sqlite3 database (which should be created in `portal/instance/` at runtime). This should make it easy to ensure that the application is saving objects to the database correctly.
+### MySQL
+By default, the docker-compose file will auto-generate a docker MySQL image and set the `FLASK_SQLALCHEMY_DATABASE_URI` env variable (this will override any settings in `default_config.py` and in `portal/.env`). The MySQL database can be configured via its configuration file located in `mysql/mysql.cnf`, which will extend/override any default configurations existing in the MySQL image.
+
+The Flask app will use the local MySQL docker database when running in production (via docker-compose). However, if you wish to use a custom remote MySQL server then you will need to change the `FLASK_SQLALCHEMY_DATABASE_URI` in the `docker-compose.yml` file to refer to that database. The default installed database connector is `PyMySQL`, if a different one is desired it will need to be installable via pip (so that docker can install it in the container), otherwise, this will require manual intervention from the user.
 
 ### Deployment
 When deploying this application, however, the portal app uses the gunicorn wsgi web server to run the application instead of flask. This is a production-ready server designed to handle more requests than flask. The `portal` and `mysql` containers will only be accessible through localhost on port 8000 and port 3306 respectively. Instead, the `nginx` container will be remotely accessible on either port 80 (HTTP) or port 443 (HTTPS) which will forward requests to the flask app.
 
-These settings are already automatically configured by docker and docker-compose so there shouldn't be a need to do anything besides running `docker-compose up`, which will build the images and then run them. Additional settings can be configured in the `docker-compose.yml` file or the individual `Dockerfile`'s for each subsystem.
+These settings are already automatically configured by docker and docker-compose so there shouldn't be a need to do anything besides running `docker-compose up -d`, which will build the images and then run them. Additional settings can be configured in the `docker-compose.yml` file or the individual `Dockerfile`'s for each subsystem.
 
 The application can be deployed on any system running `docker` and `docker-compose`. If deploying on Microsoft Azure Cloud, the application can be installed as an [App Service](https://learn.microsoft.com/en-us/azure/app-service/overview) running a multi-container app (The `docker-compose.yml` file will need to be modified for this and any pre-generated images will either need to be pushed to azure or docker-hub). Unfortunately, this does not easily support automatic deployment without using the Azure CLI. Automatic deployment is currently being investigated.