Docker Instructions

Ubyssey Code
Search…
Introduction
Our Technology
Docker Instructions
(This is a Work In Progress. Please contact the current web devs if anything is confusing!)
Setup Basics
1.
Install git, Docker, Visual Studio Code, and the Remote Development plugin for Visual Studio Code.
2.
In your preferred development folder:
1
git clone https://github.com/ubyssey/ubyssey.ca.git
2
cd ubyssey.ca
3
docker build . -t ubyssey/ubyssey.ca:latest
Copied!
 (Or replace ubyssey/ubyssey.ca:latest with name of your choice)
3.
Again, in your preferred directory, clone either the below repo, or else clone a fork you made of it:
1
git clone https://github.com/ubyssey/ubyssey-dev.git
Copied!
 (If you changed the docker image's name, make sure to also change it in docker-compose.yml in /ubyssey-dev/.devcontainer/)
4.
Set up a persistent Docker volume. (This is used to persist the database contents between Docker containers, should you ever need to delete yours)
1
docker volume create --name=ubyssey_db_volume
Copied!
5.
Use the Remote Development plugin to open the ubyssey-dev.git directory as a container
6.
If the database container isn't set up yet, connect to it:
1
docker exec -t -i ubyssey_db bash
Copied!
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.
1
# password is ubyssey
2
mysql -u root -p
3
create database ubyssey;
4
quit;
Copied!
Populate the database.
1
apt update
2
apt-get install curl
3
# password is ubyssey.
4
# You may not be prompted for the password, and the curl operation may appear to have hanged. Simply type the password and press enter.
5
curl https://storage.googleapis.com/ubyssey/dropbox/ubyssey.sql | mysql -u root ubyssey -p
Copied!
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.
Software
Docker
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 (https://github.com/ubyssey).
Clone the ubyssey.ca 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.
1
git clone https://github.com/ubyssey/ubyssey.ca.git
2
git clone https://github.com/ubyssey/dispatch.git
Copied!
How to build Docker images from scratch
To build a docker image from a Dockerfile, run in the directory containing the Dockerfile:
1
docker build . -t <dockerhub account>/<image name>:<tag>
Copied!
Or:
1
docker build . -t <some other cloud hub>/<cloud account>/<image name>:<tag>
Copied!
 (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 /ubyssey.ca/.
There is also one in /dispatch/ too, but it layers Dispatch on top of the image built by the one in /ubyssey.ca/. To get this to work correctly, make sure you name the image built from the /ubyssey.ca/ 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 ubyssey.ca/ubyssey/static/
In the Docker container: 1) Install the required Node packages with npm:
1
cd /workspaces/ubyssey.ca/ubyssey/static/
2
npm install
Copied!
2) Install a global version of gulp (if you don't have it already) and build the static files:
1
npm install -g gulp
2
gulp buildDev
Copied!
_If you run into any error while installing npm or gulp, remove ubyssey.ca/ubyssey/static/node_modules by running rm -rf node_modules
How to setup the mysql container with a database
Connect to the ubyssey_db docker container.
1
docker exec -t -i ubyssey_db bash
Copied!
Setup the local database in ubyssey_db docker container.
1
# password is ubyssey
2
mysql -u root -p
3
create database ubyssey;
4
quit;
Copied!
Populate the database.
1
apt update
2
apt-get install curl
3
# password is ubyssey.
4
# You may not be prompted for the password, and the curl operation may appear to have hanged. Simply type the password and press enter.
5
curl https://storage.googleapis.com/ubyssey/dropbox/ubyssey.sql | mysql -u root ubyssey -p
Copied!
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
1
docker exec -t -i ubyssey-dev bash
Copied!
Run migrations on the mysql database
1
cd ubyssey.ca
2
python manage.py migrate
Copied!
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.
Using Dispatch
You can see Dispatch by going to http://localhost:8000/admin/
Username is [email protected], password is volunteer
Extra docker info
To see currently running docker containers, run the following command in a separate terminal.
1
docker ps
Copied!
When in doubt, you may need to clear docker's cache and remove all docker images.
1
# will remove docker cache and clear all images
2
docker system prune -a
Copied!
then you can rebuild your docker images using
1
# from ubyssey-dev dir
2
docker-compose up
Copied!
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.
1
  django:
2
    build: .
3
    command: bash -c "cd ubyssey.ca && python manage.py runserver 0.0.0.0:8000"
4
    volumes:
5
      - ./dispatch/dispatch:/dispatch/dispatch
6
      - .:/ubyssey.ca
7
      - ~/.config/:/root/.config
8
    volumes_from:
9
      - gulp
10
      - yarn
11
    ports:
12
      - "8000:8000"
13
      #######
14
      # PDB #
15
      #######
16
      - "4444:4444"
17
    depends_on:
18
      db:
19
        condition: service_healthy
20
    container_name: ubyssey-dev
21
    #######
22
    # PDB #
23
    #######
24
    stdin_open: true
25
    tty: true
Copied!
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.
1
docker attach ubyssey-dev
Copied!
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.