chore: update dev ports to avoid conflicts with fCC Proper

.devcontainer/devcontainer.json

@@ -36,7 +36,7 @@
 
 	// Use 'forwardPorts' to make a list of ports inside the container available locally.
 	// This can be used to network with other containers or with the host.
-	"forwardPorts": [3000, 3001, 5432, 5555],
+	"forwardPorts": [3001, 3002, 5432, 5555],
 
 	// Use 'postCreateCommand' to run commands after the container is created.
 	// "postCreateCommand": "yarn install",

.env.sample

@@ -1,8 +1,8 @@
 DATABASE_URL="postgresql://postgres:password@localhost:5432/classroom"
 #if you are on gitpod, MOCK_USER_DATA_URL is https://30001-XXXXX.XXXXX.gitpod.io/data
-MOCK_USER_DATA_URL = "http://localhost:3001/data"
+MOCK_USER_DATA_URL = "http://localhost:3002/data"
 #if you are on gitpod, NEXTAUTH_URL is https://3000-XXXXX.XXXXX.gitpod.io/
-NEXTAUTH_URL="http://localhost:3000"
+NEXTAUTH_URL="http://localhost:3001"
 
 #set NEXTAUTH_SECRET with random string (can create via commandline `openssl rand -base64 32`)
 #https://next-auth.js.org/configuration/options#secret
@@ -12,7 +12,7 @@ NEXTAUTH_SECRET=abcdefghijlmnopqrstuvwxyz
 #If you are a dev contributing to the project, it is easier to setup a github provider than an Auth0 one.
 #Auth0 will be the only provider allowed on production however.
 #https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app
-#If running on your local machine, the callback URL will normally be https://localhost:3000/api/auth/callback/github
+#If running on your local machine, the callback URL will normally be http://localhost:3001/api/auth/callback/github
 
 GITHUB_ID=
 GITHUB_SECRET=

README.md

@@ -31,7 +31,7 @@ If you have used GitHub Codespaces in other projects, doing the same in freeCode
 
 Within freeCodeCamp Classroom, GitHub Codespaces is on par with Gitpod so that you can use either.
 
