Skip to content

Getting Started

Jump to bottom
Laith edited this page May 25, 2026 · 2 revisions

Everything you need to run GeeksHub locally from scratch.

Prerequisites

Tool Version Purpose
Node.js ≥ 18 Frontend build + dev server
npm ≥ 9 Package management
Python 3.11 Backend runtime
Git any Source control

You also need accounts and credentials for:

  • Neon — PostgreSQL database (free tier works)
  • Auth0 — authentication (free tier works)
  • Google Cloud — GCS bucket + service account
  • Google AI Studio — Gemini API key (free tier: 15 RPM)

Step 1: Clone and install

git clone https://github.com/your-org/geekshub.git
cd geekshub

Frontend


npm install


Backend


cd server
python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt

Step 2: Auth0 setup

  1. Create a new Auth0 Application (type: Regular Web Application).
  2. Enable the Username-Password-Authentication connection.
  3. Create a Machine-to-Machine (M2M) application authorised for the Auth0 Management API with scopes: create:users, read:users, delete:users.
  4. Create an API in Auth0. Set the identifier — this is your AUTH0_AUDIENCE.
  5. In your application settings, add http://localhost:5173 to Allowed Callback URLs and Allowed Logout URLs.

Step 3: Google Cloud setup

  1. Create a GCS bucket. Enable public access prevention (files are served via signed URLs only).
  2. Create a service account with the Storage Admin role for that bucket.
  3. Download the JSON key file → save as server/gcp_key.json.
  4. Set up a lifecycle rule on the bucket: delete objects with the prefix trash_bin/ after 3 days.

Step 4: Environment variables

Create server/.env:

# Database
DATABASE_URL=postgresql://user:pass@host/dbname?sslmode=require

Auth0


AUTH0_DOMAIN=your-tenant.us.auth0.com
AUTH0_M2M_ID=your-m2m-client-id
AUTH0_M2M_SECRET=your-m2m-client-secret
AUTH0_AUDIENCE=https://your-api-audience


AI


GEMINI_API_KEY=AIza...


Storage


BUCKET_NAME=your-bucket-name
GOOGLE_APPLICATION_CREDENTIALS=gcp_key.json


App


FRONTEND_URL=http://localhost:5173
ENVIRONMENT=development

Step 5: Seed the database

On first run, the FastAPI lifespan hook calls init_db() which creates all tables. Then seed catalog data:

cd server
python seed.py

This creates material types (Summary, Exam, Lecture Notes, Slides). To add majors and courses, either add them to seed.py or insert directly:

INSERT INTO majors (id, name, slug) VALUES (gen_random_uuid(), 'Software Engineering', 'software-engineering');

Step 6: Run

# From project root — runs both frontend and backend
npm run dev:all

Or separately:


npm run dev                          # Frontend → http://localhost:5173
cd server && uvicorn main:app --reload --port 8000   # Backend → http://localhost:8000

Verify backend is running:

curl http://localhost:8000/api/v1/health
# → {"status":"online","database":"connected"}

Step 7: Create your first accounts

  1. Navigate to http://localhost:5173/auth.
  2. Sign up with an @post.jce.ac.il email.
  3. Check your email and verify it (Auth0 sends verification on sign-up).
  4. Sign in.

To create an admin account, sign up normally, then update the role directly in the database:

UPDATE users SET role = 'ADMIN' WHERE email = 'you@post.jce.ac.il';

Running tests

npm run test:run        # Vitest unit tests
npx tsc --noEmit        # TypeScript check
npm run lint            # ESLint
npm run build           # Production build check

Backend tests: a pytest suite is not yet present. See Contributing for the plan.

Common first-run issues

See Troubleshooting for fixes. The most common:

  • 401 on all API calls — Auth0 credentials wrong or M2M app not authorised for Management API.
  • 500 on file upload — GCS credentials missing or GOOGLE_APPLICATION_CREDENTIALS path wrong.
  • Majors dropdown empty — seed.py hasn't been run or database tables not created yet.
  • PDF viewer blank — GCS bucket permissions issue; check signed URL generation in backend console.
