Merge pull request ucfopen#1077 from dmols/updated-instructions

updated the instructions to be a little neater

Author: dmols

INSTALL.md

@@ -38,7 +38,7 @@ cp .env.example .env
 This command copies the `.env.example` into `.env`, creating the `.env` file in the process if it does not exist.
 
 2. Open `.env` with a text editor (i.e. Notepad, VS Code, etc.) and make the necessary changes to the following variables:
-   - `APP_ENV`: If you are setting up a development environment, change this to `dev` and follow the steps in [Installing Composer Dependencies](#installing-composer-dependencies) without the `--no-dev` flag to obtain all of the development packages. Otherwise, leave it as `prod`.
+   - `APP_ENV`: If you are setting up a development environment, change this to `dev`. Otherwise, leave it as `prod`.
    - `DATABASE_URL`: If you are hosting UDOIT on Docker or your local machine, leave it as it is. Otherwise, change it to your database URL.
    - `BASE_URL`: If you are hosting UDOIT on Docker or your local machine, leave it as it is. Otherwise, change it to the URL of your instance of UDOIT.
    - `WEBPACK_PUBLIC_PATH`: Uf you are hosting UDOIT on Docker or your local machine, leave it as it is. Otherwise, change it to match the `BASE_URL`in such a way that `/build` is located at the root of the `BASE_URL` (Example:  If your `BASE_URL` is set to `http://127.0.0.1:8000`, your `WEBPACK_PUBLIC_PATH` should be `/build`).
@@ -51,20 +51,31 @@ This command copies the `.env.example` into `.env`, creating the `.env` file in
 ### Option 1: Docker
 We provide a fast and simple way of setting up a local UDOIT instance through Docker.
 
-1. Install [Docker Desktop](https://docs.docker.com/get-docker/). This will install Docker and Docker Compose on your system.
-	> Alternatively, you may install Docker and [Docker Compose](https://docs.docker.com/compose/install/) individually.
+#### 1. Install [Docker Desktop](https://docs.docker.com/get-docker/). This will install Docker and Docker Compose on your system.
+> Alternatively, you may install Docker and [Docker Compose](https://docs.docker.com/compose/install/) individually.
 
-2. Build the Containers
+#### 2. (Optional) Install the Necessary PHP Dependencies for Dev Environment
+
+UDOIT uses Composer to install PHP dependencies. If your `APP_ENV` is set to `prod`, UDOIT will handle this for you. However, if it is set to `dev`, you may need some additional dependencies.
+
+You can set them up by running the following command:
+```
+docker compose -f docker-compose.nginx.yml run composer composer install
+```
+
+#### 3. Build the Containers
 
 ```
     make start
 ```
 
-3. Once the containers are initialized, run the following command:
+*Note: This may take a while to fully initiate. This is normal.*
+#### 4. Set Up Database
+
+The following command applies migrations necessary to set up the database to store all UDOIT data. Please make sure the containers have fully spun up before running this command.
 ```
     make migrate
 ```
-This applies migrations necessary to set up the database to store all UDOIT data.
 
 Running this will give the following warning:
 
@@ -76,12 +87,14 @@ Type `yes` and proceed. The warning is expected and is a non issue.
 
 UDOIT should be installed and running as Docker containers.
 
-4. To stop the UDOIT containers, run the following command:
+#### To stop the UDOIT containers, run the following command:
 ```
     make down
 ```
 
-> Please be sure to review the `makefile` for more information on what these commands do.
+Please be sure to review the `makefile` for more information on what this command and others do.
+
+If UDOIT is running without errors, you can move on to [installing it for your LMS](#connecting-udoit-to-an-lms)! If you're encountering errors, please check out the [wiki](https://github.com/ucfopen/UDOIT/wiki).
 
 ### Option 2: Manual Installation
 If you prefer not to use Docker, the process is more complicated:
@@ -140,3 +153,6 @@ For example, if you are setting this up on your local computer via Docker, it ma
 To configure it fully within your LMS, follow the installation instructions below that apply to you.
 - To install it on Canvas, follow [INSTALL_CANVAS.md](INSTALL_CANVAS.md)
 - or for D2l Brightspace, follow [INSTALL_D2L.md](INSTALL_D2L.md)
+
+## Encountering Errors
+Please resort to the [wiki page](https://github.com/ucfopen/UDOIT/wiki) for some commonly found errors when setting up UDOIT.

INSTALL_CANVAS.md

@@ -5,27 +5,29 @@ Once UDOIT has been installed on a public web server the following steps must be
 * Update the Institutions table
 * Install the application
 
+## Docker Compose Base URL
+If you are setting up UDOIT for local development through `docker compose`, <YOUR_UDOIT_BASE_URL> in both the API developer key and the LTI developer key above should be set to `http://127.0.0.1:8000/udoit3`.
+
+
 ## Create an API Developer Key
 UDOIT requires an API developer key since all course data is gathered through the Canvas API.
 
 ### Steps to Create an API Key
 1. Navigate to `Developer Keys` in the root account menu.
 2. Choose to add a `Developer Key` => `API Key`
 3. Provide values for the following fields:
-* Key Name: i.e. UDOIT 3 API
-* Owner Email
-* Redirect URIs: <YOUR_UDOIT_BASE_URL>/authorize/check
-* Icon URL: <YOUR_UDOIT_BASE_URL>/build/static/udoit_logo.svg
-* Client Credentials
-* Canvas
-* Enforce Scopes
-* See the section below for a list of scopes to enable.
-* Check `Allow Include Parameters`
-* Redirect URL (Legacy) : *SKIP*
-* Vendor Code : *SKIP*
-* Notes : *Optional*
-* These are only seen by other LMS admins
-* Test Cluster Only : *SKIP*
+   * Key Name: i.e. UDOIT 3 API
+   * Owner Email
+   * Redirect URIs: <YOUR_UDOIT_BASE_URL>/authorize/check
+   * Redirect URL (Legacy) : *SKIP*
+   * Vendor Code : *SKIP*
+   * Icon URL: <YOUR_UDOIT_BASE_URL>/build/static/udoit_logo.svg
+   * Notes : *Optional*
+     * These are only seen by other LMS admins
+   * Client Credentials Audience: Canvas
+   * Enforce Scopes
+     * Check `Allow Include Parameters`
+     * See the section below for a list of scopes to enable.
 4. Save
 5. Click `ON` to enable the newly created key
 
@@ -42,6 +44,14 @@ We strongly recommend you enforce scopes with your API key. The following scopes
   * url:GET|/api/v1/courses/:course_id/assignments
   * url:GET|/api/v1/courses/:course_id/assignments/:id
   * url:PUT|/api/v1/courses/:course_id/assignments/:id
+* context_module_items_api
+  * url:GET|/api/v1/courses/:course_id/modules/:module_id/items
+  * url:GET|/api/v1/courses/:course_id/modules/:module_id/items/:id
+  * url:PUT|/api/v1/courses/:course_id/modules/:module_id/items/:id
+* context_modules_api
+  * url:GET|/api/v1/courses/:course_id/modules
+  * url:GET|/api/v1/courses/:course_id/modules/:id
+  * url:PUT|/api/v1/courses/:course_id/modules/:id
 * courses
   * url:PUT|/api/v1/courses/:id
   * url:GET|/api/v1/courses/:id
@@ -55,14 +65,6 @@ We strongly recommend you enforce scopes with your API key. The following scopes
 * files
   * url:GET|/api/v1/courses/:course_id/files
   * url:GET|/api/v1/courses/:course_id/files/:id
-* context_module_items_api
-  * url:GET|/api/v1/courses/:course_id/modules/:module_id/items
-  * url:GET|/api/v1/courses/:course_id/modules/:module_id/items/:id
-  * url:PUT|/api/v1/courses/:course_id/modules/:module_id/items/:id
-* context_modules_api
-  * url:GET|/api/v1/courses/:course_id/modules
-  * url:GET|/api/v1/courses/:course_id/modules/:id
-  * url:PUT|/api/v1/courses/:course_id/modules/:id
 * quizzes/quiz_questions
   * url:GET|/api/v1/courses/:course_id/quizzes/:quiz_id/questions
   * url:GET|/api/v1/courses/:course_id/quizzes/:quiz_id/questions/:id
@@ -84,7 +86,6 @@ We strongly recommend you enforce scopes with your API key. The following scopes
   * url:GET|/api/v1/courses/:course_id/enrollments
   *   
 
----
 ## Create an LTI Developer Key
 UDOIT uses LTI 1.3 to integrate with the LMS.
 
@@ -94,30 +95,26 @@ Follow the steps below, replacing `<YOUR_UDOIT_BASE_URL>` with the `BASE_URL` va
 1. Navigate to `Developer Keys` in the root account menu.
 2. Choose to add a `Developer Key` => `LTI Key`
 3. Provide values for the following fields:
-* Key Name: i.e. UDOIT 3 LTI
-* Owner Email
-* Redirect URIs: <YOUR_UDOIT_BASE_URL>/lti/authorize/check
-* Configure method: Enter URL
-* JSON URL: <YOUR_UDOIT_BASE_URL>/lti/config
-* If your instance of Canvas is self-hosted, modify the URL under **JWK Method** to point to your Canvas instance.
-* Set Additional Settings
-* Domain: Your UDOIT domain
-* Tool ID: Enter a name
-* Custom Fields
-	```
-	lms_id=canvas
-	lms_user_id=$Canvas.user.id
-	lms_course_id=$Canvas.course.id
-	lms_api_domain=$Canvas.api.domain
-	```
+   * Key Name: i.e. UDOIT 3 LTI
+   * Owner Email
+   * Redirect URIs: <YOUR_UDOIT_BASE_URL>/lti/authorize/check
+   * Configure methods
+     * Manual entry
+     * Paste JSON URL: <YOUR_UDOIT_BASE_URL>/lti/config
+   * If your instance of Canvas is self-hosted, modify the URL under **JWK Method** to point to your Canvas instance.
+   * Set Additional Settings
+   * Domain: Your UDOIT domain
+   * Tool ID: Enter a name
+   * Custom Fields
+      ```
+      lms_id=canvas
+      lms_user_id=$Canvas.user.id
+      lms_course_id=$Canvas.course.id
+      lms_api_domain=$Canvas.api.domain
+      ```
 4. Click Save.
-5. Click `ON` to enable the newly created key.
-
----
-## Docker Compose Base URL
-If you are setting up UDOIT for local development through `docker compose`, <YOUR_UDOIT_BASE_URL> in both the API developer key and the LTI developer key above should be set to `http://127.0.0.1:8000/udoit3`.
+5. Click `ON` to enable  the newly created key.
 
----
 ## Update the Institutions Table
 UDOIT is built to support more than one LMS instance. For this purpose, we have an `institution` table that must be populated with the LMS information.
 
@@ -131,17 +128,21 @@ UDOIT is built to support more than one LMS instance. For this purpose, we have
 - `CREATED` = Date in this format: `2021-06-08`
 - `STATUS` = `1` if you are using MySQL or MariaDB (or Docker), `true` if you are using PostgreSQL
 - `VANITY_URL` = Your LMS vanity URL (i.e. `canvas.myschool.edu`)
-- `METADATA` = Optional. Institution-specific settings, such as language or excluded tests. Text representation of a JSON object. (i.e. `{"lang":"es"}`)
+- `METADATA` = Optional. Institution-specific settings, such as language or excluded tests. Text representation of a JSON object. (i.e. `{"lang":"en"}`)
 - `API_CLIENT_ID` = The ID of the developer API key you created earlier
 - `API_CLIENT_SECRET` = The secret for the API key you created earlier
 
-4. Run the following command:
+With all the values now set up, you're ready to run the command that will automate the creation of your `institutions` table! Run the following command if you have a MySQL database setup:
+```
+make ins-mysql
+```
+Or this one if you have a PostgreSQL setup:
 ```
-make ins-mysql	# For MySQL or MariaDB
-make ins-psql	# For PostgreSQL
+make ins-psql
 ```
+Your database should now show a new row in the `institution` table, containing all the values you input above.
+
 
----
 ## .ENV Setup
 For cloud-hosted canvas instances, the default value for the `JWK_BASE_URL` environmental variable will work out of the box. If you are not cloud-hosted, you may need to change the value of this variable in `.env.local` to match your canvas instance.
 
@@ -159,5 +160,3 @@ UDOIT now needs to be added to an account in Canvas. Follow these steps to add t
 9. Click Submit.
 
 You're done!  "UDOIT" should now appear in the navigation menu of the course (or every course in the account) in which you installed it.  If you installed it on an account, "UDOIT Admin" will also appear in the account navigation menu.
-
-