Skip to content

Commit

Permalink
Merge branch 'staging' into enhancement-responsive-itemtable
Browse files Browse the repository at this point in the history
  • Loading branch information
@campb303
campb303 authored Oct 23, 2020
2 parents c9cda61 + 4cbb998 commit 071fe7c
Show file tree
Hide file tree
Showing 37 changed files with 4,044 additions and 2,345 deletions.
272 changes: 204 additions & 68 deletions Dev Environment Setup Guide.md
View file
Original file line number Diff line number Diff line change
@@ -1,119 +1,255 @@
# Dev Environment Setup Guice
# 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.

# Table of Contents

<!-- TOC -->

- [Prerequisites](#prerequisites)
- [On Your Computer](#on-your-computer)
- [On The Development Computer](#on-the-development-computer)
- [Configuring Your SSH Keys](#configuring-your-ssh-keys)
- [Configuring SSH](#configuring-ssh)
- [Adding SSH Keys](#adding-ssh-keys)
- [Installing VS Code](#installing-vs-code)
- [Connecting To The Development Machine](#connecting-to-the-development-machine)
- [Adding Your SSH Keys to GitHub](#adding-your-ssh-keys-to-github)
- [Cloning and Opening the Repository](#cloning-and-opening-the-repository)
- [Configuring VS Code](#configuring-vs-code)
- [Installing Extensions](#installing-extensions)
- [Frontend Extensions:](#frontend-extensions)
- [Backend/API Extensions:](#backendapi-extensions)
- [Configuring Extensions](#configuring-extensions)
- [Python](#python)
- [Python Docstring Generator](#python-docstring-generator)
- [Configuring Tools](#configuring-tools)
- [Using Tools](#using-tools)

<!-- /TOC -->

## Prerequisites

### On Your Computer
- [VS Code](https://code.visualstudio.com/download)
- [Cisco AnyConnect for WebVPN](https://webvpn.purdue.edu/)

### On The Development Computer
**Note:** These are already installed on the provided development machines.
- [git](https://git-scm.com/downloads)
- [NodeJS](https://nodejs.org/en/) >= v14.2.0
- npm >= v6.14.4
- npx >= v6.14.4
- [Python](https://www.python.org/downloads/) >= 3.7
- [NodeJS](https://nodejs.org/en/) >= v14.11.0
- npm >= v6.14.8
- npx >= v6.14.8
- [Python](https://www.python.org/downloads/) == 3.6.9

## Configuring Your SSH Keys
We will be using SSH keys to authenticate to both the development machines and GitHub.

## Setup
- The webqueue2 API uses `gunicorn` as a WSGI server and this does not run on Windows. If you're developing on Windows use a virtual machine.
In either PowerShell on Windows or bash on Linux, run:
```
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:

- webqueue2 uses npm and create-react-app to manage itself. You can learn more about npm [here](https://nodesource.com/blog/an-absolute-beginners-guide-to-using-npm/) and create-react-app [here](https://create-react-app.dev/docs/getting-started/).
- `C:\Users\<user_name>` (Windows)
- `/Users/<user_name>` (macOS)
- `/home/<user_name>` (Linux)

---
Most CLI shells like PowerShell and bash use the tilda <kbd> ~ </kbd> key as a shortcut for your user's folder.

### Step 1: Close the Reposistory
You can confirm these files were created by running:
```
git clone https://github.itap.purdue.edu/ECN/webqueue2.git
ls ~/.ssh/
```
**Note:** github.itap.purdue.edu is only accessible on Purdue's campus or via the [AnyConnect webvpn](https://webvpn.purdue.edu/).

### Step 2: Move to the project directory
```
cd webqueue2
```
## Configuring SSH
In your editor of choice, create the file `~/.ssh/config` and add this:

### Step 3: Install npm Packages
```
npm install
**Important:** Replace `campb303` with your career account username and replace `w2vm1` with the name of the provided development machine you're connecting to.

```bash
Host campb303-w2vm1
HostName w2vm1.ecn.purdue.edu
User campb303
# Forward webqueue2 Frontend Port
LocalForward 3000 localhost:3000
# Forward webqueue2 API Port
LocalForward 5000 localhost:5000
# Forward webqueue2 Docs Port
LocalForward 6060 localhost:6060
```

#### Using npm
There are four npm scripts included in this project:
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:

- `npm run start:frontend`: This will start a development server on [localhost:3000](http://localhost:3000). (If the server is on your local machine, this will also launch your default browser at that address.) As you save changes in /public and/or /src you'll see your changes in the browser. (API requests are automatically proxied to the API server.)
| 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. |

- `npm run start:api`: This will start a local WSGI server on [localhost:5000](http://localhost:5000) to access the API. **Note:** You will need to add Python to your PATH variable if it is not already.
**Note:** You need to be connected to WebVPN before SSH'ing into a the development machine.

- `npm run build`: This will build a static version of the site in /build ready to be placed in the document root of any web server.
To test your configuration, run `ssh` followed by the `Host`value. When prompted for your password, enter your career account password and press <kbd>Enter</kbd>.

- `npm run test`: This will run any tests (using the [Jest](https://jestjs.io/) tester). There are currently no defined tests.
**Note:** You will not see your password being typed but it is being typed.

### Step 4: Setup Python for API
Go to the API directory
For the configuration above you would run:
```
cd api/
ssh campb303-w2vm1
campb303@w2vm1's password:<career_account_password>
```

Create Python virtual environment
## Adding SSH Keys
Replace `HOST` below with the value from above.

**In PowerShell on Windows:**
```powershell
type $env:USERPROFILE\.ssh\id_rsa.pub | ssh HOST "cat >> .ssh/authorized_keys"
```
python3 -m venv venv

**In bash on macOS/Linux:**
```bash
ssh-copy-id HOST
```

Activate the Python virtual environment
If the key was added successfully, you can login without entering a password by running:
```
source venv/bin/activate
ssh HOST
```

If you're pip version is less than 19, upgrade pip
```
(venv) campb303@acererak [~/webqueue2/api]
$ pip --version
pip 9.0.1 from /home/pier/e/campb303/webqueue2/api/venv/lib/python3.6/site-packages (python 3.6)
## Installing VS Code
Download and install [VS Code](https://code.visualstudio.com/download). Be sure to add `code` to your PATH.

**On Windows:** this is a a checkbox in the installer.

![VS Code Install Options on Windows](https://i0.wp.com/www.techomoro.com/wp-content/uploads/2019/06/5.jpg?w=596&ssl=1)

_Image from [this article on Techomoro](https://www.techomoro.com/installing-visual-studio-code-on-windows-10/)_

**On macOS/Linux:** this is accessible by searching for "PATH" in the Command Pallete. You can access the Command Pallete with the keyboard shortcut <kbd>Command</kbd>/<kbd>Ctrl</kbd> + <kbd>Shift</kbd> + <kbd>P</kbd>:

![VS Code Install Options on macOS/Linux](https://i.stack.imgur.com/Ng886.png)

_Image from [this StackOverflow thread](https://stackoverflow.com/questions/30065227/run-open-vscode-from-mac-terminal)_

## Connecting To The Development Machine
Install the [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) plugin. After installation a new icon will appear in the sidebar:

![Remote SSH Plugin Icon](./docs/Dev%20Environment%20Setup%20Guide/Remote%20SSH%20Icon.png)

- 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

![Remote SSH Connection Example](./docs/Dev%20Environment%20Setup%20Guide/Connect%20to%20Remote%20SSH%20Host.gif)

If prompted for a platform, select Linux:
![VS Code Select Platform](./docs/Dev%20Environment%20Setup%20Guide/VS%20Code%20Select%20Platform.png)

(venv) campb303@acererak [~/webqueue2/api]
$ pip install --upgrade pip
...
Successfully installed pip-20.2.2
## 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:

Using the integrated terminal in VS Code, run:
```bash
ssh-keygen
```

Install Python requiements
This will create the files `id_rsa` and `id_rsa.pub` in `~/.ssh/`. You can confirm this by running:
```
pip install -r requirements.txt
ls ~/.ssh/
```

**Note:** You can deactivate the Python virtual environment by running `deactivate`.
- Go to https://github.itap.purdue.edu/settings/keys
- 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

### Step 5: Install VS Code extentions
![Add SSH Key to GitHub](docs/Dev%20Environment%20Setup%20Guide/Add%20SSH%20Key%20to%20GitHub.gif)

#### Installing Plugins
- [ES Lint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) for JavaScript linting
- [Babel JavaScript](https://marketplace.visualstudio.com/items?itemName=mgmcdermott.vscode-language-babel) for JavaScript and JSX syntac highlighting and error checking
## Cloning and Opening the Repository
Using the integrated terminal in VS Code, run:
```bash
git clone git@github.itap.purdue.edu:ECN/webqueue2.git
```
This will create a `webqueue2` folder in your user's home directory. Open this directory using the "Open Folder" button:

![Open Repo](./docs/Dev%20Environment%20Setup%20Guide/Open%20Repo.gif)

**Note:** When you open VS Code next it will try to reconnect to the last SSH host it was connected to.

**Note:** If you need to reconnect manually, there will not be an option to open this folder directly from the Remote Hosts menu:

![Remote Folder Open](./docs/Dev%20Environment%20Setup%20Guide/Remote%20Folder%20Open.png)

## Configuring VS Code

### Installing Extensions
Install the following extensions:
- [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python) for working with Python virtual environments and debugging
- [Git Graph](https://marketplace.visualstudio.com/items?itemName=mhutchie.git-graph) for a more detailed view of git info
- [Markdown Preview GitHub Styling](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-preview-github-styles) for previewing Markdown as it will appear on GitHub

#### Frontend Extensions:
- [ES Lint](https://marketplace.visualstudio.com/items?itemName=dbaeumer.vscode-eslint) for JavaScript linting
- [Babel JavaScript](https://marketplace.visualstudio.com/items?itemName=mgmcdermott.vscode-language-babel) for JavaScript and JSX syntax highlighting and error checking
- [MDX](https://marketplace.visualstudio.com/items?itemName=silvenon.mdx) to provide MDX syntax support

#### Backend/API Extensions:
- [Python Docstring Generator](https://marketplace.visualstudio.com/items?itemName=njpwerner.autodocstring) for generating Google style docstrings according to section 3.8 of [Google's Python style guide](https://google.github.io/styleguide/pyguide.html#s3.8-comments-and-docstrings)

Optionally:
- [Remote - SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh) for directly editing files on remote machine
- [Markdown Preview GitHub Styling](https://marketplace.visualstudio.com/items?itemName=bierner.markdown-preview-github-styles) for previewing Markdown as it will appear on GitHub
### Configuring Extensions

## Configuring Environemnt
ES Lint, Babel JavaScript and Markdown Preview GitHub Styling will work without further configuration
#### Python
The Python extension supports virtual environments but needs to be told where the virtual environment is.

### Step 1: Configure VS Code's Python Extension
Create a folder called .vscode in the project root
```
mkdir .vscode
Create or modify the file `.vscode/settings.json` and add the following:
```json
"python.pythonPath": "./api/venv/bin/python3"
```

Create a file in the .vscode folder called settings.json
```
nano .vscode/settings.json
```
**Note:** 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.

Add the path to the virtual environment Python interpreter
Create or modify the file `.vscode/settings.json` and add the following:
```json
"autoDocstring.customTemplatePath": "./docstring-format.mustache"
```

At this point, your `.vscode/settings.json` file should look like this:
```json
{
"python.pythonPath": "./api/venv/bin/python3"
"python.pythonPath": "./api/venv/bin/python3",
"autoDocstring.customTemplatePath": "./docstring-format.mustache"
}
```
For more information on the Python extension and details on how to use the debugger see: [Getting Started with Python in VS Code](https://code.visualstudio.com/docs/python/python-tutorial) for more info.

### Step 2: Configure Python Docstring Generator
In Settings > Extensions> Python Docstring Generator set the Custom Template Path to `./docstring-format.mustache`
## Configuring Tools
Install npm dependencies:
```bash
npm install
```

Create the Python virtual environment:
```bash
npm run venv:create
```

## Using Tools
All of the tools in this project are accessible as an npm task so you can interact with them by running `npm run <task>`. The tasks are:

### Step 3 (Optional): Configure Remote - SSH Plugin
Remote - SSH will requires hosts to be added to your SSH config file. See [this guide](https://linuxize.com/post/using-the-ssh-config-file/) for more info.
| Task | Description |
| - | - |
| `start:frontend` | This will start a development server on [localhost:3000](http://localhost:3000). (If the server is on your local machine, this will also launch your default browser at that address.) As you save changes in the `/public` or `/src` directories you'll see your changes in the browser. (API requests are automatically proxied to the API server.) |
| `start:api` | This will start a local WSGI server on [localhost:5000](http://localhost:5000) to access the API. You can interact with the API using `curl` or [Postman](https://www.postman.com/) |
| `start:docs` | This will start a local server on [localhost:6060](http://localhost:6060) showing you the React component documentation. As you change a components documentation file in `/src/components/<component_name>/<component_name>.md` you'll see your changes in the browser. |
| `build:frontend` | This will output a static bundle of the frontend in `/build` that can be put on any webserver. |
| `build:docs` | This will output a static bundle of the frontend documentation in `/styleguidist/frontend-docs` that can be put on any webserver. |
| `kill:frontend` | Kills the runaway frontend process(es). |
| `kill:api` | Kills the runaway API process(es). |
| `venv:create` | This will create a virtual environment in `/api/venv` and install requirements from `/api/requirements.txt`. |
| `venv:delete` | This will delete the folder `/api/venv`. |
| `venv:reset` | This will run `venv:delete` then `venv:create`. |
7 changes: 2 additions & 5 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -1,15 +1,12 @@
# webqueue2
A re-write of Purdue ECN's webqueue

![UI Snapshot](./docs/UI%20Snapshots/UI-Snapshot%202020-08-19%20at%202.10.48%20PM.png)
![UI Snapshot](./docs/UI%20Snapshots/UI-Snapshot%202020-09-22%20at%201.48.58%20PM.png)

## Stay Up To Date
See what's being worked on with [the webqueue2 Project](https://github.itap.purdue.edu/ECN/webqueue2/projects/4).
See what's being worked on with [the webqueue2 Project](https://github.itap.purdue.edu/ECN/webqueue2/projects/).

See and participate in the conversation by viewing the [issues](https://github.itap.purdue.edu/ECN/webqueue2/issues).

## Tech Specs
Stay up to date with the [Dev Logs](https://github.itap.purdue.edu/ECN/webqueue2/blob/master/Dev%20Logs.md).

## Get Involved
Reading the [Dev Environment Setup Guide](https://github.itap.purdue.edu/ECN/webqueue2/blob/master/Dev%20Environment%20Setup%20Guide.md)
Loading

0 comments on commit 071fe7c

Please sign in to comment.