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
Note: you may need to add python AND pip to your path, follow the instructions here.
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.
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.
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 itpip install virtualenv# Create a new virtual environmentcd ~virtualenv ubyssey-devcd ubyssey-dev# Activate the virtualenvsource bin/activate
We recommend working inside a virtualenv, but it's not required.
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.
We will now download
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
# Inside ubyssey-dev dir# Change urls to your cloned repogit clone https://github.com/<YOUR-USERNAME>/ubyssey.ca.gitgit clone https://github.com/<YOUR-USERNAME>/dispatch.git
We have stored the config files for Docker in
ubyssey.ca project. To make enable Docker we first move the files to appropriate location:
# cd into your Ubyssey project dircd ~/ubyssey-devcp -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 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.
NOTE: Keep this terminal window with docker running open for following commands
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 ubysseymysql -u root -pcreate database ubyssey;quit;
Populate the database.
apt updateapt-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
Connect to the
ubyssey-dev docker container
docker exec -t -i ubyssey-dev bash
Run migrations on the mysql database
cd ubyssey.capython manage.py migrate
Once the database has been populated, and migrations have been applied, you should be able to proceed to
localhost:8000/admin to view ubyssey.ca and dispatch running from your ubyssey-dev docker container.
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.
You can see Dispatch by going to
email@example.com, password is
# will remove docker cache and clear all imagesdocker system prune -a
then you can rebuild your docker images using
# from ubyssey-dev dirdocker-compose up
**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/.configvolumes_from:- gulp- yarnports:- "8000:8000"######## PDB ########- "4444:4444"depends_on:db:condition: service_healthycontainer_name: ubyssey-dev######## PDB ########stdin_open: truetty: true
Now kill any running docker containers, and rerun them with
import pdb to the .py file you are interested in debugging, and set a breakpoint with
To step through the source, open a new terminal and connect to the
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.