Running Your Own Instance

Using MySQL

By default, OpenBench runs using sqlite3. This database is perfectly fine for local use, and even is quite resilient on instances with only a few dozen machines. However, best practices, and larger instances, would encourage the use of MySQL, or some other database. Instructions for MySQL are provided here, as the schema of sqlite3 can be loaded directly into MySQL. A solution like MonogoDB would require additional efforts, if porting from an existing sqlite3 database.

The instructions below assume you are working on a recent Ubuntu system. Most of the instructions are fairly general, but may change depending on the platform you are on. If you are an experienced user of MySQL, then these instructions will likely be beneath you, and you need only look at the Django specific changes in OpenSite/settings.py, listed lasted later on.

Step 1. Install python-mysqlclient

In order to interface with MySQL, Django relies on the mysqlclient pip3 package. This can be installed via pip3 install mysqlclient. Below are some potential errors that you may encounter.

If you encounter Exception: Can not find valid pkg-config name, you can try to update some non-python packages to resolve dependency issues with sudo apt-get install python3-dev default-libmysqlclient-dev.

If this still does not work, you'll want to explicitly set MYSQLCLIENT_CFLAGS and MYSQLCLIENT_LDFLAGS, as per the error message. The following is an example that works on a typical Ubuntu system. sudo MYSQLCLIENT_CFLAGS="-I/usr/include/mysql" MYSQLCLIENT_LDFLAGS="-L/usr/lib/x86_64-linux-gnu -lmysqlclient". You'll want to verify that the file paths are correct.

After attempting any of the remedies, try again to install the python-mysqlclient package.

Step 2. Backup the sqlite3 Database

If you are attempting to port from an sqlite3 database to a MySQL database, you'll want to dump the database to a json file as follows: python3 manage.py dumpdata > db.json. This will dump some extra fields, which we will delete later on when importing the database to MySQL.

Step 3. Install MySQL, and create a new Database

$ sudo apt install mysql-server
$ sudo mysql_secure_installation
$ sudo systemctl start mysql
$ sudo systemctl enable mysql

If mysql_secure_installation did not prompt you to set a root password, you'll need to run the following to do so:

$ sudo mysql
ALTER USER 'root'@'localhost' IDENTIFIED WITH mysql_native_password BY '<password>'
FLUSH PRIVILEGES;
exit

Finally, we create the database:

$ mysql -u root -p
CREATE DATABASE openbench;

Step 4. Update OpenSite/settings.py

You'll want to replace the default config for DATABASES = to be something like below. You are encouraged to use a solution that does not involve placing the MySQL password inside of the source file. But for ease of explanation, it is done here.

DATABASES = {
    'default': {
        'ENGINE'  : 'django.db.backends.mysql',
        'NAME'    : 'openbench',
        'USER'    : 'root',
        'PASSWORD': '<password>',
        'HOST'    : 'localhost',  # Change to your MySQL server's host
        'PORT'    : '3306',       # Change to your MySQL server's port
    }
}

Step 5. Import the existing Database

$ python3 manage.py migrate
$ python3 manage.py migrate --run-syncdb

When importing the database, you'll need to remove some objects that are going to create conflicts.

$ python3 manage.py shell
>>> from django.contrib.contenttypes.models import ContentType
>>> ContentType.objects.all().delete()
>>> quit()

Finally, pull in the data with python3 manage.py loaddata db.json