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.
Navigate to your selected directory
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.
This will create a directory
/home/oppia/django-oppia/
with the latest stable release version of the Oppia server code.Navigate to the
/home/oppia/django-oppia/oppiamobile/
directoryCopy the
settings_secret.py.template
tosettings_secret.py
, eg: by using:$ cp settings_secret.py.template settings_secret.py
Open the
settings_secret.py
file 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.ADMINS
andSERVER_EMAIL
: update these to your system admin detailsALLOWED_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
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:
sudo apt-get install python3-mysqldb python3-dev libpython3-dev
- extra python3 packagessudo apt-get install libjpeg-dev zlib1g-dev
- extra packages for imagessudo 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.
Navigate to
/home/oppia/
and run:$ virtualenv -p /usr/bin/python3 env
Run:
$ source env/bin/activate
Your command line should now look something like:
(env)$
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
/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.
Navigate the
/home/oppia/django-oppia/
directoryCreate 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:
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