Software Onboarding

Owned by Anthony Bernardi (Unlicensed)
Last updated: Jan 18, 2024 by Reid Chandler

General

Welcome to Northeastern Electric Racing’s Software Solutions team! We are excited to have you join!

Table of Contents

Purpose

The purpose of this document is to onboard developers to the Software Solutions team. To learn more about the team itself, see the Software Solutions page. To get a better idea of the goals and roles on the team, you can read the Software Solutions Charter.

Environment Setup

Time to dive into the meat of onboarding: environment setup! Note: every time you install something, please restart your CLI to be able to use it (it will probably say that what you installed is not recognized otherwise).

Project Setup

  1. Git: What is it and why?

    1. Git is a version control system and GitHub is an internet hosting service using the version control that Git provides. If you are not familiar with Git, you can find a great presentation on what Git is here. Some other resources include common git commands, CLI commands, and what Git is (if you get the gist you do not need to read through all of it).

    2. In order to set up Git on your computer please follow these steps (after creating a GitHub account if you do not already have one). Make sure to do the authentication step so that your computer is tied to your GitHub account.

    3. Now that you have Git installed and have a GitHub account, clone the repository from here to your computer, potentially using git clone in your preferred CLI (i.e. Terminal/Powershell; please use Powershell over Command Prompt on Windows) to pull the project down to your computer. 

  2. NodeJS: Version 14 16 18 Please

    1. Ensure that you have Node.js v18 installed. Any iteration of version 18 will do as long as it is version 18! (Make sure to pick an installer that corresponds to your operating system) https://nodejs.org/en/blog/release/v18.17.1

    2. Check the box to install any additional tools during installation to ensure functionality with VSCode while installing (don’t worry if there are a couple errors here - this tends to happen on new installs).

    3. After installation, confirm that the version is some variant of 18 with the command node -v.

  3. NPM & Yarn

    1. Navigate to the folder of the cloned repository using your CLI (via the cd command).

    2. If you’re on Windows: run Set-ExecutionPolicy -ExecutionPolicy RemoteSigned to prevent some future problems with yarn

    3. In your CLI, run npm install -g yarn.

    4. Run yarn install to instruct npm to install all the necessary packages.

Database

Docker is the new method to run the database. If you’re a returning developer and still have the old way, that’s ok, you can keep using it. This way is just easier to setup! (NOTE: If you have Windows and method 1 isn’t working, move on to method 2!!!)

Method 1

  1. Install Docker

    1. Download Docker Desktop for your OS and install it following the default steps (there are a few weird steps for Windows so make sure to do those).

    2. After installation, restart your computer if required.

  2. .env setup

    1. Navigate to the src/backend directory in the repo and run one of the two commands below based on your OS

      1. [Mac] echo "DATABASE_URL=\"postgresql://postgres:docker@localhost:5432/nerpm?schema=public\"" >> .env

      2. [Windows] ni .env then Set-Content -Path .env 'DATABASE_URL="postgresql://postgres:docker@localhost:5432/nerpm?schema=public"'

  3. Run the following two commands in your CLI (note - if you are already running Postgres from the old manual installation, you must stop it first):

    1. docker run --name finishline -e POSTGRES_PASSWORD=docker -p 5432:5432 -d postgres

    2. docker exec -ti finishline psql -U postgres -c "CREATE DATABASE nerpm;"

  4. Go to your Docker desktop app and the container you just made should appear. If it says “running”, then everything is working!

Method 2 (for Windows users who can’t get Docker running)

  1. Go to https://www.postgresql.org/download/ and download Postgres

  2. Run the installer with all defaults except: uncheck “Stack Builder” on the list of things to install, and make your password “password” when prompted.

  3. Once it’s done, press the windows button and search for “psql” and open the thing called something like “psql command line”

  4. press enter for everything except password, where you should type “password” then press enter

  5. run CREATE DATABASE nerpm;

  6. go back to powershell and cd to the main folder of the repo, then cd to src/backend

  7. [Windows] run ni .env then Set-Content -Path .env 'DATABASE_URL="postgresql://postgres:password@localhost:5432/nerpm?schema=public"'

Initial Database Migration

  1. In order to run the database for the first time, you will need to execute the following command in the CLI (make sure you’ve navigated back to the base folder of the repo!). Run yarn prisma:reset.

    1. This combines three commands for you: yarn prisma:migrate which applies all the existing database migrations to the database, yarn prisma:generate which builds the type files for typescript so you can code with it, and yarn prisma:seed which populates the database with test data

  2. Refer to Software Prisma FAQ for more information about these commands.

Run and Test

  1. To test that things are working, run yarn install and then yarn start in the CLI (in the root directory) and go to an example API route. Example: localhost:3001/users.

    1. Then go to localhost:3000 to see the dashboard (if it does not launch automatically)! Feel free to take a look around!

  2. IDE: VSCode

    1. We use VSCode at NER. You can use something else, but we won’t be able to help you if you have problems. VSCode is pretty industry standard though, so it’s very good to know.

    2. Click File > Open Folder then navigate to the repo and open it

    3. There should be a popup in the bottom right asking you if you want to install the recommended extensions. Click install.

      1. If for some reason this doesn’t show up, the following are the mandatory VSCode extensions. You can install them manually by clicking the extensions tab on the left (it looks like building blocks) and searching for them:

        1. Jest (orta.vscode-jest)

        2. Prisma (prisma.prisma)

        3. ESLint (dbaeumer.vscode-eslint)

        4. Prettier (esbenp.prettier-vscode)

      2. And the optional ones (for a better experience):

        1. Babel (mgmcdermott.vscode-language-babel)

        2. Material Icon Theme (pkief.material-icon-theme)

  3. Congrats!

    1. You now (theoretically) have a functioning environment! Congratulations! If not, please look at the FAQ page, and if that doesn’t help, look for further help in the #software_env-setup slack channel (more info down below). Once again, here is the link to the repo (and here is the link to the outdated repo which still holds a lot of useful information).

What Now?

Learn about the technologies we use and join Slack (see below)! If you are not familiar with the technologies, don’t worry! We have some learning resources to help with the basics! You may also follow tutorials found in the NER curriculum for this information as well as attend the Learning Sessions. When you are ready to start development on the codebase, please read through the contributor guide on the GitHub repo.

Join the Slack!

At NER, we utilize Slack for communication. We ask that you download Slack on both your phone and computer to be able to reliably view and respond to any communication. Here is a quick start guide for Slack (on desktop). Most of the information in this should translate over to mobile. Please note that notifications may be off by default, so please ensure that they are turned on. After this, go through the channels that exist in the Slack and join any relevant channels (#software, #software_env-setup, and #software_pr-review for starters). Additionally, try to avoid DMing people (unless it’s a personal issue). Keeping communications public is better because someone probably will have the same question as you and it keeps everyone up to date. It also allows more than one person to help you.

Organization & Leads

Now who should you ask for issues?

Our Product Team exists as a wonderful resource for all developers on the Software Solutions team. Product Analysts, Product Managers, and our Head hold key business facing information for all parts of our application, and are a great resource to go to if you have non-technical questions. Make sure to reach out to relevant analysts, PMs, or even Peyton first before reaching out to others for these questions in case they can answer your questions.

For technical or coding questions, try to contact anyone you are pair programming with or working with on a feature. If this does not help, move to the tech leads & senior developers. Next step is to check in with a Software Group Lead, Peyton McKee. If they cannot answer anything, please contact the Head of Software Solutions, Reid Chandler.