GitHub Readme.md
UDOIT enables faculty to identify accessibility issues in Canvas by Instructure. Scan a course, generate reports, and provide resources to address common accessibility issues.
In late 2013, the proposal submitted by UCF's Center for Distributed Learning won Instructure, Inc.’s Canvas Grant in the higher education category. The $10,000 grant was awarded to UCF – CDL to take an existing tool and further develop this solution into what is now known as UDOIT.
UDOIT has been recognized by the industry, heres a quick list of the awards it's won.
UDOIT is distributed under the GNU GPL v3 license.
Copyright (C) 2014 University of Central Florida, created by Jacob Bates, Eric Colon, Fenel Joseph, and Emily Sachs.
This program is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.
You should have received a copy of the GNU General Public License along with this program. If not, see http://www.gnu.org/licenses/.
Primary Contact: Jacob Bates jacob.bates@ucf.edu
UDOIT includes a modified QUAIL library. QUAIL requires derivitives to be distributed under the GNU General Public License version 3
UDOIT includes a Composer binary which is distributed under the MIT license
UDOIT can be installed on your own existing servers, but we've also configured an easy install to a free Heroku server.
To start the Heroku deployment process, you can click the button below, please note, that although this button eliminates much of the installation complexity, there are still some configuration steps that need to be followed, those steps are outlined in the HEROKU.md Readme.
There are two methods of obtaining the source code and maintaining your installation of UDOIT: Git Clone or Download ZIP.
The benefit of this method is that you can update an existing installation of UDOIT by simply using git pull
. It also lets you roll back to previous versions if needed. Follow these steps:
git clone git@github.com:ucfopen/UDOIT.git .
(The .
is important. It tells Git to download the files to the current directory.)This method is useful if you don't want to install Git on your server, but if you want to update UDOIT later, you will have to manually overwrite files with the new versions. Follow these steps:
The details of configuring a web server with PHP are out of the scope of this README. However, there is an optional configuration step you can take to increase the security of your UDOIT installation. Without any special web server configuration, UDOIT will work if you place it in the web root of your server. You can even place it in a subfolder inside your web root with no issues. If someone tries to access any of your configuration files via a URL, they will only see a blank page.
If you'd like to add a little extra security to your installation, you can configure your web server to point to UDOIT's "public" folder. Doing this will hide the configuration files so that they are not web accessible. It will also clean up your URL structure so that you don't need to include the "public" folder in any of the URLs to UDOIT. See the LTI Config URL Notes section of this README for examples.
UDOIT uses Composer to install PHP dependencies. So cd
into your UDOIT directory and run this command before anything else:
$ php composer.phar install --no-dev
The libraries (other then Quail) that we rely on can be found in composer.json
.
Please refer to the documentation for these three libraries for additional information.
After Insalling Dependencies, the following directories need to be made writable by your webserver:
vendor/mpdf/mpdf/ttfontdata
vendor/mpdf/mpdf/tmp
public/reports
config
UDOIT works with MySQL, MariaDB, or PostgreSQL
GRANT
while Pg requires OWNER
.If config/localConfig.php
doesn't exist, create it using a copy of the template:
$ cp config/localConfig.template.php config/localConfig.php
Edit config/localConfig.php
:
$db_type
- use 'mysql' or 'pgsql'$db_host
- the host or ip address of your database server, often 'localhost'$db_port
- the database server's port, MySQL's default is '3306'$db_user
- database user that has access to your tables$db_password
- the database user's password$db_name
- The database name that contains the tables$db_user_table
- Default is 'users', no change needed unless you change the table names$db_reports_table
: - Default is 'reports', no change needed unless you change the table names$db_job_queue_table
: - Default is 'job_queue', no change needed unless you change the table namesTo create the required tables, run the creation script below. You'll need to complete the db steps above first.
$ php composer.phar db-setup
The table schema can be found in bin/db_create_tables.php
If you didn't already make config/localConfig.php
when you set up the database, do it now.
Please refer to the Canvas API Policy before using this application, as it makes heavy use of the Canvas API.
UDOIT uses the security processes built into the LTI specification to ensure that users are only accessing UDOIT from within your instance of Canvas. There are two values that need to be set in order for this security process to work. These values should be different from each other. You will use them again when you are installing the LTI in Canvas.
Edit config/localConfig.php
:
$consumer_key
: A value you make up.$shared_secret
: The value you make up.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. Here is the information you need to provide them:
oauth2response.php
file in the UDOIT directory.https://www.example.com/public/oauth2response.php
. (Replace 'www.example.com' with the url of your UDOIT server.)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:
After you receive your Developer Key from your Canvas admin, edit the following variables in config/localConfig.php
:
$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$oauth2_enforce_scopes
: Set to true if you are using Scoped Developer Keys.If you'd like to use this option, you'll need set the following scopes for your developer 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:
config/localConfig.php
in the define('GOOGLE_API_KEY', '');
statement. For example, if your API key is heythisisanapikey
, that line should look like define('GOOGLE_API_KEY', 'heythisisanapikey');
when you're done.If you do not provide a Google API key, a warning log will be recorded in config/log.log
and all YouTube videos will be marked for manual inspection by the user.
In order for UDOIT to scan Vimeo videos for closed captioning, you will need to create a Vimeo API key. Follow the instructions below:
Public
and Private
checkboxes for Scopes.)config/localConfig.php
in the define('VIMEO_API_KEY', '');
statement. For example, if your API key is heythisisanapikey
, that line should look like define('VIMEO_API_KEY', 'heythisisanapikey');
when you're done.If you do not provide a Vimeo API key, a warning log will be recorded in config/log.log
and all Vimeo videos will be marked for manual inspection by the user.
If you would like to use Google Analytics for tracking usage of UDOIT, create a new tracking code and add it to config/localConfig.php
in the define('GA_TRACKING_CODE', '');
statement. For example, if your tracking code is UA-12345678-1
, that line should look like define('GA_TRACKING_CODE', 'UA-12345678-1');
when you're done.
As of 2.5.0, the admin panel is still an experimental feature. Consider it a first draft of what we'd like it to be. It lets you view reports across your institution, generate statistics about reports and user growth, and administer user accounts. This feature is disabled by default. To enable it, change $admin_panel_enabled
to true
.
Log into Canvas to add UDOIT:
UDOIT
.$consumer_key
from config/localConfig.php
$shared_secret
from config/localConfig.php
udoit.xml.php
. See LTI Config URL Notes.The URL of your UDOIT LTI config depends on your webserver install. The file is located the public
directory. The examples below should give you are some possible values:
https://<DOMAIN>/udoit.xml.php
https://<DOMAIN>/public/udoit.xml.php
https://<DOMAIN>/udoit/udoit.xml.php
https://<DOMAIN>/udoit/public/udoit.xml.php
The instructions below are general guidelines for upgrading your installation of UDOIT from one version to the next. However, the release notes for a particular version might contain specific instructions for that version, and those instructions supersede the ones below. Since the instructions differ depending on how you installed UDOIT, they are separated by these methods below.
Install a new instance of UDOIT using the HEROKU.md Readme. Then, swap the old one out with the new one in Canvas.
git pull
php composer.phar install
php composer.phar migrate
php composer.phar install
.For more information about how to use UDOIT you can read the UDOIT User Guide created by Clemson University. It can be accessed by importing the pages as modules into an existing course. The guide covers the reasoning behind the accessibility issues that UDOIT addresses as well as detailed descriptions of how to interpret and interact with the results of a scan.
Navigate to your LTI install page at https://<domain>/udoit.xml.php
where domain
is the location of your install. This URL may also look like the list from the section above.
This page will display XML if all of the following are true:
Here's an example of a working LTI install page: https://udoit.herokuapp.com/udoit.xml.php
Turn on PHP tracing on the server to view possible errors.
If you see an issue pertaining to require_once(__DIR__.'/../vendor/autoload.php');
make sure you've run Composer to install all of the dependencies. In the root UDOIT folder on your server run:
$ php composer.phar install
If you get a warning about Bower not being found, you will need to install Bower on your server and run the above command again.
The oauth2response.php
file generates an API key to gain access to the Canvas API.
If you suspect that there is an authentication problem, first try echoing or error logging the variable $base_url
from this file to check the URL.
Whether hosted on your own server or on Heroku, the URL where UDOIT has been installed needs to be designated as an authorized domain for your Google/YouTube API keys.
If database migrations fail, make sure the database user has the ability to alter tables in your udoit database. Give that user permission to ALTER tables. MySQL uses GRANT
while PostgreSQL requires OWNER
.
There are a few different ways you can get in touch with us, depending on what you're most comfortable with:
UDOIT should require little to no maintenance. It is up to your institution to choose when you update UDOIT to the latest release. UDOIT can be updated by running git pull
on this repository.
The Deploy to Heroku
button installs the latest release of UDOIT when clicked. Your Heroku instance will not be updated automatically when new updates are released. You can either:
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 Canvas API Documentation.
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.
From the public directory, run:
$ php composer.phar start
Then open http://localhost:8000 in a browser.
To setup the Docker environment, follow the steps outlined in the DOCKER.md Readme.
We use phpunit to run unit tests on UDOIT. To run the tests, type the following command:
$ php composer.phar test
We included a Dockerfile, docker-compose.yml, and tests script to run your tests in a predictable environment. To run tests using docker run this command:
$ php composer.phar docker-test
By default, we exclude functional tests that include external APIs. If you would like to run those tests, run this command:
$ ./vendor/phpunit/phpunit/phpunit