Welcome to the ORB documentation

Contents:

Managing an ORB installation

Content Review Process

https://www.youtube.com/watch?v=D7dBrnGFurQ

ORB Knowledge Management Tasks

All of the management tasks below are done from the ORB admin pages (https://health-orb.org/admin/) and you will need to be an admin user to be able to access these pages, or perform any of the tasks listed below.

User/Permissions Management

Search for a user
  • Go to the ORB admin pages
  • Under the Authentication and Authorization section select ‘Users’
  • You can search based on name, username or email address
Update a users information/change password
  • Find the user you’d like to update (Search for a user)
  • Click to edit their details
  • From here you can update their information and change their password
  • Click save when finished
Add a new content reviewer

The new reviewer should register on ORB first and let us have their username so we can then assign them permissions.

  • Go to the ORB admin pages
  • Under the ORB section select ‘User profiles’
  • Search or browse for the user and click to edit their details
  • Under the reviewer roles, select the role(s) to give this user
  • Click ‘save’
Give access to organisation analytics

Users can be given permissions to view the analytics for all the resources published under their organisations.

  • Go to the ORB admin pages
  • Under the ORB section select ‘Tag Owners’
  • Click on ‘Add tag owner’ and select the user and tag to give permissions to, then save

Usually we’d give users access to tags that are organisations, although you could assign users to any tag.

View Content Reviewers

If you need to find out who is currently listed as being a content reviewer, and for which roles:

  • Go to the ORB admin pages
  • Under the ORB section select ‘User profiles’
  • From the filtering menu on the right hand side, you can filter the users by the reviewer roles

Health Domain Management

Add a new health domain
  • Go to the ORB admin pages
  • Under the ORB section select ‘Tags’
  • Select ‘Add Tag’ button (top right of screen)
  • For the category, select ‘health domain’
  • Add the name of the new name in both the ‘name’ and ‘name [en]’ fields
  • Select your user id as both the create and update user
  • Update the ‘order by’ field to reflect where in the list of health domains you would like the new one to appear - if you are placing it between existing domains, you should also update the order by for the existing domains to ensure consistency in display.
  • Untick the ‘published’ checkbox if you would like to add some resources to the domain before it appears on the homepage. Once you are ready to publish the domain, just tick this box.
  • Click ‘save’

Resource/Toolkit Management

Remove/Hide a resource

Usually it will be best to just hide a resource, rather than delete it, since deleting it will remove all of the statistics and other information that is associated with a resource.

  • Go to the ORB admin pages
  • Under the ORB section select ‘Resources’
  • Search or browse for the resource and click to edit the details
  • Change the status to either ‘pending’, ‘rejected’ or ‘archived’ (‘archived’ option coming soon)
  • Click save

To completely delete the resource, from the edit page, there is an option to delete the resource.

Create/Update a collection of resources

Collections may be resources that are part of a particular curriculum (eg OpenWASH).

  • Go to the ORB admin pages
  • Under the ORB section select ‘Collections’
  • Either click to edit an existing collection, or click to ‘Add Collection’
  • Enter a title and description and then save

Now to add/edit the resources in the collection:

  • Go to the ORB admin pages
  • Under the ORB section select ‘Collection resources’
  • Click on ‘Add Collection resource’
  • Select the resource and the collection to add it to, optionally add an ‘order by’ number
  • Click save, repeat for each resource to add to the collection
Add or update a toolkit
  • Go to the ORB admin pages
  • Under the ‘Toolkits’ section select ‘Toolkits’
  • Search or browse for the toolkit and click to edit the details
Manage translations

The documentation for managing the internationalisation and translations is described in the Internationalization and Translation section.

Tag Management (incl. Languages & Geographies)

Update the info/image for a tag
  • Go to the ORB admin pages
  • Under the ORB section select ‘Tags’
  • Browse or search for the tag to update and click to edit it
  • You can upload a new image or change the information for the tag
  • For the image files, ORB will automatically resize and crop (if necessary) any images files for display on the site
  • Click ‘save’
Update logo and information for an organisation

All organisations are stored as ‘tags’, see Update the info/image for a tag

Update the icon for geography or language

All geographies and languages are stored as ‘tags’, see Update the info/image for a tag

ORB Peer Network - orb.peers

synopsis:Shared data across a network of peers

The ORB API provides a way for data on an ORB site to be accessed programmatically. This allows for other one ORB instance to download resources from another, syncing resources across a network of ORB peers.

The starting requirement is API access to the target ORB (e.g. the global mPowering ORB).

Setting up peers

A peer is added to your ORB instance by adding three data items:

  • host name
  • user name
  • API key

This can be done from the Django admin or using a management command, add_peer.

The management command is especially helpful for automating setup of an ORB instance.

Note that the API key is stored and read in plaintext.

Syncing data

To sync data from a configured ORB peer, use the sync_peer_resources management command. This can be used without arguments or the numeric primary keys of configured peers can be provided to sync only from select peers.

The primary keys can be discovered via the Django admin or by using the management command list_peers.

How syncing works

The core action of the peer data sync is to copy or update resources from the remote ORB to the local ORB.

Global IDs

Every resource has a globally unique identifier which is copied with synced resources. This ensures that a resource can be downloaded from one ORB and from yet another and still retain a non-overridable ID that tracks it across instances. This GUID is used to identify resources for update.

Pending by default

Resources on the remote ORB that are not present on the local ORB are copied to new resources in the local ORB and placed in the pending state. These must be reviewed by a content administrator prior to becoming public on the local ORB.

Updates

Updates to a remote resource will overwrite any local changes.

Languages

ORB instances may have resources available with multiple language translations. Only data for languages explicitly supported on the local ORB instance will be synced. Other languages will be ignored.

Module overview

ORB Analytics

ORB stores a lot of data about how the site and resources are accessed.

Internationalization and Translation

Managing Translations

ORB Interface

ORB Database Translations

Internationalization - Technical Set-up

Translating source content

Todo. See the Django i18n docs in the meantime!

Translating database content

Content in the database is user created content and cannot be translated using the normal gettext interface that Django provides. Instead a package called django-modeltranslation provides for language-specific mirrored fields in the database that allow for content specific translation.

Specifying models and fields for translation

Translations are registered much like admin.ModelAdmin classes in a translation.py file in each app root. For each model to translate create a translation class based on the TranslationOptions class, and specify the fields.:

from modeltranslation.translator import translator, TranslationOptions
from orb import models

class CategoryTranslation(TranslationOptions):
    fields = ('name',)

translator.register(models.Category, CategoryTranslation)

In the above example the CategoryTranslation class specifies only that the name field should be translated, and the Category model is registered with this translation options class.

Realizing new translation fields

Field registration is by itself an insufficient step. It is like adding new fields to a model - you still need to create a database migration to realize the field(s). This is straightforward 3-step process.

  1. Run makemigrations for the app in question
  2. Apply the migrations with migrate
  3. Update the translation fields with the update_translation_fields command

The third step is important because of how modeltranslations pulls data out of the database. If you have a name field and then decide to translate it, then presuming an English language site with Spanish and Portuguese available as well, you will have four database fields: name, name_en, name_es, and name_pt.

Note

Dialect or region specific codes will have their own fields if specified, e.g. name_pt_br.

Once active, modeltranslation will look for the name value in name_en! Running update_translation_fields updates those values.

A convenience command has been added to the Makefile:

make register-languages

This will create migrations, apply them, and then update the translation fields.

Important

You must create new migrations any time you register new models/fields and also if you change the project LANGUAGES setting, so that database fields are available for each language.

Source code & Installation

The ORB site source code is available on GitHub: https://github.com/mPowering/django-orb

The site is built using the Django framework.

Server set-up and management

Email Setup

SSL Certificates

Search Engine

Backups

System updates

ORB Settings

ORB_INFO_EMAIL
‘orb@example.com’
ORB_GOOGLE_ANALYTICS_CODE
Google Analytics tracking code
ORB_PAGINATOR_DEFAULT
20
ORB_RESOURCE_DESCRIPTION_MAX_WORDS
150
ORB_RESOURCE_MIN_RATINGS
3
SITE_HTTP_PROTOCOL
string value which should be either ‘http’ or ‘https’ (email tasks will default to ‘http’ if this is not defined)
STAGING
False # used for version context processor
TASK_UPLOAD_FILE_MAX_SIZE
maximum file upload size in bytes
TASK_UPLOAD_FILE_TYPE_BLACKLIST
list of file types (MIME types) to exclude

Change log

v2.8.0 - not yet released

v2.7.0 - Released 3 Apr 2018

v2.6.0 - Released 22 Feb 2018

v2.5.2 - Released 4 May 2017

v2.5.1 - Released 26 Apr 2017

v2.5.0 - Released 25 Apr 2017

v2.4.0 - Released 17 Apr 2017

v2.3.0 - Released 27 Mar 2017

v2.2.2 - released 5 Dec 2016

v2.2.1 - released 3 May 2016

v2.2.0 - released 23 Apr 2016

v2.1.0 - released 4 Nov 2015

v2.0.0 - released 14 Oct 2015

v1.1.0 - released 11th Aug 2015

v1.0.2

v1.0.1

28 May 2015

27 May 2015

25 May 2015

21 May 2015

19 May 2015

15 May 2015

14 May 2015

13 May 2015

12 May 2015

11 May 2015

8 May 2015

7 May 2015

6 May 2015

5 May 2015

4 May 2015

1 May 2015

30 Apr 2015

29 Apr 2015

28 Apr 2015

27 Apr 2015

26 Apr 2015

24 Apr 2015

22 Apr 2015

21 Apr 2015

20 Apr 2015

18 Apr 2015

17 Apr 2015

15 Apr 2015

14 Apr 2015

13 Apr 2015

pre 12 Apr 2015

Virus Checking

Since the ORB platform allows users to upload files, these files should be checked for viruses.

Even if an uploaded file contains a virus that may not harm the server operating system, users who download the files may be using operating systems which are susceptible to the virus.

The ORB server uses the ClamAV open source antivirus engine to scan uploaded files.

A sample shell script to run the virus checker and email the results is included in the utils directory (virus-scan.sh)

REST API

The REST API is still under development.

There is an example of the search API running at: http://alexlittle.net/mpowering/examples/search.php

Current versions of the API helper libraries can be found at:

These helper libraries also include some examples of how to use the API.

Accessing the API

Note

Currently, for any REST API method requests, you will need to contact us so we can enable your account for these API methods.

To make any request to the API, you must supply your username and API Key (your API key can be found on your ORB profile page).

Resource

For getting the information about a resource, submitting a new resource or updating an existing resource

Endpoint: /api/v1/resource/

Allowed methods:

  • GET
  • POST
  • PUT

Required params (POST and PUT):

  • title
  • description

Resource Tag

Endpoint: /api/v1/resourcetag/

Allowed methods:

  • GET
  • POST
  • PUT

Resource Tag

Endpoint: /api/v1/resourcetag/

Allowed methods:

  • GET
  • POST
  • DELETE

Resource File

Endpoint: /api/v1/resourcefile/

Allowed methods:

  • GET
  • DELETE

Resource URL

Endpoint: /api/v1/resourceurl/

Allowed methods:

  • GET
  • DELETE

Resource Image Upload

Endpoint: /api/upload/image/

Allowed methods:

  • POST

Resource File Upload

Endpoint: /api/upload/file/

Allowed methods:

  • POST

Tag

Endpoint: /api/v1/tag/

Allowed methods:

  • GET
  • POST

Tags

Endpoint: /api/v1/tags/

Allowed methods:

  • GET

Tags Resource

Endpoint: /api/v1/tagsresource/

Allowed methods:

  • GET

ORB Roadmap

OpenDeliver

AMI Installation

To assist with setting up the Open Deliver process, mPowering has created an Amazon Machine Image (AMI) on Amazon Web Services (AWS), which already has the 3 key components set up and configured on one machine:

  • ORB
  • Moodle
  • OppiaMobile server

The specific versions and machine info can be found below.

Pre-requisites

You will need to have:

  • An AWS account, see: https://aws.amazon.com/ - you will need a debit/credit card for the monthly charges for hosting and bandwidth.
  • Some experience in using the command line/SSH to log into and configure the server, and experience in server and MySQL database management
  • A domain name registered that you can point to your new services. If you don’t have this then please ask mPowering about how we can help with providing a sub-domain.

Installation

  1. Log into your AWS account and go to EC2 services
  2. From ‘Instances’ select ‘Launch Instance’
  3. Select ‘Community AMIs’ and search for ‘OpenDeliver’ - you may need to select the zone to be ‘US East’ for the AMI to appear in the search results.
  4. Follow the instructions to create and launch the instance. Remember to keep the server keys safe and secure, you will need these to log into your machine and, if lost, cannot be recovered.

Once the machine is up and running you can log in using SSH.

Post Installation Set-up & Configuration (Required)

The following must be set up and configured to ensure your machine is accessible and secure.

Update database passwords

All the database passwords are set to ‘opendeliver’ - all these must be changed to make your server is secure. The following passwords and configurations should be changed (using the MySQL command line):

  • MySQL root password - using SET PASSWORD FOR 'root'@'localhost' = PASSWORD('<new-password>');
  • ORB database password - using SET PASSWORD for 'mpower'@'localhost' = PASSWORD('<new-password>');
  • Moodle database password - using SET PASSWORD for 'moodleuser'@'localhost' = PASSWORD('<new-password>');
  • Oppia database password - using SET PASSWORD for 'oppiauser'@'localhost' = PASSWORD('<new-password>');

After changing the database passwords remember to run flush privileges.

Now update the site database configurations to use your new passwords:

  • ORB - edit /home/www/platform/mpower/mpower/settings.py
  • Moodle - edit /home/www/moodle/config.php
  • Oppia - edit /home/www/oppia/oppia_core/settings.py
Assign static IP (elastic IP)

In AWS you should create an Elastic IP and assign it to your newly created machine. This ensures that when you assign a domain name, the IP address will be static and so not change if the machine is stopped.

Assign domain names

Each component will need it’s own sub-domain (or domain) name. Once you have assigned the new elastic/static IP address to your domain & sub-domains, then update the following:

ORB:

  • Apache configuration - update ServerName in /etc/apache2/sites-available/health-orb.conf and /etc/apache2/sites-available/health-orb-ssl.conf
  • Django - update ALLOWED_HOSTS in /home/www/platform/mpower/mpower/settings.py

Moodle:

  • Apache configuration - update ServerName and RedirectPermanent in /etc/apache2/sites-available/moodle.opendeliver.conf and ServerName in /etc/apache2/sites-available/moodle.opendeliver-le-ssl.conf
  • config - update $CFG->wwwroot in /home/www/moodle/config.php

Oppia:

  • Apache configuration - update ServerName in /etc/apache2/sites-available/oppia.conf and /etc/apache2/sites-available/oppia-ssl.conf
  • Django - update ALLOWED_HOSTS in /home/www/oppia/oppia_core/settings.py
Install SSL certificates

All the components are set up to use SSL certificates (i.e. using the secure https). ORB can be accessed either through non-secure http or through secure https, but Moodle and Oppia are set to to be accessed via https only (anyone using http for either of these will be re-directed to the secure version).

The SSL certificates are generated using the free service LetsEncrypt (https://letsencrypt.org/) and will need to be updated to match your (sub-)domain names.

  • Run sudo letsencrypt --apache certonly, you’ll need to run this 3 times, once for each of the 3 domains

  • Edit the apache site configuration files to update the SSL key file paths (the directory paths are also given at the end of running letsencrypt):

    • For ORB (/etc/apache2/sites-available/health-orb-ssl.conf):

      SSLCertificateFile /etc/letsencrypt/live/<insert-ORB-domain-name-here>/fullchain.pem

      SSLCertificateKeyFile /etc/letsencrypt/live/<insert-ORB-domain-name-here>/privkey.pem

    • For Moodle (/etc/apache2/sites-available/moodle.opendeliver-le-ssl.conf):

      SSLCertificateFile /etc/letsencrypt/live/<insert-Moodle-domain-name-here>/fullchain.pem

      SSLCertificateKeyFile /etc/letsencrypt/live/<insert-Moodle-domain-name-here>/privkey.pem

    • For Oppia (/etc/apache2/sites-available/oppia-ssl.conf):

      SSLCertificateFile /etc/letsencrypt/live/<insert-Oppia-domain-name-here>/fullchain.pem

      SSLCertificateKeyFile /etc/letsencrypt/live/<insert-Oppia-domain-name-here>/privkey.pem

  • Now enable the SSL sites by running:

    • sudo a2ensite health-orb-ssl.conf
    • sudo a2ensite moodle.opendeliver-le-ssl.conf
    • sudo a2ensite oppia-ssl.conf

  • Finally restart apache with sudo service apache2 restart

You should now have all 3 sites running and available with your domain names and with SSL enabled.

Update component admin passwords

The administrator passwords for each of ORB, Moodle and Oppia should now be updated:

  • For ORB, log into the site with username/password ‘admin’/’opendeliver’, then go the profile page (under ‘My ORB’ in the menu bar) and update the password
  • For Moodle, log into the site with username/password ‘admin’/’OpenDeliver1!’, then go to the profile page to update the password
  • For Oppia, log into the site with username/password ‘admin’/’opendeliver’, then go the profile page (under ‘My Oppia’ in the menu bar) and update the password

Post Installation Set-up & Configuration (highly recommended)

Email configuration

To enable the sending of emails (for example password reset and notification messages), you will need to set up and configure the AWS SES service (https://aws.amazon.com/ses/)

Reserved instance

Assuming you are planning to have the site running 24x7, then you should look at purchasing a reserved instance from AWS, as this will be much cheaper than on-demand usage.

Cron tasks

Several scheduled tasks are set up for ORB, Moodle, Oppia, backing up and auto-renewing the SSL certificates, you check and amend the times and frequency these tasks run by looking at the sudo crontab (sudo crontab -e).

Regular Maintenance

All systems need regular, ongoing maintenance to keep them up to date and secure.

Backups

The databases and uploads are backed up regularly (according to the cron schedule), however these backup files are stored on the server (in the directory /home/backup), so you should ensure these are regularly copied off-server, for example by using rsync (https://en.wikipedia.org/wiki/Rsync) to copy the backup files onto another machine/device.

Operating system updates

You should regularly (suggested once per month) ensure that the operating system is kept up to date with the latest bug and security fixes. Use sudo apt-get update then sudo apt-get upgrade on the command line to check for and install any Ubuntu updates

Updates from core code repositories

The AWS AMI is a point-in-time snapshot of the core code for ORB, Moodle and OppiaMobile, so you should ensure that the code for each of these is kept up to date.

Updating OpenDeliver AMI Instance

OpenDeliver AMI Versions

OpenDeliver AMI - v3 - released 13 Apr 2017

  • ORB v2.7.0
  • Moodle v3.4
  • OppiaMobile server v0.10.0

OpenDeliver AMI - v3 - released 6 Jul 2017

  • ORB v2.5.2
  • Moodle v3.3
  • OppiaMobile server v0.9.10

OpenDeliver AMI - v2 - released 6 Apr 2017

  • ORB v2.3.0
  • Moodle v3.2.2
  • OppiaMobile server v0.9.8

OpenDeliver AMI - v1 - released Jan 2017

  • ORB v2.2.2
  • Moodle v3.2
  • OppiaMobile server v0.9.8

VirtualBox Download and set up

Updating OpenDeliver VirtualBox Instance

OpenDeliver VirtualBox Versions