Something or other, whatever!

Christian Lawson-Perfect's homepage

Chirun LTI server

Chirun LTI Tool

The Chirun LTI tool provides a simple to use interface for instructors to upload content to a VLE to be automatically converted into accessible and flexible documents with Chirun. With this tool, the instructor does not need to have any knowledge of running Unix software or uploading content to a web-server in order to share the web-based output generated by Chirun.

Installation

Prerequisites

LTI Tool Setup

Clone this repo and copy the software into an install directory (referred to as INSTALLDIR) visible to your web server. Copy the file config.dist.php to config.php and then edit the file to include your own site settings. Take particular note of the following variables,

Name | Description | Example -------------|-------------|--------- WEBDIR | The intended web path for accessing the tool | /lti INSTALLDIR | The full file system path to the tool's install directory | /var/www/webroot/lti PROCESSUSER | The "processing user" that will run the Chirun build tools via docker | programs DB_NAME | A database DSN specifying a database host and name | mysql:dbname=chirun;host=database.example.com DB_USERNAME | Database username | DB_PASSWORD | Database password |

User Permission Setup

Uploaded documents are compiled by running the Chirun software in a docker container. Since allowing access to docker is equivalent to giving root access to a user, this must be handled carefully. For separation of privileges a new Unix user must be created to be used as the Chirun processing user. This user should have access to docker via membership of the docker group.

Assuming your processing user will be named programs, the following commands creates the user and adds it to the docker group, ```

adduser programs

usermod -aG docker programs

```

Directory Permission Setup

The user running the web server process should be able to write to UPLOADDIR, CONTENTDIR and PROCESSDIR/logs, but not permitted to write to anything else in INSTALLDIR. As such, ensure directory permissions are setup as follows, where programs is your processing user and www-data is the primary unix group for the user running the web server process.

Directory | Mode | Owner:Group ----------|------|-------------- INSTALLDIR | 755 | programs:programs UPLOADDIR | 775 | programs:www-data CONTENTDIR | 775 | programs:www-data PROCESSDIR/logs |775 | programs:www-data

Sudo Permission Setup

The sudo command should be configured so that the user running the web server process (e.g. www-data) can start the Chirun processing script as the processing user with some particular environment variables populated. This can be setup by adding the following lines to the /etc/sudoers file,

``` www-data ALL = (programs) NOPASSWD: [PROCESSDIR]/process.sh Defaults env_keep += "PROCESSDIR" Defaults env_keep += "CONTENTDIR" Defaults env_keep += "UPLOADDIR" Defaults env_keep += "DOCKER_PROCESSING_VOLUME"

```

replacing [PROCESSDIR] with the full path to the processing directory.

Docker Setup

Prepare the docker daemon by pulling the Chirun image on the server. For example, log into the server as the processing user and run the command: $ docker pull chirun/chirun-docker:latest

Admin Directory Setup

The web server's rewriting engine should be used to direct all requests of the form lti/content/[...] to lti/index.php?req_content=[...]. In addition, the following directories should be made forbidden for public access:

The path WEBPATH/admin should also be protected and allow only server administrator access. An example Apache setup using Basic Authentication is shown below.

<Location /> Require all granted DirectorySlash Off RewriteEngine on RewriteRule /lti/content/(.*)$ /lti/index.php?req_content=$1 [L,QSA] </Location> <Location /lti/upload> Require all denied </Location> <Location /lti/process> Require all denied </Location> <Location /lti/lib> Require all denied </Location> <Location /lti/admin> AuthType Basic AuthName "Restricted admin section" AuthUserFile /etc/apache2/.htpasswd Require user admin </Location>

In this example a username and password for admin access can be setup by running the following command on the server,

```

htpasswd /etc/apache2/.htpasswd admin

```

LTI Setup

To use the Chirun LTI tool with your VLE, an administrator will need to add the tool to your own instance of the VLE. To do this, the VLE needs to be setup beforehand as a tool consumer in the admin panel accessible on your web server at https://chirun.example.com/lti/admin/.

Create a Name, Key, and Secret for your VLE using the Add New Consumer form on the admin page, and then forward that information on to your VLE administrator to be added as an external LTI tool. They might also need the URL for the LTI XML configuration: https://chirun.example.com/lti/xml/ or the LTI launch URL, https://chirun.example.com/lti/connect.php.

Build Process Information

When content is uploaded to the LTI tool for processing, the following series of steps occurs.

Other Information

The UPLOADDIR directory should be emptied periodically to avoid filling the disk. For example, this can be handled by adding a cron job or systemd timer for the programs user.

An example command that clears the upload directory of all files could be,

find [INSTALLDIR]/upload/ -mindepth 1 -maxdepth 1 -exec rm -r -- {} +

replacing [INSTALLDIR] with the full path to the install directory. The find command can be tweaked with arguments such as -mtime to more finely tune what files are deleted.