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: 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
> 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

    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 to, eg: by using:

    $ cp
  6. Open the 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/

  7. Save your 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:

  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 migrate
  3. Load initial data:

    (env)$ python loaddata oppia/fixtures/default_badges.json
    (env)$ python loaddata oppia/fixtures/default_gamification_events.json
  4. Compile the SCSS file:

    (env)$ python compilescss
  5. Copy the static files with:

    (env)$ python collectstatic
  6. Create a first admin user with:

    (env)$ python 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.

8. Test running the server locally

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

(env)$ python 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/
        WSGIPassAuthorization On

        <Directory /home/oppia/django-oppia/oppiamobile/>
                        Require all granted

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

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

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


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.

12. Set up cron tasks

There are 2 cron 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.

Here are 2 example files that you can use, for each of these cron tasks. We recommend putting these files in your /home/oppia/ directory.


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

python django-oppia/ oppiacron --hours=48


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

python django-oppia/ update_summaries

Edit your crontab to run these scripts 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