Installation¶

This guide will bring you through the steps of creating a local Semester.ly 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.

Setting up Visual Studio Code¶

We recommend using Visual Studio Code (VSCode) for its integration with WSL 2, Docker, and the Postgres database. This section assumes you will be using Visual Studio Code for development with Semester.ly.

1. If you are on Windows OS, see the following guide on installing Windows Subsystem for Linux (WSL). We recommend choosing Ubuntu 20.04 as your linux distribution. Make sure you take the extra steps to enable WSL 2 as it will be required for Docker.

After WSL 2 is installed, install the Remote - WSL extension by Microsoft in VSCode. This will allow you to open a VSCode window within your linux subsystem. Press Ctrl+Shift+P and select the option Remote-WSL: New WSL Window.

2. Install the Docker extension by Microsoft, the remote containers extension by Microsoft and the Postgres extension by Chris Kolkman.

3. Ensure that you are in a WSL Window in VSCode before continuing to the next step. You can open a terminal by selecting the menu option Terminal -> New Terminal.

Fork/Clone The Repository¶

Forking Semester.ly will create your own version of Semester.ly listed on your GitHub! Cloning your Semester.ly 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:

Fork navigate to our GitHub repository then, in the top-right corner of the page, click Fork.
Clone by executing this line on the command line:
Note

ATTENTION: Be sure to replace [YOUR-USERNAME] with your own git username
git clone https://github.com/[YOUR-USERNAME]/semesterly
Enter the directory:
cd semesterly

Set up the upstream remote to jhuopensource/semesterly:

git remote add upstream https://github.com/jhuopensource/semesterly

Setting up Docker¶

Steps are below on getting your local development environment running:

Download and install docker for your environment (Windows/Mac/Linux are supported)
https://www.docker.com/get-started

Create semesterly/local_settings.py as follows:

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

Note

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.

Edit semesterly/dev_credentials.py and add a value for JHU_API_KEY in single quotes like below.
You can request this API KEY from http://sis.jhu.edu/api.
'JHU_API_KEY': 'xxxxxxxx',
Note

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/dev_credentials.py
Alternatively, you may create semesterly/sensitive.py as follows:
SECRETS = { 'JHU_API_KEY': 'xxxxxxxx', # Other sensitive information goes here }
This file will automatically be ignored by git. Be sure to replace ‘xxxxxxxx’ with your own API key.
Append this entry to your hosts file as follows (This file is in C:\Windows\System32\drivers\etc\hosts or /etc/hosts)
127.0.0.1 sem.ly jhu.sem.ly
Note

ATTENTION: If you’re working on other schools, add their URLs here as well (i.e. uoft.sem.ly for University of Toronto).
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).

Note

If you run into additional errors, try the following:

1. Change “buildkit” from true to false in Settings -> Docker Engine.

2. Refer to the Docker troubleshooting document

Open a browser and visit http://jhu.sem.ly:8000 to verify you have Semester.ly running.

Note

In order to log in on your local running version of Semester.ly, you will need access to auth keys. Please ask one of the current developers for access to these keys if you require use of login authentication for development. Furthermore, some logins require use of https, so ensure that you are on https://jhu.sem.ly instead of http://jhu.sem.ly:8000 in these cases.

Tip

If you ever need to hard reset Docker, use the command docker system prune -a. You can then follow up with docker-compose build && docker-compose up.

Setting up Postgres¶

You can easily access the Postgres database within VSCode by following the next steps. You should have the Postgres extension by Chris Kolkman installed.

Open the Postgres explorer on the left pane and click the plus button in the top right of the explorer to add a new database connection.
Enter 127.0.0.1 as the database connection.
Enter postgres as the user to authenticate as.
Enter nothing as the password of the PostgreSQL user.
Enter 5432 as the port number to connect to.
Select Standard Connection.
Select postgres.
Enter a display name for the database connection, such as semesterly.

Upon expanding a few tabs under the new semesterly database, you should see several tables. Right clicking any of these tables gives you options to select (view) the items in the table or run a query.

If this is your first time running Semester.ly, you will want to populate your database with courses. Before you continue to Loading the Database, please read the following additional tips for working with Docker and Postgres.