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.
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.
Navigate to your selected directory
$ 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.
This will create a directory
/home/oppia/django-oppia/with the latest stable release version of the Oppia server code.
Navigate to the
settings_secret.py, eg: by using:
$ cp settings_secret.py.template settings_secret.py
settings_secret.pyfile in your favourite text editor and update at least the following settings:
Database name, user, password (that you created in step 1 above)
SECRET_KEY: This can be anything you like, generally a long list of random characters.
SERVER_EMAIL: update these to your system admin details
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
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:
sudo apt-get install python3-mysqldb python3-dev libpython3-dev- extra python3 packages
sudo apt-get install libjpeg-dev zlib1g-dev- extra packages for images
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.
$ virtualenv -p /usr/bin/python3 env
$ source env/bin/activate
Your command line should now look something like:
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.
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
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.
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
$ 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.
Create the database by running:
(env)$ python manage.py migrate
Load initial data:
(env)$ python manage.py loaddata oppia/fixtures/default_badges.json (env)$ python manage.py loaddata oppia/fixtures/default_gamification_events.json
Compile the SCSS file:
(env)$ python manage.py compilescss
Copy the static files with:
(env)$ python manage.py collectstatic
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:
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>
localhost.oppia with your site’s domain name and
adjust any instances of
/home/oppia/ with the directory you used for
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)
settings_secret.py file, edit the
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
#!/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.
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