Skip to content

SETUP.md

Latest commit

 

History

History
372 lines (256 loc) · 9.87 KB

SETUP.md

File metadata and controls

372 lines (256 loc) · 9.87 KB
Raw

Setup Guide — SadPath

Complete instructions to download, run locally, deploy, and connect the frontend and backend.

Repository: github.com/shubhransh-gupta/SadPath
Web setup guide: shubhransh-gupta.github.io/SadPath/setup

Table of Contents

Prerequisites

Requirement Version
Node.js 18+ (20 recommended)
npm 9+
Git Any recent version
Chromium Installed via Playwright (see below)
Gemini API key Optional but recommended (free)

OS notes:

  • macOS, Linux, and Windows are supported
  • Playwright downloads its own Chromium binary — you do not need Chrome installed separately

Local Setup

1. Clone the repository

git clone https://github.com/shubhransh-gupta/SadPath.git
cd SadPath

2. Install dependencies

npm install

This also runs npx playwright install chromium automatically. If it fails, run manually:

npx playwright install chromium

On Linux servers you may also need:

npx playwright install-deps chromium

3. Configure environment

cp .env.example .env

Edit .env and add your Gemini API key (optional):

GEMINI_API_KEY=your_key_here

Get a free key at Google AI Studio.

Without a Gemini key, scans still work — you get real issues with rule-based summaries instead of AI-generated ones.

4. Run the full stack

npm run dev
Service URL
Frontend http://localhost:5173
Backend API http://localhost:3001
Health check http://localhost:3001/api/scan/health

