Merge pull request #452 from ucfopen/dev/v2-6-0

Dev/v2 6 0

Author: bagofarms

HEROKU.md

@@ -15,14 +15,15 @@ After clicking the Heroku button above:
 
 1. Create an account (if you don't have one already).
 2. Give the app a name.
-3. Fill out the `OAUTH2_ID` and `OAUTH2_KEY` fields with dummy data.  (We'll fix it later.)
-4. Fill out the `OAUTH2_URI` field with `https://yourapp.herokuapp.com/oauth2response.php`. (Replace 'yourapp' with the name you gave in step 2.)
-5. Fill out the `CANVAS_NAV_ITEM_NAME` field with the name you would like the app to appear as in the course navigation menu.  This is useful if your instance will be use for a pilot.  The normal value to use here is ***UDOIT***.
-6. (optional) Copy and paste your Google/YouTube API key into the `GOOGLE_API_KEY` field.
-7. (optional) Copy and paste your Vimeo API key into the `VIMEO_API_KEY` field.
-8. (optional) If you have a Google Analytics account, you can paste your site tracking code into the `GA_TRACKING_CODE` field.
-9. (optional) If you would like to enable the Admin Panel, change the `ADMIN_PANEL_ENABLED` field to `true`.
-8. Click the Deploy button and wait for the process to complete.
+3. Set `OAUTH2_ENFORCE_SCOPES` to true if you have a scoped developer key.
+4. Fill out the `OAUTH2_ID` and `OAUTH2_KEY` fields with dummy data. (We'll fix it later.)
+5. Fill out the `OAUTH2_URI` field with `https://yourapp.herokuapp.com/oauth2response.php`. (Replace 'yourapp' with the name you gave in step 2.)
+6. Fill out the `CANVAS_NAV_ITEM_NAME` field with the name you would like the app to appear as in the course navigation menu.  This is useful if your instance will be use for a pilot.  The normal value to use here is ***UDOIT***.
+7. (optional) Copy and paste your Google/YouTube API key into the `GOOGLE_API_KEY` field.
+8. (optional) Copy and paste your Vimeo API key into the `VIMEO_API_KEY` field.
+9. (optional) If you have a Google Analytics account, you can paste your site tracking code into the `GA_TRACKING_CODE` field.
+10. (optional) If you would like to enable the Admin Panel, change the `ADMIN_PANEL_ENABLED` field to `true`.
+11. Click the Deploy button and wait for the process to complete.
 
 ### Step 3:  Request a Developer Key
 UDOIT uses Oauth2 to take actions on behalf of the user, so you'll need to ask your Canvas administrator to generate a Developer Key for you.  (If you are an admin, go to your institution's account administration page in Canvas and click on 'Developer Keys'.)  Here is the information you need to provide them:
@@ -33,6 +34,35 @@ UDOIT uses Oauth2 to take actions on behalf of the user, so you'll need to ask y
  * This should be `https://yourapp.herokuapp.com/oauth2response.php`. (Replace 'yourapp' with the name of your UDOIT instance on Heroku.)
 * ***Icon URL:*** The URL of the UDOIT icon.  This is `https://yourapp.herokuapp.com/assets/img/udoit_icon.png`.  (Replace ***yourapp*** with the name of your UDOIT instance on Heroku.)
 
+#### Scoped Developer Keys
+If you'd like to use this option, you'll need set the following scopes for your developer key.
+* Assignments
+	* 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
+* Courses
+	* url:PUT|/api/v1/courses/:id
+	* url:GET|/api/v1/courses/:id
+	* url:POST|/api/v1/courses/:course_id/files
+* Discussion Topics
+	* url:GET|/api/v1/courses/:course_id/discussion_topics
+	* url:GET|/api/v1/courses/:course_id/discussion_topics/:topic_id
+	* url:PUT|/api/v1/courses/:course_id/discussion_topics/:topic_id
+* Files
+	* url:GET|/api/v1/courses/:course_id/files
+	* url:GET|/api/v1/courses/:course_id/folders/:id
+	* url:GET|/api/v1/folders/:id/folders
+	* url:GET|/api/v1/folders/:id/files
+* Modules
+	* url:GET|/api/v1/courses/:course_id/modules
+	* url:GET|/api/v1/courses/:course_id/modules/:module_id/items
+* Pages
+	* url:GET|/api/v1/courses/:course_id/pages
+	* url:GET|/api/v1/courses/:course_id/pages/:url
+	* url:PUT|/api/v1/courses/:course_id/pages/:url
+* Users
+	* url:GET|/api/v1/users/:user_id/profile
+
 ### Step 4:  Add your Developer Key to UDOIT
 1. In Heroku, click the 'Manage App' button for your install of UDOIT.
 2. Go to the 'Settings' tab.
@@ -43,7 +73,7 @@ UDOIT uses Oauth2 to take actions on behalf of the user, so you'll need to ask y
 
 ### Step 5:  Install the UDOIT LTI
 
-In Canvas, you can install UDOIT at the course or sub-account levels.  
+In Canvas, you can install UDOIT at the course or sub-account levels.
 
 1. Click the **Settings** menu item from any course in Canvas.
 2. Click the **Apps** tab.
@@ -60,6 +90,8 @@ UDOIT should now be available in the course navigation menu.
 
 # Manual Deploy on Heroku
 
+**Warning: Recommended for advanced users only**
+
 You can use our configuration to launch a new Heroku app using [Heroku's app-setups api](https://devcenter.heroku.com/articles/setting-up-apps-using-the-heroku-platform-api).
 
 You'll have to set some env settings. Peek at [app.json](app.json) for any env vars that don't have `"required": false` set. Our config vars are covered in [Configure section](#configure)
@@ -79,7 +111,7 @@ curl -n -X POST https://api.heroku.com/app-setups \
 
 Read the result to make sure it returned an id, not an error.
 
-Check your Heroku dashboard or run `heroku apps` to see if a new app shows up.  If all goes well, it should be running.
+Check your Heroku dashboard or install the [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) and run `heroku apps` to see if a new app shows up.  If all goes well, it should be running.
 
 
 ## Configure
@@ -129,6 +161,62 @@ If needed, you can manually run the table creation script: `heroku run composer
 ## Table Schema
 The table schema can be found in [migrations/](migrations/)
 
+# Upgrade an Existing Heroku Installation
+
+When it comes time to update UDOIT to the latest version, you probably don't want to have to start over from scratch using the Heroku Button (as explained above).  Luckily, there's a procedure for upgrading an existing installation, which allows you to keep your existing database, settings, and URL.
+
+## First Time Setup
+
+This process takes a while to set up the first time, but is very fast after that.  On your computer:
+
+1. Install [Git](https://git-scm.com/downloads)
+2. [Configure Git](https://git-scm.com/book/en/v2/Getting-Started-First-Time-Git-Setup)
+3. Install [Heroku CLI](https://devcenter.heroku.com/articles/heroku-cli) and follow the instructions to get your account set up.
+4. Clone the UDOIT Git repository.  If you are using a command line interface, navigate to a directory where you would like the code to live and run this command:  `git clone git@github.com:ucfopen/UDOIT.git`.  This will create a folder called `UDOIT` that contains the latest version.
+5. In your command line interface, navigate into the newly-created `UDOIT` folder.
+6. Run `heroku git:remote --app your-heroku-instance`, replacing `your-heroku-instance` with your actual heroku instance name.  For example, if your UDOIT instance resides at `https://udoit-pcu.herokuapp.com`, you would run `heroku git:remote --app udoit-pcu`.  This adds your Heroku instance as a ***remote*** called `heroku` in the Git repository so that you can push updates to it in the future.
+
+## Pushing Updates to Heroku
+
+Now that your computer is set up, you only need to follow these steps each time you would like to update your instance of UDOIT:
+
+1. In your command line interface, navigate to the `UDOIT` directory on your computer.
+2. Run `git checkout master` to make sure we're on the master branch, which represents the latest version of UDOIT.
+3. Run `git pull` to update your local copy of UDOIT from the official GitHub repository.
+4. Run `git push heroku master:master` to deploy the new version to your UDOIT instance.
+5. Run `heroku run --app your-heroku-instance "php composer.phar migrate"` to update the database structure for your UDOIT instance. (Remember to replace `your-heroku-instance` with your Heroku instance name.)
+6. Log into the Heroku website and click on your UDOIT instance.
+7. Click **Settings**
+8. Under the **Config Vars** heading, click **Reveal Config Vars**.
+9. Compare them to the `env` section of [app.json](app.json), and add any missing variables to Heroku.
+
+UDOIT should now be up to date with the latest release!
+
+## Dealing with Multiple Heroku Instances
+
+### First Time Setup (Test Instance)
+
+The sections above assume you only have a single Heroku instance.  However, we recommend you always have two instances:  one for testing and one for production.  That way, you can test out the deploy on your test instance without risking any downtime on your production instance.  If you don't have a test instance, just use the [Heroku Button](#heroku-button) to create one.  Assuming you set everything up for your production instance in the [First Time Setup](#first-time-setup) section above, here's how to set up your testing instance (sometimes called "staging" or "QA"):
+
+1. In your command line interface, navigate to the `UDOIT` directory on your computer.
+2. Run `heroku git:remote --remote test --app your-heroku-test-instance`, replacing `your-heroku-test-instance` with your actual heroku test instance name.  For example, if your UDOIT instance resides at `https://udoit-pcu-test.herokuapp.com`, you would run `heroku git:remote --remote test --app udoit-pcu-test`.  This adds your Heroku test instance as a ***remote*** called `test` in the Git repository so that you can push updates to it in the future.
+
+Feel free to name the remote anything you want.  It doesn't have to be `test`; it could be `staging` or `qa` or `blah`.  It's best to make it something descriptive, though.
+
+### Pushing Updates to the Test Instance
+
+Now that you have the connection to the test instance set up, here's how to push an update to it:
+
+1. In your command line interface, navigate to the `UDOIT` directory on your computer.
+2. Run `git checkout master` to make sure we're on the master branch, which represents the latest version of UDOIT.
+3. Run `git pull` to update your local copy of UDOIT from the official GitHub repository.
+4. Run `git push test master:master` to deploy the new version to your UDOIT test instance.
+5. Run `heroku run --app your-heroku-test-instance "php composer.phar migrate"` to update the database structure for your UDOIT test instance.  (Remember to replace `your-heroku-test-instance` with your Heroku test instance name.)
+6. Log into the Heroku website and click on your UDOIT test instance.
+7. Click **Settings**
+8. Under the **Config Vars** heading, click **Reveal Config Vars**.
+9. Compare them to the `env` section of [app.json](app.json), and add any missing variables to Heroku.
+
 # FAQ
 
 ## Why aren't my scans completing?

README.md

@@ -54,6 +54,7 @@ To start the Heroku deployment process, you can click the button below, please n
 * PHP 7.1, 7.2 (Not yet compatible with 7.3.  See issue #422)
   * [GD Graphics Library](http://php.net/manual/en/book.image.php)
 * MySQL or PostgreSQL
+* Git (If you are using [The Git Method](#the-git-method) below) or if you plan on contributing to UDOIT
 
 ## Downloading the Source Code
 There are two methods of obtaining the source code and maintaining your installation of UDOIT:  Git Clone or Download ZIP.
@@ -81,7 +82,7 @@ If you'd like to add a little extra security to your installation, you can confi
 UDOIT uses [Composer](https://getcomposer.org/) to install PHP dependencies. So `cd` into your UDOIT directory and run this command before anything else:
 
 ```
-$ php composer.phar install
+$ php composer.phar install --no-dev
 ```
 
 The libraries (other then Quail) that we rely on can be found in `composer.json`.
@@ -150,11 +151,49 @@ UDOIT uses Oauth2 to take actions on behalf of the user, so you'll need to ask y
  * If you did a normal install into the web root of your server, it would be `https://www.example.com/public/oauth2response.php`. (Replace 'www.example.com' with the url of your UDOIT server.)
 * ***Icon URL:*** The URL of the UDOIT icon.  This is `https://www.example.com/public/assets/img/udoit_icon.png`.  (Replace 'www.example.com' with the url of your UDOIT server.)
 
+Your Canvas administrator will perform the following tasks:
+1. Navigate to your institution's ***Account Admin panel*** in Canvas.
+2. Click on the ***Developer Keys*** menu option.
+3. Click the ***+ Developer Key*** button and select the ***API Key*** option.
+4. Enter the data provided above into the form, leaving the ***Redirect URI (Legacy)*** and ***Vendor Code (LTI 2)*** fields blank.
+5. (Optional) If you would like to Enforce Scopes on this developer key, which limits this Developer Key to only allow access to the functions UDOIT requires, enable the option and check the boxes outlined in the [Scoped Developer Keys](#scoped-developer-keys) section below.
+6. Click ***Save Key***
+7. Find the new Developer Key in the list, and send the values from the ***Details*** column to the person requesting the key.  The top value is the ***Oauth2 ID***, and the value revealed by clicking on the ***Show Key*** button is the ***Oauth2 Key***.
+
 After you receive your Developer Key from your Canvas admin, edit the following variables in `config/localConfig.php`:
 
-* `$oauth2_id`: The Client_ID yoru Canvas admin gives you
-* `$oauth2_key`: The Secret your Canvas admin gives you
-* `$oauth2_uri`: The Redirect URI you provided to your Canvas admin
+* `$oauth2_id`: The ***Oauth2 ID*** your Canvas admin gives you
+* `$oauth2_key`: The ***Oauth2 Key*** your Canvas admin gives you
+* `$oauth2_uri`: The ***Redirect URI*** you provided to your Canvas admin
+
+#### Scoped Developer Keys
+If you'd like to use this option, you'll need set the following scopes for your developer key.
+* Assignments
+	* 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
+* Courses
+	* url:PUT|/api/v1/courses/:id
+	* url:GET|/api/v1/courses/:id
+	* url:POST|/api/v1/courses/:course_id/files
+* Discussion Topics
+	* url:GET|/api/v1/courses/:course_id/discussion_topics
+	* url:GET|/api/v1/courses/:course_id/discussion_topics/:topic_id
+	* url:PUT|/api/v1/courses/:course_id/discussion_topics/:topic_id
+* Files
+	* url:GET|/api/v1/courses/:course_id/files
+	* url:GET|/api/v1/courses/:course_id/folders/:id
+	* url:GET|/api/v1/folders/:id/folders
+	* url:GET|/api/v1/folders/:id/files
+* Modules
+	* url:GET|/api/v1/courses/:course_id/modules
+	* url:GET|/api/v1/courses/:course_id/modules/:module_id/items
+* Pages
+	* url:GET|/api/v1/courses/:course_id/pages
+	* url:GET|/api/v1/courses/:course_id/pages/:url
+	* url:PUT|/api/v1/courses/:course_id/pages/:url
+* Users
+	* url:GET|/api/v1/users/:user_id/profile
 
 ### Google/YouTube API Key
 In order for UDOIT to scan YouTube videos for closed captioning, you will need to create a YouTube Data API key.  Follow the instructions below:
@@ -273,6 +312,9 @@ The `Deploy to Heroku` button installs the latest release of UDOIT when clicked.
 * Allow inbound traffic from world to UDOIT on 80 and 443
 * Allow outbound traffic from UDOIT to Canvas on 443
 
+### Why am I recieving a "Due to LMS limitations, UDOIT is unable to scan this section." error?
+When an institution installs UDOIT and uses a scoped developer key, certain features of the Canvas API are unavailable to UDOIT, including retrieving content from the Syllabus tool.  This limitation does not affect UDOIT installations that use a non-scoped developer key.  For more information, refer to the "Canvas API Includes" section of the <a href="https://canvas.instructure.com/doc/api/file.developer_keys.html">Canvas API Documentation</a>.
+
 # Developing and Testing
 
 For quick local development, set `$UDOIT_ENV = ENV_DEV;` in `config/localConfig.php`.  This flag disables authentication and allows you to quickly see a sample test report for most template, js, and css development. Use this along with the quick dev server below.

app.json

@@ -42,6 +42,10 @@
       "description": "Full url to your oauth2responce.php file",
       "value": "https://your.herokuapp.com/oauth2response.php"
     },
+    "OAUTH2_ENFORCE_SCOPES": {
+      "description": "Set to true if you have a scoped developer key",
+      "value": "false"
+    },
     "GOOGLE_API_KEY": {
       "description": "Google API key for caption detection support",
       "required": false
@@ -58,6 +62,10 @@
       "description": "needed to use the Heroku configuration",
       "value": "true"
     },
+    "USE_API_CACHING": {
+      "description": "Flag to indicate whether or not to use the api caching feature",
+      "required": false
+    },
     "CANVAS_NAV_ITEM_NAME" : {
       "description": "The text displayed in the canvas navigation menu to launch this app",
       "value": "UDOIT"

config/herokuConfig.php

@@ -10,6 +10,16 @@
 $oauth2_id        = getenv('OAUTH2_ID');
 $oauth2_key       = getenv('OAUTH2_KEY');
 $oauth2_uri       = getenv('OAUTH2_URI');
+$oauth2_enforce_scopes = (getenv('OAUTH2_ENFORCE_SCOPES')) == 'true';
+
+/* Set session cookie options */
+$session_cookie_options = [
+    'expire' => getenv('SESSION_COOKIE_EXPIRE') ?: 0,
+    'path' => getenv('SESSION_COOKIE_PATH') ?: '/',
+    'domain' => getenv('SESSION_COOKIE_DOMAIN') ?: null,
+    'secure' => getenv('SESSION_COOKIE_SECURE') ?: true,
+    'httponly' => getenv('SESSION_COOKIE_HTTPONLY') ?: false,
+];
 
 /* Tool name for display in Canvas Navigation */
 $canvas_nav_item_name = getenv('CANVAS_NAV_ITEM_NAME');
@@ -55,6 +65,9 @@
 /* Google Analytics Tracking Code */
 define('GA_TRACKING_CODE', getenv('GA_TRACKING_CODE')?:'');
 
+/* Flag for API Caching */
+define('USE_API_CACHING', getenv('USE_API_CACHING')?:'');
+
 // Fix some issues caused by the heroku load balancer
 // The OAUTH signature verification doesn't know it's using https w/o this
 if (!empty($_SERVER['HTTP_X_FORWARDED_PROTO']) && $_SERVER['HTTP_X_FORWARDED_PROTO'] == 'https') {

config/localConfig.template.php

@@ -5,9 +5,25 @@
 $shared_secret = '';
 
 /* Canvas Developer Key Oauth 2.0 Settings */
-$oauth2_id  = ''; // Provided by your Canvas Admin
-$oauth2_key = ''; // Provided by your Canvas Admin
-$oauth2_uri = ''; // EX: https://udoit.my-org.edu/oauth2response.php or https://udoit.my-org.edu/udoit/public/oauth2response.php
+$oauth2_id             = '';    // Provided by your Canvas Admin
+$oauth2_key            = '';    // Provided by your Canvas Admin
+$oauth2_uri            = '';    // EX: https://udoit.my-org.edu/oauth2response.php or https://udoit.my-org.edu/udoit/public/oauth2response.php
+$oauth2_enforce_scopes = false; // Set to true if you have a scoped developer key.
+
+/* Set session cookie options
+ * expire - the cookie expiration time in seconds (0 means it does not expire)
+ * path - the applications on this domain to which the cookie is visible
+ * domain - the domain to which this cookie is visible
+ * secure - 'true' to send the cookie only over secure connections
+ * httponly - 'true' to set the 'httponly' flag when setting the cookie
+ */
+$session_cookie_options = [
+    'expire' => getenv('SESSION_COOKIE_EXPIRE') ?: 0,
+    'path' => getenv('SESSION_COOKIE_PATH') ?: '/',
+    'domain' => getenv('SESSION_COOKIE_DOMAIN') ?: null,
+    'secure' => getenv('SESSION_COOKIE_SECURE') ?: true,
+    'httponly' => getenv('SESSION_COOKIE_HTTPONLY') ?: false,
+];
 
 /* Disable headings check character count */
 $doc_length = '1500';
@@ -34,6 +50,9 @@
 /* Google Analytics Tracking Code */
 define('GA_TRACKING_CODE', '');
 
+/* Flag for API Caching */
+define('USE_API_CACHING', '');
+
 /* Database Config */
 $db_type            = 'mysql'; // 'mysql' or 'pgsql'
 $db_host            = ''; // localhost or some other domain/ip

config/localConfig.test.php

@@ -30,6 +30,12 @@
 /* Vimeo API Key */
 define('VIMEO_API_KEY', 'TEST_VIMEO_KEY');
 
+/* Course Language */
+define('COURSE_LANGUAGE', 'TEST_COURSE_LANGUAGE');
+
+/* Flag for API Caching */
+define('USE_API_CACHING', 'false');
+
 /* Database Config */
 $db_type            = 'test'; // 'mysql' or 'pgsql'
 $db_host            = ''; // localhost or ip