Developing myRobogals on a Mac

Here's how to set up a local development copy of myRobogals on macOS.

This guide will be helpful for Linux users too - it is much the same except that instead of Homebrew you will use the package manager relevant to your Linux distro, and the package names may be different.

Clone the myRobogals repository

Fork the myRobogals repository from Github to create your own copy of it, then clone that copy onto your local machine. The following pages may be helpful:

Github: Set up git

Github: Fork a repo

myRobogals repo

(Optional) Installing MySQL using Homebrew

If you don't want to install MySQL, you can use the default SQLite that Django provides and skip this part. See "Generate the settings file" section for more information.

If you don't have Homebrew, install it be entering this command:

/usr/bin/ruby -e "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/master/install)"

After Homebrew is installed, make sure all the packages are up to date by typing

brew update

Next, you will need to install MySQL through Homebrew and follow the instructions post installation.

brew install mysql

Start the mySQL service after installation

sudo mysql.server start

Secure your MySQL installation. The purpose of doing this is to set up your initial development environment. Follow the prompts to complete installation. If unsure, the suggested responses are yes to all including setting up a password.

mysql_secure_installation

Download MySQL Workbench, which is a free tool that allows you to view, edit and administer the database. Use it to connect to your local MySQL server and create a database called "myrobogals".

Setting up a Python virtual environment for myRobogals

Type the following command to create a Python 2 virtual environment. This will create a directory "myrobogals-env" in the current directory, which you will need whenever you develop myRobogals. This should not be in your myRobogals code directory.

python2 -m virtualenv myrobogals-env

(If you don't have Python 2 installed, install it using homebrew: brew install python@2 and if necessary brew link python@2 to put python2 into your path).

Activate the virtual environment (you'll need to activate the environment each time you are developing myRobogals)

source myrobogals-env/bin/activate

Now go to the cloned myRobogals directory and install the required dependencies listed under requirements.txt

cd (myRobogals folder path)
pip install --upgrade -r requirements.txt

Generate the Settings File

In the "myrobogals" directory inside the "myrobogals" directory (yes you read that correctly), make a copy of the file "settings.py.sample" and call it "settings.py"

Edit the file and fill in the path to your myRobogals directory at the top of the file. This is to ensure that everything gets the proper path references in your project.

Find where DATABASES is defined and enter in your MySQL credentials to ensure that Django has access to the database. If you want to use SQLite instead, comment out the DATABASES section for MySQL and uncomment the one for SQLite.

Generate a Sample Database

Create database structure

python manage.py migrate

Delete the timezone information, otherwise conflicts will occur when loading the sample data

python manage.py shell

In the Python shell command line enter the following:

from myrobogals.rgmain.models import Timezone
Timezone.objects.all().delete()
quit()

Load in the sample data

python manage.py loaddata sampledata

Start the development server

python manage.py runserver

The development server will now be running on http://127.0.0.1:8000/ - click there and you'll see your very own local copy of myRobogals.

You can log in with the username "mark" and password "test" to get started. This account has admin privileges.

Now get coding, and contribute your changes back to us as a "Pull Request" on Github!

Things to remember for EACH coding session

1. Activate your myRobogals virtual environment (see above)
2. Update your fork from the original repo to ensure you are working off the latest code
3. Install/upgrade required Python packages using 'pip install --upgrade -r requirements.txt'
4. If using MySQL, ensure that MySQL has started on your local machine. Otherwise Django will throw an error.
5. Run 'python manage.py migrate' to ensure your local database structure is up to date

Troubleshooting

We have compiled a list of common problems which you may encounter when setting up the development environment on myRobogals (probably what we've already encountered when setting up), however most of the errors can probably be found through a quick Google search

Database errors about a table/column not existing

You may have modified a model (e.g. added or removed a field) and forgot to run makemigrations:

python manage.py makemigrations

Makemigrations will create a python file describing the required database changes. This file should be committed to git, together with your other changes. Apply the database changes by running:

python manage.py migrate

Insufficient Permissions in Folder

Sometimes there might be permissions issue with the MySQL database. When trying to start up MySQL for the first time. To check if this is the case, change the directory to where MySQL is installed.

cd /usr/local/var/mysql/

Check permissions in that folder.

ls -la

If _mysql doesn't own everything in that folder, use the following commands to change ownership:

chown -R _mysql .
sudo chown -R _mysql .