Wayne State University - AWS Student Hub

Project Leads

• Natali Chaaban - Senior Cloud Architect | [email protected]
• Akshath Reddy - Senior Cloud Architect | [email protected]
• Akrm Al-Hakimi - President | [email protected]

---

Development Setup

The app uses concurrently to run both the frontend and the backend together.

1. Clone the Repository

git clone [email protected]:AWS-WSU/AWS-Student-Hub.git
cd AWS-Student-Hub

2. Install Dependencies

Backend:

cd backend
npm install

Frontend:

cd frontend
npm install

Root directory:

# Navigate back to the root of the repository
cd ..
npm install

3. Environment Variables

You can test most functionalities without about 50% of the environment variables. However, for more focused features and implementations, you will need the official production/development level variables to which those are only available by contacting @cachebag (Akrm Al-Hakimi) and you must be an official board member or verified club member/contributor.

🌐 Environment Variables Overview

Variable Name	Description	Required?	Who Needs This
MONGODB_URI	MongoDB connection string for the primary database	Yes	Backend
ADMIN_TOKEN	Token used for privileged admin actions	Optional	Backend
JWT_SECRET	Secret key for signing/verifying JWTs	Yes	Backend
PORT	Port for backend server	Yes	Backend
NODE_ENV	Application environment mode	Yes	Backend
CORS_ORIGIN	Allowed origins for CORS requests	Yes	Backend
AWS_ACCESS_KEY_ID	AWS credential for accessing services (e.g., S3)	Optional	Backend
AWS_SECRET_ACCESS_KEY	Secret AWS key paired with access key ID	Optional	Backend
AWS_REGION	AWS region for services	Optional	Backend
AWS_S3_BUCKET	S3 bucket name used for file uploads	Optional	Backend
SMTP_HOST	SMTP server address for sending emails	Optional	Backend
SMTP_PORT	SMTP port number	Optional	Backend
SMTP_ENCRYPTION	Email encryption method (e.g., STARTTLS)	Optional	Backend
SMTP_USER	SMTP username or email	Optional	Backend
SMTP_PASS	SMTP password or app-specific key	Optional	Backend
DISCORD_BOT_TOKEN	Invite bot token from Discord	Yes	Backend
DISCORD_GUILD_ID	Identifier for running commands through our bot	Yes	Backend
DISCORD_CHANNEL_ID	AWS Club Discord channel ID	Yes	Backend
VITE_AUTH0_DOMAIN	Auth0 domain for authentication	Yes	Frontend
VITE_AUTH0_CLIENT_ID	Public Auth0 client ID	Yes	Frontend
VITE_AUTH0_AUDIENCE	Auth0 API audience identifier	Yes	Frontend
VITE_API_URL	Base URL for frontend to connect to backend	Yes	Frontend

Frontend (.env):

VITE_AUTH0_DOMAIN=your-auth0-domain
VITE_AUTH0_CLIENT_ID=your-auth0-client-id
VITE_AUTH0_AUDIENCE=your-auth0-api-audience
VITE_API_URL=http://localhost:5001/api

Backend (.env):

# MongoDB connection string
MONGODB_URI=your-mongodb-uri

# Admin access token
ADMIN_TOKEN=your-admin-token

# Secret key for signing JWTs
JWT_SECRET=your-jwt-secret

# Backend port
PORT=5001

# Environment mode
NODE_ENV=development

# CORS configuration
CORS_ORIGIN=http://localhost:5173,http://localhost:3000

# AWS Configuration
AWS_ACCESS_KEY_ID=your-aws-access-key-id
AWS_SECRET_ACCESS_KEY=your-aws-secret-access-key
AWS_REGION=us-east-1
AWS_S3_BUCKET=aws-student-hub

# SMTP configuration for email
SMTP_HOST=smtp.gmail.com
SMTP_PORT=587
SMTP_ENCRYPTION=STARTTLS
SMTP_USER=your-email
SMTP_PASS=your-email-password

# Discord bot configuration
DISCORD_BOT_TOKEN=<contact-@cachebag-for-this>
DISCORD_GUILD_ID=<contact-@cachebag-for-this>
DISCORD_CHANNEL_ID=<contact-@cachebag-for-this>

4. Start the Application

npm run dev

Concurrently runs the appropriate scripts for both the frontend and the backend to get the site running. Under the hood, this is what npm run dev is doing:

concurrently "npm run dev --prefix frontend" "npm start --prefix backend" 

This should give you an output in your terminal that looks something like this:

5. Open the Site

Navigate to localhost:5173 in any browser, and you'll see the website. Any changes you make to either the frontend or backend should update automatically without you needing to refresh the page.

---

Contributing to a Bug Fix or Feature

Beginning to contribute is simple. By default, you cannot push any changes to the master branch, so you must first start your own branch by doing the following:

Option 1: Using VSCode or Similar IDE

Step 1: Create a New Branch

1. Open the project through VSCode or similar IDE

2. In the bottom left, click on the "master" branch symbol

   

3. Select "Create a new branch"

4. Name your branch something descriptive like feature/color-themes or fix/login-bug

   

Step 2: Develop Your Feature

1. Make your changes to the codebase

2. When ready to commit, click on the branch icon in your IDE

   

Step 3: Commit Your Changes

1. Stage your changes by clicking the commit button

   

2. You will be asked if you want to stage all your changes - click Yes

3. Enter a descriptive commit message. For example:

   fix: refactored login component to accept saved login states
   

   

4. Click the checkmark on the top right (or similar in your IDE) to accept the commit message

Step 4: Push Your Changes

1. Click the "push changes" icon to upload your changes to GitHub

   

Step 5: Create a Pull Request

1. Navigate to the GitHub repository

2. You should see a notification like this - click to open your pull request for review by one of the project leads

   

Option 2: Using Terminal

If you are comfortable with the terminal, making changes and pushing them to git is straightforward:

Step 1: Make Your Changes

Simply make your changes using any IDE of your choice.

Step 2: Stage and Commit

Open a terminal window, navigate to the project directory, and execute the following commands in order:

1. Stage your changes:

   git add .
   # or for specific files:
   git add <the-file-you-want-to-commit>

2. Commit with a descriptive message:

   git commit -m "Your commit message goes here about what your changes do"

3. Push your changes to your branch:

   git push origin <your-branch-name>

Step 3: Create Pull Request

Repeat Step 5 from the VSCode instructions above.

---

Troubleshooting 🛠️

If you run into issues getting the app up and running, here are some common problems and their solutions:

❌ Permission denied (publickey) when cloning the repo

Cause: You don't have your SSH key linked to your GitHub account, or no SSH key is set up on your device.

Solution:

1. Check for existing SSH key:

   ls -al ~/.ssh

   Look for files like id_rsa.pub or id_ed25519.pub.

2. Generate a new SSH key (if none exists):

   ssh-keygen -t ed25519 -C "[email protected]"

3. Add your SSH key to the ssh-agent:

   eval "$(ssh-agent -s)"
   ssh-add ~/.ssh/id_ed25519

4. Copy and add the key to GitHub:

   # macOS
   pbcopy < ~/.ssh/id_ed25519.pub
   
   # Windows/Linux - manually copy the output
   cat ~/.ssh/id_ed25519.pub

   Then go to GitHub SSH Settings and add your key.

❌ npm install fails or throws errors

Common causes:

• Using an outdated version of Node.js
• Missing build tools (especially on Windows)
• Cache issues

Solutions:

1. Ensure Node.js is installed:

   • Install Node.js from the official website
   • Check your Node version: node -v
   • Use Node v18+ (consider using nvm to manage versions):

     nvm install 18
     nvm use 18

2. Clear the npm cache:

   npm cache clean --force

3. Remove node_modules and package-lock.json, then reinstall:

   rm -rf node_modules package-lock.json
   npm install

4. On Windows (for node-gyp errors):

   npm install --global windows-build-tools

❌ Port already in use (e.g., EADDRINUSE :5173)

Solution: Kill the process using the port, or use a different port:

# macOS/Linux:
lsof -i :5173
kill -9 <PID>

# Windows:
netstat -ano | findstr :5173
taskkill /PID <PID> /F

❌ Frontend not auto-refreshing on changes

Solutions:

• Ensure you're running the app via npm run dev from the root directory
• Try restarting the Vite server (Ctrl + C and then npm run dev again)
• Make sure your file changes are inside the frontend/src directory and not outside the watched paths

---

Need Help?

If you're still stuck after trying the troubleshooting steps above, feel free to reach out to any of the project leads for assistance.