fix(readme): Added set up instructions and re-organized information

README.md

@@ -7,39 +7,27 @@
 
 # Classroom
 
-> A self-hosted solution to help teachers plan and manage classroom-based learning, on top of freeCodeCamp's learning platform.
+A self-hosted solution to help teachers plan and manage classroom-based learning, on top of freeCodeCamp's learning platform.
 
 ## Motivation
 
 For a while now teachers have been asking for a way to get a birds eye view of multiple students who are progressing through the course. This is why we set out to make freeCodeCamp classroom mode, an interactive dashboard for teachers to view multiple freeCodeCamp users’ progress on their courses.
 
 ## Contributing
 
-### Optional - GitHub Codespaces Environment
+This project supports multiple ways to set up the codebase. You can choose to either to use Gitpod or Github Codespaces for a browser environment or set up locally. Please use whichever you feel the most comfortable with. We recommend Github Codespaces if you are not sure.
 
-If you have used GitHub Codespaces in other projects, doing the same in freeCodeCamp Classroom should be straightforward.
+Please read our contibution [guidelines](https://contribute.freecodecamp.org/#/how-to-contribute-to-the-codebase?id=contributing-to-the-codebase) before making your first pull request.
 
-- https://docs.github.com/en/codespaces/overview
+### Instructions to set up your code:
 
-- https://docs.github.com/en/codespaces/getting-started
+#### Option 1 - [GitHub Codespaces Environment](docs/GITHUB-CODESPACES-SET-UP.md)
 
-- If you want a ready-made dev environment in your browser, make a fork of this repository.
+#### Option 2 - [GitPod Dev Environment](docs/GITPOD-SET-UP.md)
 
-- Afterward, set up your NextAuth-related environment variables in the `.env` file.
+#### Option 3 - [Local Docker Enviornment](docs/LOCAL-DOCKER-SET-UP.md)
 
-- Please follow the "Setup Instructions" in the terminal for more information.
-
-Within freeCodeCamp Classroom, GitHub Codespaces is on par with Gitpod so that you can use either.
-
-### Optional - GitPod Dev Environment
-
-If you want a ready-made dev environment in your browser, make a fork of this repository and then prefix your fork with "gitpod.io/#". For example,
-
-`gitpod.io/#https://github.com/{your-github-user-name}/classroom`
-
-You will still need to setup your NextAuth-related environment variables in the .env file.
-For more information, please follow the "Setup Instructions" in the terminal.
-For setting up locally, follow the instructions below.
+Need more help? Ran into issues? Check out this [guide](https://docs.google.com/document/d/1apfjzfIwDAfg6QQf2KD1E1aeD-KU7DEllwnH9Levq4A/edit) that walks you through all the steps of setting up the repository locally, without Docker.
 
 ### Styling a component
 
@@ -53,91 +41,54 @@ We are strongly opinionated about adding new variables/tokens to the colors. Aft
 
 We recommend going through our [system design diagram](https://www.canva.com/design/DAFo8ezu7W8/EfUE0hjSDuJHFRGnG9NOvQ/edit?utm_content=DAFo8ezu7W8&utm_campaign=designshare&utm_medium=link2&utm_source=sharebutton).
 
-### Prepare the database
-
-This project uses a [PostgreSQL](https://www.postgresql.org/) database. You should follow the instructions in the linked documentation to set it up for your system. Alternatively, you can use the below commands for a docker-based setup on likes of Linux or macOS, if you have docker installed.
-
-<details>
-
-<summary>Docker based setup on Linux, macOS, etc.</summary>
+## Resources
 
-```console
-# create a directory for the data
-mkdir -p $HOME/docker/volumes/postgres
+### Contact Information
 
-# start a container (this will use the "latest" tag. Use the version as needed)
-docker run -it --name pgsql-classroom -e POSTGRES_PASSWORD=password -d --restart unless-stopped -p 5432:5432 -v $HOME/docker/volumes/postgres:/var/lib/postgresql/data postgres:latest
-
-# change DATABASE_URL in your .env to
-postgresql://postgres:password@localhost:5432/classroom
-```
-
-</details>
-
-### Get the code
-
-1. Clone the project repository.
-   ```console
-   git clone https://github.com/freeCodeCamp/classroom.git
-   cd classroom
-   ```
-2. We use npm (specifically npm workspaces) to manage our dependencies.
-   ```console
-   npm ci
-   ```
-3. Create `.env` file based on the `.env.sample` file. Theses are the environment variables that are used by the application.
-4. Run `npx prisma generate`.
-5. Run `npx prisma db push`.
-6. Run `npx prisma db seed`.
-7. Run `npm run develop`.
-8. Run `npm run mock-fcc-data`
-9. Run `npx prisma studio`
-
-Need more help? Ran into issues? Check out this [guide](https://docs.google.com/document/d/1apfjzfIwDAfg6QQf2KD1E1aeD-KU7DEllwnH9Levq4A/edit) that walks you through all the steps of setting up the repository locally, without Docker.
-
-### Join us in our [Discord Chat](https://discord.gg/qcynkd4Edx) here.
-
----
+Join us in our [Discord Chat](https://discord.gg/qcynkd4Edx).
 
 ### Terminology
 
 freeCodeCamp uses the following terms:
 
-Certification = 'superblock'
+`Certification = 'superblock'`
+
+`Course(s) = 'blocks'`
 
-Course(s) = 'blocks'
+Everything under a course/block is a `'challenge'`
 
-Everything under a course/block is a 'challenge'
+### API
 
----
+This project uses multiple APIs from freeCodeCamp. Check out the following and familiarize yourself.
 
-### Tech stack learning resources
+[Superblock API](https://www.freecodecamp.org/curriculum-data/v1/available-superblocks.json)
 
-Testing with jest
-https://jestjs.io/docs/snapshot-testing
+[Blocks API](https://www.freecodecamp.org/curriculum-data/v1/2022/responsive-web-design.json)
 
-Next.js fullstack framework
-https://nextjs.org/docs/pages/building-your-application/optimizing/testing#jest-and-react-testing-library
-https://dillionmegida.com/p/nextjs-main-concepts/
-https://blog.devgenius.io/advanced-next-js-concepts-8439a8752597
+Mock API: Student information - this will be replaced with real student information in the future. It is **not available publicly** yet, you will need to start the application and go to http://localhost:3001/data.
 
-Next.js terminology:
+### Tech Stack Learning Resources
 
-SSR - Server Side Rendering
+#### Jest Snapshot Testing
 
-SSG - Static Site Generation
+> We are always in need of more tests! Checkout Jest's [snapshot testing docs](https://jestjs.io/docs/snapshot-testing). We recommend learning snapshot testing as we require tests for each component inside our project.
 
-ISR - Incremental Static Regeneration
+#### Next.js Fullstack Framework
 
-CSR - Client Side Rendering
+> This project utilizes Next.js to optimize performance, such as SEO. We recommend learning [main concepts of Next.js](https://dillionmegida.com/p/nextjs-main-concepts/) and familiarizing yourself on [testing with Next.js](https://nextjs.org/docs/pages/building-your-application/optimizing/testing#jest-and-react-testing-library).
 
-SSR is probably the focus point.
+#### Next.js Terminology:
 
-https://dev.to/mbaljeetsingh/what-is-csr-ssr-ssg-isr-different-rendering-strategies-and-which-framework-does-it-better-angular-react-vue-4lkp
+| Term | Value                           |
+| ---- | ------------------------------- |
+| SSR  | Server Side Rendering           |
+| SSG  | Static Site Generation          |
+| ISR  | Incremental Static Regeneration |
+| CSR  | Client Side Rendering           |
 
----
+> ISR is probably the focus point. Checkout this [article](https://dev.to/mbaljeetsingh/what-is-csr-ssr-ssg-isr-different-rendering-strategies-and-which-framework-does-it-better-angular-react-vue-4lkp) to understand these concepts and how they are helpful.
 
-### License
+## License
 
 Copyright © 2021 freeCodeCamp.org
 

docs/GITHUB-CODESPACES-SET-UP.md

@@ -0,0 +1,78 @@
+# Github Codespaces Setup Instructions
+
+If you have used GitHub Codespaces in other projects, doing the same in freeCodeCamp Classroom should be straightforward. We recommend reading the following if you are unfamiliar with Github Codespaces.
+
+- [Github Codespaces Overview](https://docs.github.com/en/codespaces/overview)
+- [How to get started with Github Codespaces](https://docs.github.com/en/codespaces/getting-started)
+
+## Step 1: Enable Github Codespace
+
+- On our [github](https://github.com/freeCodeCamp/classroom), look for a green button called Code on the top right.
+- Click on the button to reveal the dropdown
+- Observe that there are two options, Local and Codespaces which you can switch through
+- Get to the Codespaces option
+- Click on Open CodeSpace. Github will take care of making the codespace for you. Don't worry if it's taking a while, it can take up to 10 mins.
+
+## Step 2: Set up a NextAuth Provider App
+
+You need to set up a NextAuth Provider and run the app.
+
+For dev environments, we have enabled use of the Github Provider. Please read and follow their [guide](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) to set up the oauth app.
+
+## Step 3: Update the .env file
+
+You will need to update the .env file inside Github Codespaces with the following:
+
+- Set DataBase Url to:
+  `postgresql://postgres:password@localhost:5432/classroom`
+
+- Set mock user data URL to:  
+  `https://${CODESPACE_NAME}-3001.preview.app.github.dev/data`
+
+- Set homepage url to:  
+  `https://${CODESPACE_NAME}-3000.preview.app.github.dev`
+
+- Set callback url to:
+  `https://${CODESPACE_NAME}-3000.preview.app.github.dev/api/auth/callback/github`
+
+- Set NEXTAUTH_URL to:
+  `https://${CODESPACE_NAME}-3000.preview.app.github.dev`
+
+- Set GITHUB_ID to:
+  - Your Client ID is shown in the OAuth app page (generated at step 2). Copy and paste to GITHUB_ID.
+- Set GITHUB_SECRET to:
+  - Generate a **new** Client Secret. Then copy and paste to GITHUB_SECRET.
+
+Please follow the "Setup Instructions" in the terminal for more information.
+
+Within freeCodeCamp Classroom, GitHub Codespaces is on par with Gitpod so that you can use either.
+
+## Additional Steps to take after finishing Github Codespaces setup:
+
+1. Open a terminal and paste the following to start the application.
+
+```console
+   npm run develop
+```
+
+2. Check to see if the website is functional and you can sign in and authorize yourself using your GitHub profile.
+
+3. After successfully signing in, sign out and open a new terminal.
+
+4. Start the ORM tool, [Prisma Studio](https://www.prisma.io/docs/concepts/overview/what-is-prisma).
+
+```console
+   npx prisma studio
+```
+
+5. In Prisma Studio, go to User. Under the “roles” column, enter TEACHER or ADMIN. And click on the “Save Changes” button.
+
+6. Feed in the mock student data being used.
+
+```console
+   npm run mock-fcc-data
+```
+
+7. Go to the ports tab and set the visibility to public for the 3000 and 3001 ports.
+
+Happy coding!

docs/GITPOD-SET-UP.md

@@ -0,0 +1,66 @@
+# Gitpod Setup Instructions
+
+Please review Gitpod docs if you are not familiar with it.
+
+- [How to get started with Gitpod Codespaces](https://www.gitpod.io/docs/introduction/getting-started)
+
+## Step 1: Enable Gitpod
+
+If you want a ready-made dev environment in your browser, make a fork of this repository and then prefix your fork with "gitpod.io/#". For example,
+
+`gitpod.io/#https://github.com/{your-github-user-name}/classroom`
+
+## Step 2: Set up a NextAuth Provider App
+
+You need to set up a NextAuth Provider and run the app.
+
+For dev environments, we have enabled use of the Github Provider. Please read and follow their [guide](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) to set up the oauth app.
+
+## Step 3: Update the .env file
+
+You will need to update the .env file inside Github Codespaces with the following:
+
+- Set DataBase Url to:
+  `postgresql://postgres:password@localhost:5432/classroom`
+
+- Set mock user data URL to:  
+  `https://3001-${GITPOD_WORKSPACE_URL:8}/data`
+
+- Set homepage url to:  
+  `https://3000-${GITPOD_WORKSPACE_URL:8}`
+
+- Set callback url to: `https://3000-${GITPOD_WORKSPACE_URL:8}/api/auth/callback/github`
+
+- Set NEXTAUTH_URL to:
+  `https://3000-${GITPOD_WORKSPACE_URL:8}`
+
+- Set GITHUB_ID to:
+  - Your Client ID is shown in the OAuth app page (generated at step 2). Copy and paste to GITHUB_ID.
+- Set GITHUB_SECRET to:
+  - Generate a **new** Client Secret. Then copy and paste to GITHUB_SECRET.
+
+Please follow the "Setup Instructions" in the terminal for more information.
+
+Within freeCodeCamp Classroom, Gitpod is on par with Github Codespaces so that you can use either.
+
+## Additional Steps to take after finishing Gitpod Setup:
+
+1. Open a terminal and paste the following to start the application.
+
+```console
+   npm run develop
+```
+
+2. Check to see if the website is functional and you can sign in and authorize yourself using your GitHub profile.
+
+3. After successfully signing in, sign out and open a new terminal.
+
+4. Start the ORM tool, [Prisma Studio](https://www.prisma.io/docs/concepts/overview/what-is-prisma).
+
+```console
+   npx prisma studio
+```
+
+5. In Prisma Studio, go to User. Under the “roles” column, enter TEACHER or ADMIN. And click on the “Save Changes” button.
+
+Happy coding!

docs/LOCAL-DOCKER-SET-UP.md

@@ -0,0 +1,87 @@
+# Local Docker Setup Instructions
+
+Docker based setup **requires** Linux, macOS, etc. If you have not used docker before, we recommend reading Docker documentation to familiarize yourself.
+
+- [Getting Started with Docker](https://docs.docker.com/get-started/)
+
+## Step 1: Make sure you have Docker installed
+
+You will need to have Docker on your local machine to create the enviornment. Please refer to the docs to [install docker](https://docs.docker.com/get-docker/) if you do not have it already.
+
+## Step 2: Prepare the database
+
+This project uses a [PostgreSQL](https://www.postgresql.org/) database. You can use the below commands for a docker-based setup on likes of Linux or macOS.
+
+### Set up Docker
+
+```console
+# create a directory for the data
+mkdir -p $HOME/docker/volumes/postgres
+
+# start a container (this will use the "latest" tag. Use the version as needed)
+docker run -it --name pgsql-classroom -e POSTGRES_PASSWORD=password -d --restart unless-stopped -p 5432:5432 -v $HOME/docker/volumes/postgres:/var/lib/postgresql/data postgres:latest
+
+# change DATABASE_URL in your .env to
+postgresql://postgres:password@localhost:5432/classroom
+```
+
+## Step 3: Get the code
+
+1. Clone the project repository.
+   ```console
+   git clone https://github.com/freeCodeCamp/classroom.git
+   cd classroom
+   ```
+2. We use npm (specifically npm workspaces) to manage our dependencies.
+   ```console
+   npm ci
+   ```
+3. Create `.env` file based on the `.env.sample` file. Theses are the environment variables that are used by the application.
+
+## Step 4: Set up a NextAuth Provider App
+
+You need to set up a NextAuth Provider and run the app.
+
+For dev environments, we have enabled use of the Github Provider. Please read and follow their [guide](https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app) to set up the oauth app.
+
+## Step 5: Update .env file
+
+You will need to update the .env file inside your project with the following:
+
+- Set DataBase Url to:
+  `postgresql://postgres:password@localhost:5432/classroom`
+- Set mock user data URL to:  
+  `http://localhost:3001/data`
+
+- Set NEXTAUTH_URL to:
+  `http://localhost:3000`
+
+- Set GITHUB_ID to:
+  - Your Client ID is shown in the OAuth app page (generated at step 4). Copy and paste to GITHUB_ID.
+- Set GITHUB_SECRET to:
+  - Generate a **new** Client Secret. Then copy and paste to GITHUB_SECRET.
+
+## Additional Steps to take after finishing Local Docker Setup:
+
+1. Run the following commands in terminal to start your application.
+
+```console
+  npx prisma generate
+  npx prisma db push
+  npx prisma db seed
+  npm run develop
+```
+
+2. Open a new terminal to feed in the mock student information being used.
+
+```console
+   npm run mock-fcc-data
+```
+
+3. Open another terminal and start the ORM tool, [Prisma Studio](https://www.prisma.io/docs/concepts/overview/what-is-prisma).
+
+```console
+   npx prisma studio
+```
+
+Happy Coding!