Dev Environment Setup Guide

This document will walk you through the setup and configuration of a development environment for webqueue2 using the provided development machines, SSH authentication, GitHub and VS Code.

Prerequisites

On Your Computer

• VS Code
• Cisco AnyConnect for WebVPN

On The Development Computer

Note

These are already installed on the provided development machines.

• git
• Python >= 3.6.9

Configuring Your SSH Keys

We will be using SSH keys to authenticate to both the development machines and GitHub.

In either PowerShell on Windows or bash on macOS/Linux, run the following command and accept all defaults by pressing Enter:

ssh-keygen

This will create the files id_rsa and id_rsa.pub in the .ssh folder inside your user's folder. Your user's folder can usually be found at:

Windows

C:\Users\<user_name>

macOS

/Users/<user_name>

Linux

/home/<user_name>

Note

Most CLI shells like PowerShell and bash use the ~ (tilda) key as a shortcut for your user's folder.

You can confirm these files were created by running:

ls ~/.ssh/

Configuring SSH

In your editor of choice, create the file ~/.ssh/config and add this:

Tip

Replace campb303 with your career account username and replace w2vm1 with the name of the provided development machine you're connecting to.

Host campb303-w2vm1
  HostName w2vm1.ecn.purdue.edu
  User campb303
  # Forward Flask Debug Port
  LocalForward 5000 localhost:5000
  # Forward MkDocs Port
  LocalForward 5000 localhost:6060
  # Forward gunicorn Port
  LocalForward 8000 localhost:8000

The configuration above will allow you to connect to the development machine and automatically forward ports for development tools to work. Here's a bit more detail about what's going on:

Key	Value
Host	A friendly name to identify an SSH host by. This can be anything.
HostName	The DNS name or IP address of the computer you're connecting to.
User	The name of your user on the computer you're connecting to.
LocalForward	Forwards a port on your computer to a port on the computer you're connecting to.

Development machines are not publicly accessible. You'll need to be connected to WebVPN to connect to them.

SSH Jump Hosts

WebVPN works on all platforms but requires an extra step to get to work. On macOS/Linux, pier.ecn.purdue.edu can be used as an SSH jump host allowing for development machines to be connected to automatically when openning VS Code.

Assuming you already have an SSH key configured for pier.ecn.purdue.edu, you can use a jump host by adding the following to ~/.ssh/config:

Host campb303-pier
    HostName pier.ecn.purdue.edu
    User campb303

Host campb303-w2vm1
    HostName w2vm1.ecn.purdue.edu
    ProxyJump campb303-pier
    User campb303
    # Forward Flask Debug Port
    LocalForward 5000 localhost:5000
    # Forward MkDocs Port
    LocalForward 5000 localhost:6060
    # Forward gunicorn Port
    LocalForward 8000 localhost:8000

To test your configuration, run ssh followed by the Host value. When prompted for your password, enter your career account password and press Enter.

Warning

Most shell environemnts like PowerShell and bash do not show your password being typed but it is being typed.

For the configuration above you would run:

ssh campb303-w2vm1
campb303@w2vm1's password:

Adding SSH Keys

Now that we've generated SSH keys and configured our host entries, we need to add our SSH key to the host. This will allow us to connect to these machines without passwords later.

Tip

Replace HOST below with the value from above. Example: campb303-w2vm1

PowerShell on Windows

type $env:USERPROFILE\.ssh\id_rsa.pub | ssh HOST "cat >> .ssh/authorized_keys"

bash on macOS/Linux

ssh-copy-id HOST

If the key was added successfully, you can login without entering a password by running:

ssh HOST

Installing VS Code

Download and install VS Code. Be sure to add code to your PATH.

Windows

Adding code to your PATH on Windows is a checkbox in the installer:

Image from this article on Techomoro

macOS/Linux

Adding code to your PATH on macOS/Linux is accessible by searching for "PATH" in the Command Pallete. You can access the Command Pallete with the keyboard shortcut Command/Ctrl + Shift + P:

Image from this StackOverflow thread

Connecting To The Development Machine

Install the Remote - SSH plugin. After installation a new icon will appear in the sidebar:

