Server - Manual Installation

To manual install and run an OppiaMobile server, e.g. as a local development server or as live server running on a locally hosted server. Please follow the instructions below.

Prerequisites

It would be helpful if you had some system admin/set up experience before, and please note that these instructions are based on using Ubuntu as the operating system, with MySQL for the database server and Apache2 as the webserver. If you are using a different operating system, database or webserver, then some of the exact commands may differ a little.

You should have some familiarity with Git and have this installed on your machine.

1. Set up empty database

We generally use MySQL for the database, but Oppia will support any database platform that Django supports (see: https://docs.djangoproject.com/en/2.1/ref/databases/ for more detailed notes)

In the MySQL command line, run:

> create database oppia default character set utf8mb4;
> grant all privileges on oppia.* to 'oppiauser'@'localhost' identified by
        'yourpassword';
> flush privileges;
> quit

The database name, username and password can be whatever you like.

2. Clone the code and add custom settings

Select or create a suitable directory on your file system, for the rest of this setup. We use /home/oppia/, but you may prefer something like /var/html/oppia/. The rest of these instructions will assume you are using /home/oppia/, so edit any of the following commands/settings as necessary if you’re using something different.

1. Navigate to your selected directory

2. Run:

   $ git clone https://github.com/DigitalCampus/django-oppia.git
   

   If you have your own fork of the Oppia code, then replace the location with your own fork’s url.

3. This will create a directory /home/oppia/django-oppia/ with the latest stable release version of the Oppia server code.

4. Navigate to the /home/oppia/django-oppia/oppiamobile/ directory

5. Copy the settings_secret.py.template to settings_secret.py, eg: by using:

   $ cp settings_secret.py.template settings_secret.py
   

6. Open the settings_secret.py file in your favourite text editor and update at least the following settings:

   1. Database name, user, password (that you created in step 1 above)

   2. SECRET_KEY: This can be anything you like, generally a long list of random characters.

   3. ADMINS and SERVER_EMAIL: update these to your system admin details

   4. ALLOWED_HOSTS: to be able to access externally the Django app, you need to add your hostname to the list of allowed hosts. You can also use the * wildcard in a debug server.

   In this file you can also override any of the settings in /home/oppia/django-oppia/oppiamobile/settings.py

7. Save your settings_secret.py file

3. Install Ubuntu packages

Some additional packages are required that are not included on a default installation of Ubuntu, so you’ll need to install these:

1. sudo apt-get install python3-mysqldb python3-dev libpython3-dev - extra python3 packages

2. sudo apt-get install libjpeg-dev zlib1g-dev - extra packages for images

3. sudo apt-get install ffmpeg - for analysing uploaded media files

4. Set up virtualenv and packages

VirtualEnv is a way to sandbox your python libraries so they are not affected by other updates or versions that you may be using for other services and applications on your machine. You don’t have to use this, but it is very strongly recommended that you download and install this to use.

1. Navigate to /home/oppia/ and run:

   $ virtualenv -p /usr/bin/python3 env
   

2. Run:

   $ source env/bin/activate
   

   Your command line should now look something like:

   (env)$
   

3. Install the required packages for the Oppia server by running:

   (env)$ pip install -r django-oppia/requirements.txt
   

   This may take some time as it downloads and sets up all the necessary python libraries that are required by the Oppia server.

4. Install a database connector, since we use MySQL, the command below is specifically for that database server. If you are using a different database server, then use the appropriate one for your database server:

   (env)$ pip install mysqlclient
   

5. Some python packages are compiled against system libraries (for example, the Pillow imaging library). If the previous command fails at some of the installations, try installing these packages and then try again.:

   (env)$ sudo apt-get install build-essential checkinstall
   libreadline-gplv2-dev openssl libncursesw5-dev libgdbm-dev
   libc6-dev libbz2-dev python-dev libmysqlclient-dev
   

   In some cases, it will be required to perform a system reboot for this changes to be applied.

6. You should now have all the required libraries set up and installed.

5. Set up other directories and permissions

Create directories for media, static and uploads by running (from /home/oppia/):

$ mkdir media
$ mkdir static
$ mkdir upload

If you are going to run this Oppia server as a live server, you should make sure that your webserver user (eg www-data) had read and write access to all these directories.

6. Initialise the database and add admin user

Now to create the database structure and an initial admin user.

1. Navigate the /home/oppia/django-oppia/ directory

2. Create the database by running:

   (env)$ python manage.py migrate
   

3. Load initial data:

   (env)$ python manage.py loaddata oppia/fixtures/default_badges.json
   (env)$ python manage.py loaddata oppia/fixtures/default_gamification_events.json
   

4. Compile the SCSS file:

   (env)$ python manage.py compilescss
   

5. Copy the static files with:

   (env)$ python manage.py collectstatic
   

6. Create a first admin user with:

   (env)$ python manage.py createsuperuser
   

   and follow the instructions. After you have create an admin on the command line, you will also need to create a user profile for them. To do this go to the Django admin at <your-site>/admin, log in and add a user profile record.

7. Run the tests (optional but recommended)

To check that everything has been set up and installed correctly, you can run the automated tests using:

(env)$ python manage.py test

8. Test running the server locally

Check that the server will run properly on the local machine, by running:

(env)$ python manage.py runserver

Then, in the web browser on the same machine, open:

http://localhost:8000

9. Configure web server (for live servers)

If the Oppia server you are setting up is to run as a live server, then you will need to configure your web server.

As mentioned above, these instructions assume that you are using Apache webserver, and we use the mod_wsgi package for serving python applications via Apache, so before proceeding, ensure that you have mod_wsgi installed and enabled for your Apache server.

To install and enable WSGI for Python 3 and Apache, run:

$ sudo apt-get install libapache2-mod-wsgi-py3

Here is an example Apache config file that you can use and adapt:

<VirtualHost *:80>

        ServerName localhost.oppia
        WSGIDaemonProcess localhost.oppia python-path=/home/oppia/django-oppia:/home/oppia/env/lib/python3.6/site-packages
        WSGIProcessGroup localhost.oppia
        WSGIScriptAlias / /home/oppia/django-oppia/oppiamobile/wsgi.py
        WSGIPassAuthorization On

        <Directory /home/oppia/django-oppia/oppiamobile/>
                <Files wsgi.py>
                        Require all granted
                </Files>
        </Directory>

        Alias /media /home/oppia/media/
        <Directory "/home/oppia/media/">
                Options MultiViews FollowSymLinks
                AllowOverride None
                Require all granted
        </Directory>

        Alias /static /home/oppia/static/
        <Directory "/home/oppia/static/">
                Options MultiViews FollowSymLinks
                AllowOverride None
                Require all granted
        </Directory>



        LogLevel warn
        ErrorLog /var/log/apache2/oppia-error.log
        CustomLog /var/log/apache2/oppia-access.log combined

</VirtualHost>

Replace the ServerName localhost.oppia with your site’s domain name and adjust any instances of /home/oppia/ with the directory you used for installing.

10. Configure SSL (recommended)

It is recommended to set up SSL (HTTPS) certificates for the connection between users devices and the server.

You can use LetsEncrypt to set up free SSL certificates.

11. Configure email (recommended)

In your settings_secret.py file, edit the EMAIL_BACKEND and SERVER_EMAIL to configure sending emails from Oppia.

Exactly how these need to be configured and set up will depend on your email backend (see: https://docs.djangoproject.com/en/2.2/topics/email/#email-backends). For live servers you are most likely to want to use the SMTP backend.

12. Set up cron task

There are 2 scheduled tasks, one does the processing for awarding badges and general maintenance (eg clearing old user sessions and temporary files), and the other to generate the cached data for displaying the dashboard data.

These can be run as a single cron task. We recommend putting this file in your /home/oppia/ directory. oppia-cron.sh:

#!/bin/bash

cd /home/oppia/
source env/bin/activate

python django-oppia/manage.py oppiacron --hours=48
python django-oppia/manage.py update_summaries

Edit the sudo users crontab to run this script regularly - at least once per hour.

13. Contribute!

If you find issues and have fixed them or have added extra features/ functionality, then please send us a pull request to integrate into the core server code so everyone can benefit. If you find an issue, but aren’t sure how to fix it, then please file an issue on Github

If you need any help, then please post a message in the OppiaMobile Community site