This guide will bring you through the steps of creating a local server and development environment. It will walk through the setup of the core ecosystems we work within: Django/Python and React/Node/JS. It will additionally require the setup of a PostgreSQL database.

Fork/Clone The Repository

Forking will create your own version of listed on your GitHub! Cloning your fork will create a directory with all of the code required to run your own local development server. Navigate to the directory you wish to work from, then execute:

  1. Fork navigate to our GitHub repository then, in the top-right corner of the page, click Fork.

  2. Clone by executing this line on the command line:


    ATTENTION: Be sure to replace [YOUR-USERNAME] with your own git username

    git clone[YOUR-USERNAME]/semesterly

Option 1: Set up using Docker

Steps are below on getting your local development environment running:

  1. Download and install docker for your environment (Windows/Mac/Linux are supporter)

  2. Create semesterly/ as follows:

    DEBUG = True
        'default': {
            'ENGINE': 'django.db.backends.postgresql_psycopg2',
            'NAME': 'postgres',
            'USER': 'postgres',
            'PASSWORD': '',
            'HOST': 'db',
            'PORT': '5432',


    ATTENTION: When you clone the repo, you get a folder called semesterly and inside there is another folder called semesterly. Put this in the second semesterly folder.

  3. Edit semesterly/ and add a value for JHU_API_KEY in single quotes like below.

    You can request this API KEY from

    'JHU_API_KEY': 'xxxxxxxx',


    ATTENTION: This is also in the second semesterly directory.

    Now run this command in your terminal to make sure that this file isn’t tracked by Git and your API key stays local to you.

    git update-index --skip-worktree semesterly/
  4. Add this entry to your hosts file as follows (This file is in c:WindowsSystem32driversetchosts or /etc/hosts)


    ATTENTION: If you’re working on other schools, add their URLs here as well (i.e. for University of Toronto).

  5. Launch terminal or a command window and run:

    docker-compose build
    docker-compose up

    The build command creates a local database and build of your source code. The up command runs everything. Be careful not to build when you don’t need to as this will destroy your entire database and you’ll need to ingest/digest again to get your course data (which takes about 30 minutes).

    You now have running. If this is the first time, you will want some data which done in the next step.

  6. Getting JHU data for a given term. In a new terminal run the following

    docker exec -it $(docker ps -q -f ancestor=semesterly) /bin/bash
    * OR *
    docker exec -it $(docker ps -q -f ancestor=semesterly) shell

    This will put you inside of the shell. Now you can get courses by running these commands:

    python ingest jhu --term Fall --years 2021
    python digest jhu
  7. Open a browser and visit or (timetable view) and hack away. Visit http://localhost:8000 to view the landing page. You can skip ahead to Advanced Configuration or How It Works now.

Option 2: Setup using a Python Virtual Environment

Make sure you have installed Python 3.8.5. If you have not you can follow this. Please also download the python installer, PIP (install guide). We will now install and setup a python virtual environment. This keeps your dependencies for other projects and classes seperate from those required for

Install virtualenv:

sudo pip3 install virtualenv

Create a virtual environment called venv:

virtualenv -p /usr/bin/python3.8 venv

To enter your virtual environment, execute the following code from your Semesterly directory:

source venv/bin/activate


Be sure to execute the above “source” command anytime you’re working on Semesterly!

Check your OS info

If using Linux (Ubuntu, Fedora, CentOS, etc.), you can usually find your version info with this code:

cat /etc/issue

Install PostgreSQL

Before installing the python requirements, make sure to have PostgreSQL setup.

On mac, install Homebrew and run:

brew install postgres
pg_ctl -D /usr/local/var/postgres start && brew services start postgresql

On Ubuntu 18.x.x or Ubuntu 20.x.x use apt-get:

sudo apt-get update
sudo apt-get install postgresql python-psycopg2 libpq-dev libxslt-dev libxml2-dev

On CentOS / Fedora use yum:

sudo yum install postgresql gcc python-lxml postgresql-libs libxslt-devel libxml2-devel

Install Python Requirements


ATTENTION MAC USERS: you must install the xcode command line tools via xcode-select --install before proceeding.

All python dependencies are kept in a file called requirements.txt. Anytime a dependency is added or changed, we update it in this file. To bring your virtual environment up to date with all of these requirements easily, simply execute:

pip3 install --upgrade pip
pip3 install -r requirements.txt

Install Node Packages

Node and node package manager are the backbone of our frontend setup. To begin, install Node Package Manager (npm).

On mac:

brew install node

On Ubuntu 18.x.x or Ubuntu 20.x.x:

sudo apt-get install wget
wget -qO- | sudo bash -
sudo apt-get install -y nodejs

On CentOS / Fedora:

sudo yum install -y gcc-c++ make
curl -sL | sudo -E bash -
sudo yum install nodejs

Then use the newly installed Node Package Manager (npm) to install all javascript dependencies. When you execute this command, it reads from the file package.json which specifies all dependencies, their versions, and some additional node related configurations:

sudo npm install