Note: the following setup was done on an Ubunutu Linux, but should work on windows systems as well

Note for Windows: From what we've seen, Windows Docker Toolbox seem to have a poor performance. We recommend Windows users to set up the environment natively as described in Windows Setup tutorial​

Install Python

On Mac and Linux, python & pip comes with the system. For windows, you need to download them manually. Download Python 2.7 then install pip by following the links

Note: you may need to add python AND pip to your path, follow the instructions here.

Install Docker

Install docker 18.06.x Follow the instructions from official Docker doc. This will require you to create a docker account if you do not already have one.

Afterward install docker-compose 1.10.x from here (If not already installed with docker).

If setting up on linux, all docker and docker-compose commands should be preceeded with sudo. To enable docker without sudo, follow this official post-installation doc.

Set up development folder

Before we proceed, we recommend creating a dedicated directory (folder) for Ubyssey related projects. In this tutorial we will refer to this dir as ubyssey-dev (you can use any other name that makes sense to you). Let's create the directory at the location you want the code to live in:

Note: copy and paste all commands in terminal:

How to find the terminal:

Win: Click on Start btn > Type "cmd" > Click on "Command Prompt" Mac: Open Spotlight search or Applications folder > Type "terminal")

# Install virtualenv if you don't have it
pip install virtualenv
​
# Create a new virtual environment
cd ~
virtualenv ubyssey-dev
cd ubyssey-dev
​
# Activate the virtualenv
source bin/activate

We recommend working inside a virtualenv, but it's not required.

Note for Mac

Docker has a a known CPU overusage issue for macOS that may make your fan go wild.

Jason, one of our volunteers, found a trick to fix the issue!

For performance boost, there's a a popular tool called docker-sync.

Fork repositories

We will now download ubyssey.ca and dispatch projects. Follow our forking instructions first to copy the project under your GitHub username. Run these commands inside ubyssey-dev dir (note: to hcheck which dir you are in, try pwd command):

# Inside ubyssey-dev dir
# Change urls to your cloned repo
git clone https://github.com/<YOUR-USERNAME>/ubyssey.ca.git
git clone https://github.com/<YOUR-USERNAME>/dispatch.git

We have stored the config files for Docker in local-devdir inside ubyssey.ca project. To make enable Docker we first move the files to appropriate location:

# cd into your Ubyssey project dir
cd ~/ubyssey-dev
cp -r ./ubyssey.ca/local-dev/. .

We now need to set the local settings for django.

cp -r ubyssey.ca/_settings/settings-local.py ubyssey.ca/ubyssey/settings.py

Build and run the docker containers. This command can take several minutes, so be patient.

docker-compose up

Note for Windows:

docker-compose requires Docker to be running in the background. If docker-compose fails run Docker Toolbox first and try again*

Note: The database may fail to initialize. Simply re-run the above command and it should work.

To see currently running docker containers, run the following command in a separate terminal.

docker ps

NOTE: Keep this terminal window with docker running open for following commands

Setup the mysql container with a database

NOTE: Again, following commands should be done in a separate terminal window than before

Connect to the ubyssey_db docker container.

docker exec -t -i ubyssey_db bash

Setup the local database in ubyssey_db docker container.

# password is ubyssey
mysql -u root -p
create database ubyssey;
quit;

Populate the database.

apt update
apt-get install curl
# password is ubyssey.
# You may not be prompted for the password, and the curl operation may appear to have hanged. Simply type the password and press enter.
curl https://storage.googleapis.com/ubyssey/dropbox/ubyssey.sql | mysql -u root ubyssey -p

Your db container is up and running! Type exit to exit from this container

Perform django migrations on the docker container

Connect to the ubyssey-dev docker container

docker exec -t -i ubyssey-dev bash

Run migrations on the mysql database

cd ubyssey.ca
python manage.py migrate

Once the database has been populated, and migrations have been applied, you should be able to proceed to localhost:8000 and localhost:8000/admin to view ubyssey.ca and dispatch running from your ubyssey-dev docker container.

Media Files

Download and unzip the sample media folder to ubyssey-dev/ubyssey.ca/media/. This will make it so the images attached to the sample articles are viewable.

Dispatch

You can see Dispatch by going to http://localhost:8000/admin/

Username is volunteer@ubyssey.ca, password is volunteer

Extra docker info

When in doubt, you may need to clear docker's cache and remove all docker images.

# will remove docker cache and clear all images
docker system prune -a

then you can rebuild your docker images using

# from ubyssey-dev dir
docker-compose up

Using pdb with Docker

**Note: pdb is a command line debugging tool for python

First we need to update our docker-compose.yml to allow our ubyssey-dev container to connect with pdb. Make sure the django container looks like the following.

  django:
    build: .
    command: bash -c "cd ubyssey.ca && python manage.py runserver 0.0.0.0:8000"
    volumes:
      - ./dispatch/dispatch:/dispatch/dispatch
      - .:/ubyssey.ca
      - ~/.config/:/root/.config
    volumes_from:
      - gulp
      - yarn
    ports:
      - "8000:8000"
      #######
      # PDB #
      #######
      - "4444:4444"
    depends_on:
      db:
        condition: service_healthy
    container_name: ubyssey-dev
    #######
    # PDB #
    #######
    stdin_open: true
    tty: true

Now kill any running docker containers, and rerun them with docker-compose up.

Add import pdb to the .py file you are interested in debugging, and set a breakpoint with pdb.set_trace().

To step through the source, open a new terminal and connect to the ubyssey-dev container.

docker attach ubyssey-dev

the pdb output will start to display here when you hit your breakpoint.

For more information on pdb and how to use it, there is a helpful post at RealPython.