# Getting Started

Everything you need to run GeeksHub locally from scratch.

Prerequisites

Tool Version Purpose
Node.js ≥ 18 Frontend build + dev server
npm ≥ 9 Package management
Python 3.11 Backend runtime
Git any Source control

You also need accounts and credentials for:

  • Neon — PostgreSQL database (free tier works)
  • Auth0 — authentication (free tier works)
  • Google Cloud — GCS bucket + service account
  • Google AI Studio — Gemini API key (free tier: 15 RPM)

Step 1: Clone and install

git clone https://github.com/your-org/geekshub.git
cd geekshub

# Frontend
npm install

# Backend
cd server
python -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt

Step 2: Auth0 setup

  1. Create a new Auth0 Application (type: Regular Web Application).
  2. Enable the Username-Password-Authentication connection.
  3. Create a Machine-to-Machine (M2M) application authorised for the Auth0 Management API with scopes: create:users, read:users, delete:users.
  4. Create an API in Auth0. Set the identifier — this is your AUTH0_AUDIENCE.
  5. In your application settings, add http://localhost:5173 to Allowed Callback URLs and Allowed Logout URLs.

Step 3: Google Cloud setup

  1. Create a GCS bucket. Enable public access prevention (files are served via signed URLs only).
  2. Create a service account with the Storage Admin role for that bucket.
  3. Download the JSON key file → save as server/gcp_key.json.
  4. Set up a lifecycle rule on the bucket: delete objects with the prefix trash_bin/ after 3 days.

Step 4: Environment variables

Create server/.env:

# Database
DATABASE_URL=postgresql://user:pass@host/dbname?sslmode=require

# Auth0
AUTH0_DOMAIN=your-tenant.us.auth0.com
AUTH0_M2M_ID=your-m2m-client-id
AUTH0_M2M_SECRET=your-m2m-client-secret
AUTH0_AUDIENCE=https://your-api-audience

# AI
GEMINI_API_KEY=AIza...

# Storage
BUCKET_NAME=your-bucket-name
GOOGLE_APPLICATION_CREDENTIALS=gcp_key.json

# App
FRONTEND_URL=http://localhost:5173
ENVIRONMENT=development

Step 5: Seed the database

On first run, the FastAPI lifespan hook calls init_db() which creates all tables. Then seed catalog data:

cd server
python seed.py

This creates material types (Summary, Exam, Lecture Notes, Slides). To add majors and courses, either add them to seed.py or insert directly:

INSERT INTO majors (id, name, slug) VALUES (gen_random_uuid(), 'Software Engineering', 'software-engineering');

Step 6: Run

# From project root — runs both frontend and backend
npm run dev:all

# Or separately:
npm run dev                          # Frontend → http://localhost:5173
cd server && uvicorn main:app --reload --port 8000   # Backend → http://localhost:8000

Verify backend is running:

curl http://localhost:8000/api/v1/health
# → {"status":"online","database":"connected"}

Step 7: Create your first accounts

  1. Navigate to http://localhost:5173/auth.
  2. Sign up with an @post.jce.ac.il email.
  3. Check your email and verify it (Auth0 sends verification on sign-up).
  4. Sign in.

To create an admin account, sign up normally, then update the role directly in the database:

UPDATE users SET role = 'ADMIN' WHERE email = 'you@post.jce.ac.il';

Running tests

npm run test:run        # Vitest unit tests
npx tsc --noEmit        # TypeScript check
npm run lint            # ESLint
npm run build           # Production build check

Backend tests: a pytest suite is not yet present. See [Contributing](Contributing) for the plan.

Common first-run issues

See [Troubleshooting](Troubleshooting) for fixes. The most common:

  • 401 on all API calls — Auth0 credentials wrong or M2M app not authorised for Management API.
  • 500 on file upload — GCS credentials missing or GOOGLE_APPLICATION_CREDENTIALS path wrong.
  • Majors dropdown empty — seed.py hasn't been run or database tables not created yet.
  • PDF viewer blank — GCS bucket permissions issue; check signed URL generation in backend console.

Clone this wiki locally