Docker Instructions

(This is a Work In Progress. Please contact the current web devs if anything is confusing!)

Setup Basics

  1. In your preferred development folder:

    git clone
    docker build . -t ubyssey/

     (Or replace ubyssey/ with name of your choice)

  2. Again, in your preferred directory, clone either the below repo, or else clone a fork you made of it:

    git clone

     (If you changed the docker image's name, make sure to also change it in docker-compose.yml in /ubyssey-dev/.devcontainer/)

  3. Use the Remote Development plugin to open the ubyssey-dev.git directory as a container

  4. If the database container isn't set up yet, connect to it:

docker exec -t -i ubyssey_db bash

This container may be named something other than ubyssey_db. If so, type docker ps to find what it is named. You can also connect to it without typing terminal commands if you download Docker Desktop.

Once connected, setup the local database in the container.

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

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 | mysql -u root ubyssey -p
  1. You should now be able to develop inside the Docker container and see your development version of the site on localhost:8000

What does setting up like this accomplish?

Starting out as a new coder on an ongoing coding project is generally a difficult and time-consuming process. Even if your general computer knowledge is strong, knowledge of the specific tools involved may still be weak, and there’s almost inevitably a lot of learning to do. Furthermore, because you’re likely to have your own computer, we have little control over what you have installed, creating the risk of wasting time doing a lot of individualized troubleshooting.

Because the Ubyssey depends so much upon volunteer work from students who are busy with school work, it is necessary coder onboarding be made as fast as possible, so volunteers do not get caught up on the “boring stuff” of simply getting a local development environment set up. We therefore distribute virutalized development machines using containerization technology, specifically, Docker. This technology is often used in the tech industry alongside DevOps practices. The site and all its dependencies are packaged together in a “container”. Containers are a virtualization technology that can start up faster than traditional VMs, because many containers can share a single Linux kernel. The containerized website can run the same on any individual computer as it runs on the production environment.



Install Docker (version docker 19.03.x is used in these instructions). 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 (these instructions use docker-compose 1.25.x) from here (If not already installed with docker).

 (2020/06/29 - Possibly outdated note!) 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.*

Visual Studio Code

This sort of workflow is best done using Visual Studio Code, available for all major platforms, because Microsoft has developed a Remote Development plugin designed to facilitate this.

(Possibly outdated) 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.

Various How-Tos

How to clone repositories

This is the github link (

Clone the and the dispatch repositories to where-ever you prefer to work. This is typically done with the following terminal commands. If you forked the repository, use the URL of your fork. If you are working on a different branch, use the -b flag to specify which branch.

git clone
git clone

How to build Docker images from scratch

To build a docker image from a Dockerfile, run in the directory containing the Dockerfile:

docker build . -t <dockerhub account>/<image name>:<tag>


docker build . -t <some other cloud hub>/<cloud account>/<image name>:<tag>

 (The first works because Docker Hub will be assumed if the cloud hub isn’t specified)

You can name the image whatever you like, but if you want to push it to the cloud, you should follow the above convention of \/\:\

In our project:

  • A Dockerfile is located in /

  • There is also one in /dispatch/ too, but it layers Dispatch on top of the image built by the one in / To get this to work correctly, make sure you name the image built from the / Dockerfile the same name as is in the /dispatch/ Dockerfile’s FROM instruction

How to build static files with Gulp

Building static files with gulp is a step in front-end development which is somewhat analogous to compiling.

If you see that there is no CSS styling applied to the HTML in (http://localhost:8000/), you may need to set-up

In the Docker container: 1) Install the required Node packages with npm:

cd /workspaces/
npm install

2) Install a global version of gulp (if you don't have it already) and build the static files:

npm install -g gulp
gulp buildDev

_If you run into any error while installing npm or gulp, remove by running rm -rf node_modules

How to setup the mysql container with a database

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;

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 | mysql -u root ubyssey -p

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

If you run into operation errors, drop the schemas in mysql database and repopulate it.

Performing 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

python 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 and dispatch running from your ubyssey-dev docker container.

Media Files

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

Using Dispatch

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

Username is, password is volunteer

Extra docker info

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

docker ps

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.

build: .
command: bash -c "cd && python runserver"
- ./dispatch/dispatch:/dispatch/dispatch
- .:/
- ~/.config/:/root/.config
- gulp
- yarn
- "8000:8000"
# PDB #
- "4444:4444"
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.