HOW TO RUN

Prerequisites

Install these on your system before starting the project:

• Node.js 20 or newer
• npm 10 or newer
• MongoDB connection string
• RapidAPI Judge0 API credentials
• Git (optional, but recommended for collaboration)

Required environment variables

Create a file at server/.env and add the following values:

PORT=5000
MONGODB_URI=your_mongodb_connection_string
JWT_SECRET=your_jwt_secret
JUDGE0_API_HOST=your_judge0_host
JUDGE0_API_KEY=your_rapidapi_key
GMAIL_USER=[email protected]
GMAIL_APP_PASSWORD=your_gmail_app_password
EMAIL_FROM=Synapse <[email protected]>
OTP_EXPIRY_MINUTES=10
OTP_MAX_ATTEMPTS=5

You can copy the template from server/.env.example.

If port 5000 is already in use on a machine, change the backend port in server/.env and set matching client values in client/.env:

VITE_BACKEND_PORT=5001
VITE_DEV_BACKEND_URL=http://localhost:5001
VITE_API_URL=http://localhost:5001/api
VITE_SOCKET_URL=http://localhost:5001

You can copy the template from client/.env.example.

For cross-machine local collaboration, all users must connect to the same machine running the backend. Do not have each user run their own backend if they need to join the same room.

Recommended host machine setup:

# server/.env
PORT=5000
MONGODB_URI=your_shared_mongodb_connection_string
JWT_SECRET=your_shared_jwt_secret
JUDGE0_API_HOST=judge0-ce.p.rapidapi.com
JUDGE0_API_KEY=your_judge0_api_key

# client/.env on the host machine
VITE_DEV_HOST=0.0.0.0
VITE_PORT=5173
VITE_DEV_BACKEND_URL=http://localhost:5000
VITE_API_URL=http://YOUR_LAN_IP:5000/api
VITE_SOCKET_URL=http://YOUR_LAN_IP:5000
VITE_PUBLIC_APP_URL=http://YOUR_LAN_IP:5173

Other users on the same network should open http://YOUR_LAN_IP:5173 in their browser. That makes copied invite links point to the reachable host instead of localhost.

Install dependencies

From the project root, run:

pnpm install
pnpm --filter @synapse/shared build

Turbo tasks: pnpm build, pnpm typecheck, pnpm test, pnpm lint. Legacy npm layout (npm run install:all) still works for the two apps, but pnpm workspaces are canonical (see docs/CONTRIBUTING.md).

Start the app

The backend runs in Docker (API + MongoDB + Redis + Mailpit), the frontend on the Vite dev server. From the project root:

npm run dev:api     # once: build and start the backend containers
npm run dev         # frontend only, http://localhost:5173
npm run dev:down    # stop the backend containers

OTP emails in dev land in Mailpit at http://localhost:8025.

Default local URLs

• Frontend: http://localhost:5173
• Backend: http://localhost:5000
• Health check: http://localhost:5000/api/health

Notes

• The backend can start even if MongoDB is unavailable, but authentication and room persistence will not work correctly.
• Code execution depends on valid Judge0 API credentials in server/.env.
• Shared rooms are stored in server memory right now, so everyone must use the same running backend process to collaborate in one room.
• Gmail OTP auth is enabled for both signup and login. Signup creates the account only after OTP verification, and login issues the JWT only after both password and OTP are verified.
• For Gmail, use an App Password rather than your normal inbox password. The backend sends OTPs with Nodemailer and stores temporary OTP records in MongoDB with automatic expiry.

Deployment

See docs/DEPLOY.md. One production image (root Dockerfile) serves the API, Socket.IO and the built client. It runs as a public demo from a laptop through a Cloudflare quick tunnel (docker-compose.demo.yml) or on Fly.io (fly.toml). Render and Vercel were retired.

Monitoring (P0-15)

• Health: GET /api/health returns { status, db, release, uptimeSec, requestId }.
• In-repo backstop: .github/workflows/uptime.yml probes backend /api/health + frontend root (manual-only while hosting is paused; re-enable its schedule and set BACKEND_URL / FRONTEND_URL secrets when deployed).
• Recommended: add an external monitor (UptimeRobot / Better Stack) on the same two URLs with alerting to email/Slack.