diff --git a/README.md b/README.md index b5f716546..6f117aa1d 100644 --- a/README.md +++ b/README.md @@ -7,7 +7,7 @@ # 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 @@ -15,31 +15,19 @@ For a while now teachers have been asking for a way to get a birds eye view of m ## 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. - -
- -Docker based setup on Linux, macOS, etc. +## 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 -``` - -
- -### 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 diff --git a/docs/GITHUB-CODESPACES-SET-UP.md b/docs/GITHUB-CODESPACES-SET-UP.md new file mode 100644 index 000000000..87d670c95 --- /dev/null +++ b/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! diff --git a/docs/GITPOD-SET-UP.md b/docs/GITPOD-SET-UP.md new file mode 100644 index 000000000..7e90e1020 --- /dev/null +++ b/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! diff --git a/docs/LOCAL-DOCKER-SET-UP.md b/docs/LOCAL-DOCKER-SET-UP.md new file mode 100644 index 000000000..6e7b67a4d --- /dev/null +++ b/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!