Developing myRobogals on a Mac

Here's how to install a local development copy of myRobogals on Mac OS X.

This guide will be helpful for Linux users too - for the first part, instead install Django using instructions for your specific OS (Google is your friend), then the rest is the same for Linux as for Mac.

Pre-requisites

We currently use Django 1.7.11 with Python 2.7.13. For maximum compatibility with what's running on the live server, it's recommended that you use these versions too. You will need these items to be installed on your machine in order to run myRobogals

• Python
• Django
• (Optional) mySQL
• (Optional) mysql-python
• pytz
• tinymce
• (Optional) Sequel Pro

It is recommended that you install them using Homebrew with the instructions provided below. However, you can install Django, Python and all dependencies however you wish.

Check out the myRobogals repository

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

Github: Set up git

Github: Fork a repo

myRobogals repo

Installing prerequisites

First off, you will need to have Homebrew installed and updated

/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

(Optional) Installing mySQL

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

myRobogals is using a mySQL database. To be able to view the database in a meaningful way, download Sequel Pro and add it to your applications folder.

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

Now go to Sequel Pro and under QUICK CONNECT click SOCKET and type the following:

• Name: localhost
• Username: root
• Password: (what you entered for sql setup)
• Database: (leave as blank)

Then click connect. After it's connected you will need to create a database called myrobogals. In the top menu under Databases, Add Databases ... create a new database called myrobogals.

Next we will need to create a new useraccount. Under Databases again, go to User Accounts... Down in the bottom right, click the + symbol to create a new account. Make the username myrobogals and password to something. Then click on schema privileges and grant myrobogals user to have all privileges on the myrobogals database, then click apply. This user will be used by Django to access the myrobogals database.

Setting up Python and Django

Install Python 2.7.13 using Homebrew

brew install python

Link python to homebrew. You may have some issues here with linking, if so, try unlinking first then linking.

brew link python
brew unlink python && brew link python

Instead of installing the Django requirements on your computer which may have version and references collisions with what you've previously installed, it is best to use a virtual environment which counteracts this issue. So install virtualenv

pip install pyenv-virtualenv

Create your new virtual environment in any directory you want as long as it's not in the forked myRobogals folders. For now, you can create it in your user home directory

cd
virtualenv venv

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

. venv/bin/activate

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

cd (myRobogals folder path)
pip install -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 rename it to "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. For those who want to use sqlite (or other databases), comment out the one 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 "admin" and password "test" to get started. This account has admin privileges, so go ahead and create your own. All the other sample users have the password "abc123".

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 required Python packages using 'pip install --upgrade -r requirements.txt'
4. 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 .