Skip to content

Developer's Guide

Jump to bottom
Hallie edited this page Mar 10, 2023 · 10 revisions

Developer's Guide

Looking to get started developing and improving WiCHacker-Manager? This is where you should start

Developer's Note

The most important priority of the WiCHacker-Manager is to try and future-proof the application. Whenever possible we have chosen the simplest or easiest to understand/operate alternative to solve an issue. Since our application load is relatively small and the turnover of maintainers will be very large, we do not need optimizations that will make things harder to understand for future developers who may not be as familiar with the technology.

Common Gotchas

  • Sometimes UI development differs from production behavior because we are using react dev server vs productionized build

Setup

General Infrastructure

AWS Required Services:

  • EC2 - compute
  • S3 - resume storage
  • ParameterStore - secret storage
  • IAM - permissions
  • RDS - database
  • Cloudwatch - viewing logs

DNS Updates:

  • Cloudflare

Local Development

Quick Note: Local development still relies on AWS secrets and everything is determined by environment variables to configure local vs production configurations

Notes on Running the Application:

The database is run in a local docker container. You can also run a database outside of a container, but the connection information comes from secrets so make sure your database matches that same configuration

Most local development is dependent on running the applications on your computer. If you are developing the UI, you can run the API in a docker container. If you are developing the API, I would recommend running both locally to speed up development and you won’t have to worry about as many docker networking issues like calling containers by name as opposed to using localhost.

  1. Setup AWS Account
    1. Have AWS Root User Create User Account
    2. Generate AWS Secret Pair through IAM
    3. Root User will have to authorize permissions for new user
    4. Create .aws folder in user’s home directory
      1. Credentials tell the application who you are, while config tells it to look in the correct region for our tools
    5. Create ~/.aws/credentials file
      1. See below for default credentials file
    6. Create ~/.aws/config file
      1. See below for default config file
  2. Clone Repository
    1. Make sure your github account is in the WiCHacks github organization
      1. Lana, Webmaster, WiCHacks Director, Projects Director or Logistics Director should be able to make this happen
    2. Clone the WiCHacker-Manager repository
  3. Install docker and docker-compose
    1. NOTE: This is the only place in this guide where there will be a difference between operating systems. All other commands have only been verified to work on a Mac dev environment
    2. Mac
      1. Navigate to the docker download page and click the download for your applicable Mac. Make sure to choose Intel or Apple Silicon accordingly
      2. Open the .DMG file that was downloaded. Then, like any other Mac app, drag it to the applications folder
      3. Close the DMG, and then open the newly installed Docker app
      4. When you launch it for the first time, Docker will ask you for your administrator password. This is normal, and safe. Docker is a trusted tool.
      5. Docker will load, potentially open another authorization prompt, let it load
      6. Eventually, Docker will settle down, and you should see a window with a green bar in the bottom left corner
      7. NOTE: You will need Docker running while developing on this project
    3. Windows
      1. Use WSL
    4. Install Dependencies
      1. Fronted
        1. Install NPM
        2. Navigate to the /ui directory and run npm install
      2. Backend
        1. Navigate to the /api directory
        2. Run pip install -r requirements.txt
      3. Database (Optional)
        1. Pull Mysql docker image
        2. Run docker pull mysql:8.0.28
    5. Run Applications
      1. NOTE: This portion of the guide assumes you are running the front and backend directly on your computer and the database in a Docker container
      2. Frontend
        1. Navigate to /ui folder
        2. Open package.json
          1. On line 5, add "proxy": "https://localhost:5002",
        3. Open /src/config/axios.js
          1. Change apiDomain to return localApiDomain
          2. Change getAxios to return localAxios
        4. Run npm start
        5. Application should start running on http://localhost:3000
      3. Database
        1. NOTE TO ALEX TO ACTUALLY DO THIS ASAP
      4. Backend
        1. Navigate to /api
        2. Open /src/server.py
        3. All the way at the bottom, change app.run() to include the additional parameter port=5002
        4. Run server.py
        5. NOTE: If the database is not running, or AWS connections are not enabled, this will error

Blank File Templates

./aws/credentials

[default]
aws_access_key_id=AKIAIOSFODNN7EXAMPLE
aws_secret_access_key=wJalrXUtnFEMI/K7MDENG/bPxRfiCYEXAMPLEKEY

./aws/config

[default]
region=us-east-1
output=json

Production

Pre-Requisites: Make sure you have the infrastructure up and running before continuing.

  1. SSH into EC2
  2. Clone repository
    1. Create SSH keypair
    2. Add keypair to GitHub account
    3. Run clone
  3. Navigate to root of project directory
  4. Run docker-compose -f prod-docker-compose.yml up -d
  5. Navigate to https://apply.wichacks.io and verify

Initial Permissions

NOTE TO ALEX TO IMPLEMENT AND WRITE THIS ASAP

Frontend

Overview

The frontend of WiCHacker Manager is built in React. React was chosen as it is one of the largest frameworks available as of the start of development, as well as being taught by the Software Engineering department at RIT.

Higher Order Components

There are currently two higher order components that assist with authentication and authorization of pages. They can be found in the hocs folder, while being utilized in the routes.js file protecting different routes with differing levels of security.

Considerations

Javascript can be hard for backend developers. The triple equals, the non-obvious truthy statements and null checks can look somewhat foreign to those who aren’t super familiar with front end development. I know there are many super cool and very succinct javascript patterns that can be quite efficient and useful, but I would recommend avoiding these when possible as the functionality can be obscure. If it is necessary to use a super concise pattern, please make sure to heavily comment this code to increase readability for future developers.

Our users will likely be very technical. As such, try not to include any console logs to keep as much information as possible hidden from the users. WiCHacks is a big target for malicious actions of all sorts so security and protecting errors / vulnerabilities is very important for us.

Backend

Documentation

Swagger

Development

Data Storage

General

Database Schema

Database Migrations

S3 / Resumes

Permissions

Authentication

GitHub

Actions / Build Pipeline

Stadards

AWS / Infrastructure

General Note

Our infrastructure for both production and local development relies on AWS.

Future Changes

If someone wants to switch cloud providers in the future, please investigate very thoroughly to make sure every way AWS is currently utilized is understood. There are a few hidden benefits that most likely exist at all cloud providers but require understanding and additional setup beyond just getting some allocated space on a cloud provider’s machines.

Deployments

WiCHacks 💜 Women in Computing 💜 Rochester Institute of Technology

Clone this wiki locally