• Click on the Remote SSH icon and you'll see the SSH host you just defined
• Select the host and click the New Window icon to connect. A new window connected to that host will appear

Note

This may take a couple of minutes on the first connection while VS Code installs its server.

If prompted for a platform, select Linux:

Adding Your SSH Keys to GitHub

Because the development machine will be the computer that connects to GitHub, we need to create another SSH key and add it to our GitHub profile:

First, open VS Code's integrated terminal by pressing Control + ~ (tilda)

Now run the following command and accept all defaults by pressing Enter:

ssh-keygen

This will create the files id_rsa and id_rsa.pub in ~/.ssh/. You can confirm this by running:

ls ~/.ssh/

Now copy the public key from id_rsa.pub by openning the file in VS Code, selecting its contents and copying it. You can open the file in VS Code by running the following in the integrated terminal:

Danger

Do not copy your private key from id_rsa! This key should never leave your machine.

code ~/.ssh/id_rsa.pub

Now go to github.itap.purdue.edu/settings/keys. You may be prompted to login using your career account username and password.

• Click the "New SSH Key" button
• Give the key a title that tells you what device the key is from (e.g. Desktop or Dev Machine)
• Paste the contents of id_rsa.pub into the key box
• Click the "Add SSH Key" button

Cloning and Opening the Repository

Using the integrated terminal in VS Code, run:

git clone git@github.itap.purdue.edu:ECN/webqueue2-api.git

This will create a webqueue2-api folder in your user's home directory. Open this directory using the "Open Folder" button:

Note

VS Code will automatically reconnect to the last remote host used when it reopens.

Tip

If you need to reconnect manually, there will now be an option to open the webqueue2-api folder directly from the Remote Hosts menu:

Configuring VS Code

Installing Extensions

• Pylance for Python language support, IntelliSense, virtual environments and debugging
• Git Graph for a more detailed view of git info
• Markdown Preview GitHub Styling for previewing Markdown as it will appear on GitHub
• Python Docstring Generator for generating Google style docstrings according to section 3.8 of Google's Python style guide

Configuring Extensions

Python

The Python extension supports virtual environments but needs to be told where the virtual environment is.

Create or modify the file .vscode/settings.json and add the following:

"python.defaultInterpreterPath": "./venv/bin/python3"

Tip

The Python extension may complain and tell you to select another interpreter. Ignore this warning for now.

Python Docstring Generator

For consistentcy, we'll use a docstring template. Create or modify the file .vscode/settings.json and add the following:

"autoDocstring.customTemplatePath": "./docstring-format.mustache"

At this point, your .vscode/settings.json file should look like this:

{
    "python.pythonPath": "./venv/bin/python3",
    "autoDocstring.customTemplatePath": "./docstring-format.mustache"
}

Setting Up the Virtual Environment

For development, we'll use a Python Virtual Environment to isolate out changes and have a reproducible dev environment.

In VS Code's integrated terminal:

Create a virtual environment at ./venv/:

python3 -m venv venv 

Activate the virtual environment:

source venv/bin/activate

Tip

To deactivate the virtual environment and use your system's Python interpreter, run:

deactivate

Update pip within the virtual environment:

pip install -U pip

Install the webqueue2 API within the virtual environemt:

pip install -e .[all]

-e installs a package in editable mode which allows code changes to take effect without reinstalling a package.

webqueue2 API has multiple conditional dependencies:

Condition	Installation Command	Description
Production	pip install .	For use in production. Only installed needed packages.
Development	pip install .[dev]	For use in development. Installs everything for production and extra packages for development.
Documentation	pip install .[docs]	For use in creating documentation. Installs everything for production and extra packages for documentation.
All	pip install .[all]	A shortcut for installing production, development and documentation dependencies.

API Commands

Command	Description
gunicorn webqueue2api.api:app	This will start a local server on localhost:8000 to access the API.
mkdocs serve	This will start a local server on localhost:6060 to access the API docs. As you change API documentation files in ./docs/ you'll see your changes in the browser.
mkdocs build	This will output a static bundle of the API documentation in ./site/ that can be put on any webserver.