_                         _
| |__   ___  _ __ ___  ___| |__   __ _ ___  ___
| '_ \ / _ \| '_ ` _ \/ _ \ '_ \ / _` / __|/ _ \
| | | | (_) | | | | | |  __/ |_) | (_| \__ \  __/
|_| |_|\___/|_| |_| |_|\___|_.__/ \__,_|___/\___|

A prototype community web app for SJSU students, built as a Dockerized MVC application and deployed via Coolify.

Architecture

                        [ Browser ]
                             |
                    [ Coolify / Nginx ]
                             |
          ┌──────────────────┴──────────────────┐
          |                                     |
   [ Frontend :3000 ]                  [ Backend :4000 ]
     React + Vite                      Node.js + Express
     (static SPA)                      (REST API / MVC)
                                              |
                                    [ MongoDB :27017 ]
                                      (persistent vol)

Three Docker containers, orchestrated with docker-compose.yml:

Container	Tech	Role
frontend	React + Vite	SPA served as static assets
backend	Node.js/Express	REST API, business logic, auth
mongodb	MongoDB 7	Database, data persisted via volume

Auth

User authentication is handled via Okta SSO using SJSU accounts. The frontend redirects users through Okta's login flow and receives a JWT access token. The backend validates that token on protected routes using @okta/jwt-verifier.

Dev Setup

Two ways to run the app locally. Use Local (Node + Vite) for day-to-day development and fast feedback; use Docker to mirror production or run everything in one command.

Local (Node + Vite) — recommended for contributors

Best for students and contributors: clone, install, run. No Docker required for the app (only MongoDB, or use a local MongoDB install).

Prerequisites: Node.js 18+, npm. MongoDB (local install or Docker).

1. MongoDB — one of:

   • Install MongoDB locally, or
   • Run only MongoDB in Docker: docker run -d -p 27017:27017 --name homebase-mongo mongo:7

2. Backend

   cd backend
   cp .env.example .env
   # Edit .env: set OKTA_ISSUER, OKTA_AUDIENCE; set MONGO_URI=mongodb://localhost:27017/homebase and FRONTEND_URL=http://localhost:5173
   npm install
   npm run dev

   Leave this running (API on http://localhost:4000).

3. Frontend (new terminal)

   cd frontend
   cp .env.example .env
   # Edit .env: set VITE_OKTA_ISSUER, VITE_OKTA_CLIENT_ID, VITE_OKTA_REDIRECT_URI=http://localhost:5173/login/callback
   npm install
   npm run dev

   Open http://localhost:5173. The app proxies /api to the backend.

4. Okta: In your Okta app (e.g. dev tenant), add Sign-in redirect URI http://localhost:5173/login/callback so login works when using Vite on port 5173.

---

Docker (full stack)

Use when you want the same setup as production or a single command to run everything.

Prerequisites: Docker, Docker Compose.

1. Copy env and set Okta in backend/.env (see backend .env.example). Create a root .env with VITE_OKTA_ISSUER, VITE_OKTA_CLIENT_ID, VITE_OKTA_REDIRECT_URI=http://localhost:3000/login/callback so the frontend image can be built.
2. In the Okta app, ensure http://localhost:3000/login/callback is a Sign-in redirect URI.
3. From the repo root: docker compose -f docker-compose.yml -f docker-compose.local.yml up --build
   • Frontend: http://localhost:3000
   • Backend API: http://localhost:4000
   • MongoDB runs inside the compose network only (not published on the host).

---

Contributing and deployment

• Development: Work locally with the Node + Vite setup above. Commit and push to the repo.
• Deployment: Coolify watches the repo; pushes to the default branch trigger an automatic build and deploy on the server. No manual file copying — students and maintainers push to git, Coolify handles the rest.

Deployment

The app is designed to deploy to a clean Ubuntu instance via Coolify. Coolify pulls the repo, builds the Docker images, and manages the containers. No manual server setup required beyond pointing Coolify at the repository.

Currently being developed and tested on a Raspberry Pi (ARM). Docker images should be verified for amd64 compatibility before production deployment.