-This [video](https://www.loom.com/share/37dcb9555ad642618d82619277daaa38?sid=c17189b2-5798-44c9-8b74-38749f3578e1) walks through the setup process on Github Codespaces.  Note that this video was recorded on Feb 10, 2025.  It is not guaranteed to be up to date with any new setup instructions added after that date. 
+This [video](https://www.loom.com/share/37dcb9555ad642618d82619277daaa38?sid=c17189b2-5798-44c9-8b74-38749f3578e1) walks through the setup process on Github Codespaces. Note that this video was recorded on Feb 10, 2025. It is not guaranteed to be up to date with any new setup instructions added after that date.
 
 ### Optional - GitPod Dev Environment
 
@@ -95,8 +95,137 @@ postgresql://postgres:password@localhost:5432/classroom
 8. Run `npm run mock-fcc-data`
 9. Run `npx prisma studio`
 
+**Note:** The classroom app runs on port 3001 and mock data on port 3002 to avoid conflicts with freeCodeCamp's main platform (ports 3000/8000).
+
 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.
 
+---
+
+### Authentication Setup
+
+The Classroom application supports two authentication providers: **GitHub OAuth** (recommended for contributors) and **Auth0** (required for production). You must configure at least one provider to use the application.
+
+For FCC Proper integration, install the application locally and use Auth0 for authentication.
+
+#### GitHub OAuth Setup (Recommended for Development)
+
+1. Go to GitHub Settings → Developer Settings → OAuth Apps
+2. Click "New OAuth App" and fill in:
+   - **Application name**: FreeCodeCamp Classroom (or your preferred name)
+   - **Homepage URL**: `http://localhost:3001` (or the URL shown in your terminal)
+   - **Authorization callback URL**: `http://localhost:3001/api/auth/callback/github`
+3. After creating the app, copy the Client ID and Client Secret to your `.env` file:
+   ```
+   GITHUB_ID=your_client_id_here
+   GITHUB_SECRET=your_client_secret_here
+   GITHUB_OAUTH_PROVIDER_ENABLED=true
+   ```
+
+#### Auth0 Setup (Production & Advanced Development)
+
+**Important:** Auth0 callback URLs must exactly match your application URL including the port number. After changing ports, you must update your Auth0 application settings.
+
+##### Creating an Auth0 Application
+
+1. Go to [auth0.com](https://auth0.com/) and create an account (or sign in)
+2. Click "Create Application" and select "Regular Web Applications"
+3. Select "Next.js" as your technology
+4. Navigate to the "Settings" tab (do NOT follow the "integrate with my app" tutorial)
+
+##### Auth0 Configuration Mapping
+
+Copy the following values from your Auth0 Application Settings to your `.env` file:
+
+| Auth0 Setting | .env Variable         | Example Value                                        |
+| ------------- | --------------------- | ---------------------------------------------------- |
+| Client ID     | `AUTH0_CLIENT_ID`     | `abcdefghijklmnopqrstuvwxyz0123456789`               |
+| Client Secret | `AUTH0_CLIENT_SECRET` | `abcdefghijklmnopqrstuvwxyz0123456789-LONGER_STRING` |
+| Domain        | `AUTH0_ISSUER`        | `https://your-tenant.us.auth0.com`                   |
+
+**Note:** Do NOT include a trailing slash in `AUTH0_ISSUER`.
+
+##### Auth0 Application URLs (Critical for Port Changes)
+
+In your Auth0 Application Settings, configure these URLs based on your environment:
+
+**For Local Development (localhost:3001):**
+
+| Auth0 Setting         | Value                                           |
+| --------------------- | ----------------------------------------------- |
+| Allowed Callback URLs | `http://localhost:3001/api/auth/callback/auth0` |
+| Allowed Logout URLs   | `http://localhost:3001`                         |
+
+**For GitHub Codespaces:**
+
+| Auth0 Setting         | Value                                                                  |
+| --------------------- | ---------------------------------------------------------------------- |
+| Allowed Callback URLs | `https://{CODESPACE_NAME}-3001.app.github.dev/api/auth/callback/auth0` |
+| Allowed Logout URLs   | `https://{CODESPACE_NAME}-3001.app.github.dev`                         |
+
+**Note:** Auth0 allows multiple callback URLs separated by commas. You can add all your development environments to support seamless switching.
+
+##### Running with freeCodeCamp Proper Locally
+
+If you need to run Classroom alongside freeCodeCamp's main platform (fCC Proper) on the same machine:
+
+**Prerequisites:**
+
+- Both applications MUST run on the same domain (`localhost`) for authentication to work correctly
+- Both applications MUST be installed locally (Codespaces/Gitpod won't work for this setup)
+- Port separation is **required** to avoid conflicts
+
+**Port Configuration:**
+
+- fCC Proper: `localhost:8000` (frontend) + `localhost:3000` (backend)
+- Classroom: `localhost:3001` (app) + `localhost:3002` (mock data)
+
+**Auth0 Configuration for local FCC Proper integration with local FCC Classroom - Dual Setup:**
+
+Add BOTH callback URLs to your Auth0 Application Settings:
+
+| Auth0 Setting         | Value                                                                                      |
+| --------------------- | ------------------------------------------------------------------------------------------ |
+| Allowed Callback URLs | `http://localhost:3000/auth/auth0/callback, http://localhost:3001/api/auth/callback/auth0` |
+| Allowed Logout URLs   | `http://localhost:3000, http://localhost:3001`                                             |
+
+**Why This Matters:**
+
+- Authentication tokens/sessions are domain-scoped
+- `localhost:3000` and `localhost:3001` share the same domain (`localhost`)
+- This allows both apps to access the same Auth0 session
+- Different domains (e.g., Codespaces URLs) would NOT share authentication state
+
+##### Debugging Authentication Issues
+
+**If authentication fails:**
+
+1. Check Auth0 logs in the dashboard for detailed error messages
+2. Verify your `.env` file URLs match your current environment
+3. Inspect browser network tab for failed `authorize` requests:
+   - Press `Ctrl+Shift+I` (or `Cmd+Option+I` on Mac)
+   - Go to Network tab
+   - Look for failed (red) `authorize` requests
+   - Click on it and check "Preview" to see the expected callback URL
+4. Ensure all Auth0 Application Settings are saved (scroll to bottom of settings page)
+5. Verify the email used for Auth0 matches your GitHub account email
+
+**Common Issues:**
+
+- **"Callback URL mismatch"**: Your Auth0 Allowed Callback URLs don't include the exact URL being used
+- **"Invalid state"**: Session/cookie issue, try clearing cookies for localhost
+- **401 Unauthorized**: Check that `NEXTAUTH_SECRET` is set in your `.env` file
+
+##### Production Deployment Notes
+
+In production environments with separate domains (e.g., `classroom.freecodecamp.org` and `freecodecamp.org`):
+
+- Port numbers are handled by reverse proxies (external port 80/443)
+- Auth0 callback URLs use domain names, not ports: `https://classroom.freecodecamp.org/api/auth/callback/auth0`
+- No port conflicts occur because domains are different
+- The port changes in this repository are primarily for local development
+
+---
+
 ### Join us in our [Discord Chat](https://discord.gg/qcynkd4Edx) here.
 
 ---

codespace-instructions.sh

@@ -10,15 +10,15 @@ Almost done! Just need to set up a NextAuth Provider and run the app.
 https://docs.github.com/en/developers/apps/building-oauth-apps/creating-an-oauth-app
 
 The mock user data URL is:
-https://${CODESPACE_NAME}-3001.app.github.dev/data
+https://${CODESPACE_NAME}-3002.app.github.dev/data
 
 The homepage is:
-https://${CODESPACE_NAME}-3000.app.github.dev
+https://${CODESPACE_NAME}-3001.app.github.dev
 
 The callback URL is:
-https://${CODESPACE_NAME}-3000.app.github.dev/api/auth/callback/github
+https://${CODESPACE_NAME}-3001.app.github.dev/api/auth/callback/github
 
-2.) Set NEXTAUTH_URL in .env to https://${CODESPACE_NAME}-3000.app.github.dev
+2.) Set NEXTAUTH_URL in .env to https://${CODESPACE_NAME}-3001.app.github.dev
 
 3.) To setup GITHUB_ID and GITHUB_SECRET after setting up the OAuth app:
 -Your Client ID is shown in the OAuth app page. Copy and paste it to GITHUB_ID.
@@ -38,7 +38,7 @@ Additional Steps to take After Finishing Codespaces Setup:
 
 6.) Run npm run mock-fcc-data
 
-7.) Go to the ports tab and set the visibility to public for the 3000 and 3001 ports.
+7.) Go to the ports tab and set the visibility to public for the 3001 and 3002 ports.
 
 8.) Optional: To connect to a PostgreSQL server in a db container via psql PostgreSQL client in this app container
 

package.json

@@ -18,7 +18,7 @@
   },
   "homepage": "https://github.com/freecodecamp/classroom#readme",
   "scripts": {
-    "develop": "next dev",
+    "develop": "next dev -p 3001",
     "build": "next build",
     "start": "next start",
     "test:watch": "jest --watch",
@@ -28,7 +28,7 @@
     "lint:pretty": "prettier --ignore-path .gitignore --check  .",
     "format": "prettier --ignore-path .gitignore --write .",
     "prepare": "husky install",
-    "mock-fcc-data": "npx json-server --watch mock-json-server/fccdata.json --port 3001"
+    "mock-fcc-data": "npx json-server --watch mock-json-server/fccdata.json --port 3002"
   },
   "dependencies": {
     "@headlessui/react": "1.7.17",