Installation process¶
OnTask is a Web application that manages data about learners to provide them with personalised support. For this reason, it is recommended an installation that observes a set of tight security restrictions. Some of these restrictions lie within the scope of the tool, but some other are part of the environment in which the application is installed. We strongly recommend to install OnTask in a web server that uses TTL encryption (HTTPS) to serve all the pages. The application requires exchanging with your browser sensitive information about your session, so the information should be encrypted.
Requirements¶
OnTask has been developed as a Django application. Django is a high-level, python-based web framework that supports a rich set of functionalities typically required in applications like OnTask. But as with many other applications, OnTask requires a set of additional applications for its execution:
- Python 2.7.13 (or later)
- Django (version 1.11 or later)
- Additional django modules (included in the requirements/base.txt) file
- Redis (version 4.0 or later)
- PostgreSQL (version 9.5 or later)
Some of these requirements are (hopefully) properly handled by Python through its package index application pip.
Installing the required tools¶
The following installation steps assume that you are deploying OnTask in a production web server capable of serving pages using the HTTPS protocol.
Install and Configure Redis¶
Download and install redis.
Follow the instructions to configure it to be used by Django.
Test that it executes properly
For OnTask you only need executing in the machine. If you use the default settings, there are not additional changes required in OnTask (the code is alrady using this application internally).
Install and Configure PostgreSQL¶
Download and install postgresql.
Create the role
ontask
with the commandcreateuser
. The role should be able to create new databases but not new roles and you should define a password for the user (usecreateuser --interactive -W
).Adjust the access configuration in postgresql (usually in file
pg_hba.conf
) to allow the newly created user to access databases locally.Create a new database with name
ontask
with thecreatedb
command.Use the client application
psql
to verify that the user has access to the newly created database and can create and delete a new table and run regular queries. Try to connect to the database with the following command:psql -h 127.0.0.1 -U ontask -W ontask
If the client does not connect to the database, review your configuration options.
Install Python¶
In the following sections we assume that you can open a command line interpreter and you can execute the python intepreter.
Download, install and configure OnTask¶
Download or clone_actions a copy of OnTask.
Using a command interpreter, go to the OnTask folder and locate a folder inside it with name
requirements
. Verify that therequirements
folder contains the filesbase.txt
,production.txt
anddevelopment.txt
. The first file contains a list of python modules that are required by OnTask. The second is a set of additional modules to run a production instance, and the third is a list if you intend to run a development instance.If you plan to run a production instance of OnTask execute the command:
pip install -r requirements/production.txt
Alternatively, if you plan to run a development instance of OnTask then execute the commmand:
pip install -r requirements/development.txt
This command traverses a list of libraries and modules and installs them as part of the python libraries in the system. These modules include Django, Django Rest Framework, django braces, etc.
At this point you have the major modules in place. The next steps include the configuration of the Django environment to run OnTask.
If you plan to install a production instance of OnTask, using a plain text
editor (nano, vim, emacs or similar) in a command line interpreter, open the
file manage.py
in the src
folder of the project. Modify line 14
replacing the value "ontask.settings.development"
by
"ontask.settings.production"
. Save and close the file.
Using the same plain text editor create a file with name local.env
in the folder src/ontask/settings
with the following content (note there is
no space between variable names and the equal sign):
TIME_ZONE='[YOUR LOCAL PYTHON TIME ZONE]'
# syntax: DATABASE_URL=postgres://username:password@127.0.0.1:5432/database
DATABASE_URL=postgres://[PSQLUSERNAME]:[PSQLPWD]@127.0.0.1:5432/ontask
SECRET_KEY=
LTI_OAUTH_CREDENTIALS=key1=secret1,key2=secret2
Open a command interpreter and execute the following python command:
python -c 'import tzlocal; print(tzlocal.get_localzone().zone)'
Replace
[YOUR LOCAL PYTHON TIME ZONE]
in thelocal.env
file by the description of your time zone produced by the previous command.Modify the line starting with
DATABASE_URL=
and change the field[PSQLUSERNAME]
with the name of the Postgresql user created in the previous step (the one that could access the ontask database and run queries). If you decided to use a different name for the database, adjust the last part of the line accordingly (replace ontask by the name of your database).Open a command interpreter and execute the following python command:
python -c 'import random; import string; print("".join([random.SystemRandom().choice(string.digits + string.ascii_letters + string.punctuation) for i in range(100)]))'
Copy the long string produced as output and add it at the end of the last line of the file
local.env
. It should look something like (with different content after the equal sign):SECRET_KEY=4o93jf0572094jv...
Modify the line starting with
LTI_OAUTH_CREDENTIALS
and include a comma-sepparated list of pairs key=secret for LTI authentication. See the section Authentication for more details about this type of authentication.Create a new folder with name
logs
in the OnTask top folder (next to therequirements
folder). This folder is different from the folder with the same name in thesrc
folder.If at some point during the following steps you want to reset the content of the database, run the commands
dropdb
andcreatedb
Execute the following commands from the
src
folder to prepare the database initialization:python manage.py makemigrations profiles accounts workflow dataops python manage.py makemigrations table action logs scheduler
Execute the following command to create the database internal structure:
python manage.py migrate
A few messages should appear on the screen related to the initalizaton of the database.
Execute the following command to upload to the platform some initial data structures:
python manage.py runscript -v1 --traceback initial_data
The command should run without any error or exception.
Execute the command to create a superuser account in OnTask:
python manage.py createsuperuser
Remember the data that you enter in this step so that you use it when you enter OnTask with your browser.
Go to the
docs
folder to generate the documentation. Make sure this folder contains the sub-folders with name_static
and_templates
. Execute the command:make html
The documentation is produced by the
sphinx-doc
application and generates the directory_build
. The documentation for the platform is in the folder_build/html
.Copy the entire
html
folder (inside_build
) over to thesrc/static
folder (in Unixcp -r _build/html ../src/static
).From the
src
folder execute the following command to collect and install the static content:python manage.py collectstatic
If you are running a production instance, execute the following command to check the status of the platform:
python manage.py check --deploy
The command should print just one warning about the configuration variable X_FRAME_OPTIONS. If you are running a development instance, you will get various additional warning that are derived most of them from running the instance without HTTPS.
Execute the following command to start the OnTask server:
python manage.py runserver
If there are no errors, the message on the screen should say that your server is running and available in the URL 127.0.0.1:8000
If OnTask is going to be accessed through a web server like Apache or Nginx, stop the application and configure the web server accordingly.
The Administration Pages¶
As many applications developed using Django, OnTask takes full advantage of
the administration pages offered by the framework. The account created with
the command createsuperuser
has complete access to those pages through a
link in the upper right corner of the screen.
These pages offer access to several important operations:
- The elements of each of the models stored in the database (workflows, actions, conditions, columns, etc). Each model has its corresponding page allowing the creation, update and deletion of any object.
- The user information. This is a special model representing the users, their name, credentials, etc. The platform allows the creation of user accounts.
- The group information. The platform differentiates users based on groups. Each group has different functionalities.
Once the instance is running, visit these pages and configure the platform to your needs.
Production Deployment¶
Once OnTask is executing normally, you may configure a web server (nginx, apache or similar) to make it available to a community of users. The instructions to make such deployment are beyond the scope of this manual but they are available for users to consult.
Authentication¶
OnTask comes with three default authentication mechanisms (and are used in
the following order): LTI, REMOTE_USER
and basic authentication.
IMS Learning Tools Interoperability (IMS-LTI). LTI is a standard developed by the IMS Global Leanring Consortium to integrate multiple tools within a learning environment. In LTI terms, OnTask is configured to behave as a tool provider and assumes a tool consumer such as a Learning Management System to invoke its functionality. Any URL in OnTask can be give nto the LTI consumer as the point of access.
Ontask only provides two points of access for LTI requests coming from the consumer. One is the url with suffix
/lti_entry
and the second is the URL provided by the actions to serve the personalised content (accessible through theActions
menu.To allow LTI access you need:
A tool consumer that can be configured to connect with OnTask. This type of configuration is beyond the scope of this manual.
A set of pairs key,value in OnTask to be given to the tool consumers so that together with the URL, they are ready to send the requests. The key/value pairs are specified in the file
local.env
in the foldersrc/ontask/settings
together with other local configuration variables. For example:LTI_OAUTH_CREDENTIALS=key1=secret1,key2=secret2
If you change the values of this variable, you need to restart the server so that the new credentials are in effect.
This authentication has only basic functionality and it is assumed to be used only for learners (not for instructors).
REMOTE_USER
. The second method uses the variable REMOTE_USER that is assumed to be defined by an external application. This method is ideal for environments in which users are already authenticated and are redirected to the OnTask pages (for example, using SAML). If OnTask receives a request from a non-existent user through this channel, it automatically and transparently creates a new user in the platform with the user name stored in theREMOTE_USER
variable. OnTask relies on emails as the username differentiator, so if you plan to use this authentication method make sure the value ofREMOTE_USER
is the email.Basic authentication. If the variable
REMOTE_USER
is not set in the internal environment of Django where the web requests are served, OnTask resorts to conventional authentication requiring email and password. These credentials are stored in the internal database managed by OnTask.
There are other possibilities to handle user authentication (LDAP, AD, etc.) but they require ad-hoc customizations in the tool and are not provided as out-of-the-box solutions.
Scheduling tasks¶
OnTask allows to program certain tasks to execute at some point in the
future. This functionality is implemented using a combination of persistent
storage (the database), and a time-based job scheduler external to the tool.
Time-based job schedulers are present in most operating systems (cron
in Unix/Linux, or at
in Windows). OnTask provides the functionality to
describe the task to execute and assing a date and time. Additionally, the
tool has a script that checks the date/time, selects the appropriate task,
and executes it. These instructions describe the configuration assuming an
underlying Linux/Unix architecture using crontab
.
Create a crontab file for the user running the server in your production environment with the following content:
MAILTO="[ADMIN EMAIL ADDRESS]"
PATH=/usr/local/sbin:/usr/local/sbin:/usr/local/bin:/usr/bin:/bin:/usr/sbin:/sbin
SHELL=/bin/bash
ONTASK_PROJECT=[PATH TO ONTASK PROJECT ROOT]
0,15,30,45 * * * * python ${ONTASK_PROJECT}/src/manage.py runscript scheduler_script -v3 --traceback --script-args="-d" > [CRONTAB LOG] 2>&1
Modify the previous script with the following information:
- In the first line change the email address by an address to receive the
notifications produced by
crontab
. The server running the application needs to have the capacity to send emails. - Make sure the variable
PATH
contains the path to executepython
. - Define the variable
SHELL
to point to the shell to use to executepython
. - Change the value of the variable
ONTASK_PROJECT
to point to the root of OnTask (the folder containing the source code). - In the last line replace
[CRONTAB LOG]
with a file to capture the output that the screen would write to a regular terminal. We recommend this file to be in a temporary directory.
The script scheduler_scrip
has been configured to print messages through
a logger that writes the messages to the file script.log
in the logs
folder.
The remaining parameter to adjust is the frequency in which the script
scheduler_script
runs. In the example above, the script executes every
15 minutes (at minutes 0, 15, 30 and 45 minutes in the hour). Adjust this
frequency to suit your needs. Once adjusted, go to the admin menu in OnTask,
open the section with name Core Configuration, click in the preferences
and adjust the value of the Minute interval to program scheduled tasks and
match it (in minutes) to the interval reflected in the crontab.