diff --git a/Dev Environment Setup Guide.md b/Dev Environment Setup Guide.md deleted file mode 100644 index 03ed436..0000000 --- a/Dev Environment Setup Guide.md +++ /dev/null @@ -1,256 +0,0 @@ -# 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 - - - -- [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) - - - -## 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.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. - -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: - -- `C:\Users\` (Windows) -- `/Users/` (macOS) -- `/home/` (Linux) - -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: - -**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 -``` - -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. | - -**Note:** You need to be connected to WebVPN before SSH'ing into a the development machine. - -To test your configuration, run `ssh` followed by the `Host`value. When prompted for your password, enter your career account password and press Enter. - -**Note:** You will not see 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 -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" -``` - -**In bash on macOS/Linux:** -```bash -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](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 Command/Ctrl + Shift + P: - -![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) - -## 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 -``` - -This will create the files `id_rsa` and `id_rsa.pub` in `~/.ssh/`. You can confirm this by running: -``` -ls ~/.ssh/ -``` - -- 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 - -![Add SSH Key to GitHub](docs/Dev%20Environment%20Setup%20Guide/Add%20SSH%20Key%20to%20GitHub.gif) - -## 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) - -### 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: -```json -"python.pythonPath": "./api/venv/bin/python3" -``` - -**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. - -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", - "autoDocstring.customTemplatePath": "./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 `. The tasks are: - -| 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//.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`. | -| `venv:freeze` | Regenerates the API requirements.txt file and mitigates [this pip bug](https://github.com/pypa/pip/issues/4022). |