mirror of https://github.com/DOI-DO/j40-cejst-2.git synced 2025-02-20 08:41:26 -08:00

[SPIKE] Improve backend documentation (#2177 )

* Update code owners to include new folks and remove the departed ones

* Update maintainers to reflect the current personnel

* Update contributing with the latest, and make small changes to readme to make it easier to read

* Update maintainers with Lucas Brown

* Update installation guide to refine instructions and make them easier to follow

* Try emojis to make notes stand out more

* Experiment with note

* Moved installation of data pipeline into a new file (contents TBD), and redid most part of the data pipeline README for clarity and readability

* Add mermaid diagram

* Fix table

* Update readme for clarity and correctness

* Update TOC

* Fix comparator doc

* Add section on internal score comparison

* Move tox information from installation to testing

* Update installation for data pipeline

* Add emojis to make picking out platform-specific instructions easier

* Fix Git caps

* Update for readability

* Add direct link to VS Code instructions

* Fix broken link and improve readability

* Update installation for clarity and proper case

* Update python text

* Clean up information about poetry and poetry lockfiles

* Remove duplicate paragraph

* Fix case

* update date table

* re-adjust table to put links at the end

* Fix a few minor typos

---------

Co-authored-by: Sam Powers <121890478+sampowers-usds@users.noreply.github.com>

2023-02-28 15:11:57 -06:00

5.7 KiB

Raw Permalink Blame History

Justice40 Tool Installation

¡Lea esto en español!

This page documents the installation steps for some of the prerequisite software needed to work with this project. It covers steps for macOS and Win10. If you are not on either of those platforms, install the software using steps appropriate for your operating system and device.

💡 NOTE
If all you want to do is try out the application locally, visit QUICKSTART.md.

Prerequisites

There are several prerequisites necessary for downloading the source code and creating the environment necessary to run both the Frontend Client and the Data Pipeline and Scoring Application.

1. Install Git

Our project is hosted on Github, and can be forked using Git. You can use Git via the command line or any number of first or third party visual clients (the scope of which is beyond these instructions).

macOS 🍎

To install Git on macOS,

Open the terminal, type git, and press return
If dev tools are not installed, a window will prompt you to install dev tools. Follow those instructions to complete the installation
Once dev tools are installed, open the terminal, type git --version, and press return
Validate that a version number is returned (e.g. git version 2.37.1). If a version number is returned, Git is properly installed

Win10 🪟

On Win10, download and install Git following the instructions on git-scm.com.

2. Install Homebrew (macOS 🍎 only)

Homebrew is an easy way to manage software packages on macOS. Homebrew is not a requirement. However, we recommend it, and our installation instructions will assume you have Homebrew installed.

Open your terminal and run brew -v to determine whether you have Homebrew installed. If you get a response that looks something like Homebrew 3.1.9, you've already got it! If you get nothing back, or an error, continue with these instructions.
Follow the instructions on the Homebrew home page to install Homebrew on your machine.
Validate installation by typing brew -v in the terminal; ensure a version number – like in step 1 – is shown.

Don't forget to regularly run brew update and brew doctor to make sure your packages are up to date and in good condition.

3. Install Node

Node version manager (nvm) allows you to install, manage, and use different Node.js versions on your machine. It's our preferred method to install Node.js.

Follow these instructions to install nvm. Be sure to read through all of the instructions to find the sections within each step relevant to you (e.g. if you're using Homebrew, when you get to Step 2 look for the section titled Install NVM with Homebrew).

💡 NOTE
If you install nvm using Homebrew, make sure to read the terminal output. There are additional installation instructions you must follow (such as adding lines to your bash or zsh profile).

Once you've completed the nvm installation, use nvm to install Node.js version 14.

nvm install 14

You should then be able to switch to that version of Node.js through the command:

nvm use 14

To validate you are using Node.js 14, type:

node -v

This should return something like v14.x.x.

4. Set Up Your IDE (Optional)

While any IDE can be used to contribute to this project, many of our developers use Visual Studio Code (VS Code). Because of this, we've included a few VS Code configurations to make it easier to develop the data pipeline.

On macOS 🍎, open the terminal and type brew install --cask visual-studio-code and press return. If this doesn't work – or you're using Win10 🪟 – you can download and install VS Code directly.
After forking this repo, you can clone your forked repo into VS Code.

To use the client in VS Code,

Open the terminal and navigate to client directory
Type npm install to load dependencies
Type gatsby develop to spin up the app
Navigate to localhost:8000 to view the app

We recommend the following VS Code Extensions:

5. Install Docker (Optional)

Using Docker is optional; the Frontend Client and the Data Pipeline and Scoring Application can be run without Docker. If you wish to install Docker, follow the Docker installation instructions for your platform.

Next Steps

After you've completed the prerequisites, you can continue on to specific installation steps for the part of the platform you're interested in exploring.

Platform	Instructions
Frontend Client	Frontend Client Instructions
Data Pipeline and Scoring Application	Data Pipeline Instructions
Deployment Process	Github Workflows README

5.7 KiB Raw Permalink Blame History Unescape Escape