Open the frontend, enter any public URL (e.g. https://example.com), and click 💥 RUN SAD PATH.

5. Run frontend and backend separately (optional)

# Terminal 1 — backend
npm run dev:server

# Terminal 2 — frontend
npm run dev:web

In local dev, the Vite dev server proxies /api requests to localhost:3001 — no VITE_API_URL needed.

6. Verify the scan works

# Health check
curl http://localhost:3001/api/scan/health

# Run a test scan
curl -N "http://localhost:3001/api/scan/stream?url=https://example.com"

Environment Variables

Copy .env.example to .env and configure:

Variable Required Default Description
PORT No 3001 Backend API port
GEMINI_API_KEY No — Google Gemini API key for AI reports
FRONTEND_URL No — Allowed CORS origin in production
VITE_API_URL No "" Backend URL for production frontend builds
GITHUB_PAGES No — Set to true when building for GitHub Pages
SKIP_PLAYWRIGHT No — Set to 1 to skip Chromium install (CI only)

Local development: only GEMINI_API_KEY is needed (optional).
Production frontend: set VITE_API_URL=https://your-backend.onrender.com
Production backend: set GEMINI_API_KEY and FRONTEND_URL

Available Scripts

Command Description
npm run dev Start frontend + backend together
npm run dev:web Frontend only (Vite dev server)
npm run dev:server Backend only (compiles + watches server)
npm run build Build frontend for production
npm run build:server Compile backend TypeScript
npm run start:server Run compiled backend (production)
npm run preview Preview production frontend build

Deployment Overview

SadPath is split into two parts:

Part Hosts On Cost
Frontend (React UI) GitHub Pages Free
Backend (Playwright API) Render / Fly.io / Oracle VM Free tier available

The frontend cannot scan websites by itself — it needs the backend running somewhere.

GitHub Pages (frontend)  →  VITE_API_URL  →  Render/Fly.io (backend)

Frontend → GitHub Pages

GitHub Pages deployment is automatic on every push to main.

First-time setup

  1. Fork or clone this repo to your GitHub account
  2. Go to Settings → Pages → Build and deployment
  3. Set source to GitHub Actions
  4. Push to main — the workflow in .github/workflows/deploy.yml deploys automatically

Your site will be at:

https://<your-username>.github.io/SadPath/

Connect frontend to your backend

  1. Go to Settings → Secrets and variables → Actions
  2. Add secret: VITE_API_URL = https://your-backend.onrender.com
  3. Re-run the deploy workflow (Actions → Deploy to GitHub Pages → Run workflow)

Backend → Render (Free)

Render offers a free web service tier — the easiest way to host the backend.

Steps

  1. Push this repo to GitHub
  2. Sign up at render.com
  3. Click New → Blueprint
  4. Connect your GitHub repo — Render reads render.yaml automatically
  5. Set environment variables in the Render dashboard:
    • GEMINI_API_KEY — your Gemini API key
    • FRONTEND_URL — your GitHub Pages URL (e.g. https://your-username.github.io)
  6. Click Deploy

Render will run:

npm install && npx playwright install chromium && npm run build:server
node server/dist/index.js

Your API will be at something like:

https://sadpath-api.onrender.com

Note: Render free tier spins down after 15 minutes of inactivity. First request after idle may take 30–60 seconds (cold start). Playwright + Chromium uses ~512 MB RAM — sufficient for most scans.

Other Free Backend Options

Platform Free Tier Playwright Support Best For
Render 750 hrs/month ✅ Good Easiest setup (uses render.yaml)
Fly.io 3 shared VMs ✅ Good More RAM control via Docker
Oracle Cloud Always-free VM (24 GB RAM) ✅ Excellent Always-on, no spin-down
Railway Trial credits only ✅ Good Quick testing
Vercel / Netlify ❌ No Serverless — Chromium too heavy
GitHub Pages ✅ ❌ Frontend only

Fly.io quick start

Create a Dockerfile in the repo root:

FROM mcr.microsoft.com/playwright:v1.49.1-noble
WORKDIR /app
COPY package*.json ./
RUN npm ci
COPY . .
RUN npm run build:server
EXPOSE 3001
CMD ["node", "server/dist/index.js"]

Deploy:

fly launch
fly secrets set GEMINI_API_KEY=your_key
fly deploy

Oracle Cloud Always Free VM

  1. Create an ARM VM (Ubuntu 22.04) on Oracle Cloud Free Tier
  2. SSH in and install Node.js 20
  3. Clone repo, run npm install && npx playwright install chromium
  4. Build and start: npm run build:server && npm run start:server
  5. Use PM2 to keep running: pm2 start server/dist/index.js
  6. Point a domain or use the public IP with nginx reverse proxy

Connect Frontend to Backend

After deploying both parts:

Step Action
1 Deploy backend to Render (or Fly.io / Oracle VM)
2 Copy backend URL (e.g. https://sadpath-api.onrender.com)
3 Add GitHub secret VITE_API_URL with that URL
4 Re-run GitHub Pages deploy workflow
5 Set FRONTEND_URL on backend to your GitHub Pages URL

Verify the connection

# Backend health
curl https://your-api.onrender.com/api/scan/health

# Test scan
curl -N "https://your-api.onrender.com/api/scan/stream?url=https://example.com"

Open your GitHub Pages URL, enter a public website, and click 💥 RUN SAD PATH.

Troubleshooting

"Scan server is offline"

The frontend cannot reach the backend.

# Check if backend is running
curl http://localhost:3001/api/scan/health

# Start backend
npm run dev:server

For production: verify VITE_API_URL is set correctly in GitHub secrets.

"Scan failed unexpectedly" / Browser launch error

Chromium is not installed.

npx playwright install chromium
npx playwright install-deps chromium   # Linux only

Render cold start takes 30–60 seconds

Normal on Render free tier. The service spins down after inactivity. First scan after idle waits for the server to wake up.

Gemini AI not generating reports

Check that GEMINI_API_KEY is set:

# Local
cat .env | grep GEMINI

# Render: Dashboard → your service → Environment → GEMINI_API_KEY

Health check shows AI status:

curl http://localhost:3001/api/scan/health
# "ai": "gemini-configured"  ← key is set
# "ai": "fallback-mode"       ← no key, rule-based summaries only

CORS errors in production

Set FRONTEND_URL on the backend to match your GitHub Pages URL exactly:

FRONTEND_URL=https://your-username.github.io

GitHub Pages shows blank page

Ensure GITHUB_PAGES=true is set during build (already configured in the workflow). Your site URL must include /SadPath/ path unless you rename the repo to <username>.github.io.

Port already in use

Change the backend port in .env:

PORT=3002

Update vite.config.ts proxy target if running locally.

Back to README · Questions? Open an issue