Getting Started

Getting Started

Requirements

• Node.js 22 (CI uses 22; Vite 7 needs at least 20.19)
• A MongoDB database (local mongod or MongoDB Atlas)
• Optional: Cloudflare R2 bucket and Brevo account, needed for uploads and email
• Optional: Google Chrome, used by the prerender step of the production build

frontend/ and backend/ are separate npm projects with their own package.json and lockfile.

1. Backend

cd backend
npm install
cp .env.example .env     # then edit .env
npm run dev              # nodemon ./bin/www

Key variables in backend/.env (all listed with placeholders in backend/.env.example):

Variable	Purpose
PORT	API port. The template and the Vite proxy both assume 8000
NODE_ENV	development locally, production on the server
DB_URI	MongoDB connection string
JWT_SECRET, JWT_EXPIRED_IN	JWT signing secret and lifetime
COOKIE_EXPIRE_MS	Lifetime of the auth cookie
DOMAIN	Cookie domain (the cookie is set for .<DOMAIN>)
SERVER, FRONTEND_URL	Base URLs used in links inside emails
BREVO_API_KEY, BREVO_FROM_NAME, BREVO_FROM_EMAIL	Email sending
R2_ACCOUNT_ID, R2_ENDPOINT, R2_BUCKET_NAME, R2_ACCESS_KEY_ID, R2_SECRET_ACCESS_KEY, R2_REGION, R2_PUBLIC_DOMAIN	Cloudflare R2 storage
SPREAD_CRON_ENABLED	Set to false to stop the 4-minute Myfxbook scrape during local work

Generate a strong JWT_SECRET, for example:

node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

Auth cookies are issued with secure: true, so over plain http://localhost the browser may not store the cookie. The frontend also sends the token as a Bearer header, which works locally.

2. Frontend

cd frontend
npm install
cp .env.example .env     # optional for local development
npm run dev              # http://localhost:5173

In development the app calls /api, and vite.config.js proxies /api, /images and /uploads to VITE_BACKEND_URL (default http://localhost:8000).

Variable	Purpose
VITE_API_BASE_URL	API base URL used by production builds
VITE_BASE_PATH	/ for the custom domain, /xktradingfloor/ for GitHub Pages
VITE_SITE_URL	Canonical site URL for SEO tags and the sitemap
VITE_BACKEND_URL	Target of the local dev proxy

Every VITE_ variable ends up in the public JavaScript bundle. Never put secrets in them.

3. Build and test

Command (in frontend/)	Result
npm run build	Sitemap + Vite build into frontend/docs/
npm run build:local	Same with base /
npm run build:prod	Base /, prerender homepage and blog, hydration check (used for production)
npm run build:gith	Base /xktradingfloor/, same pipeline (used for staging)
npm run preview	Serve the build on port 5173
npx playwright test	Runs tests/e2e/*.spec.js in Chromium; starts npm run dev if it is not running

The build output folder is frontend/docs/. It is listed in .gitignore, although some older build files are still tracked in the repository.

4. Signing in as an admin

New sign-ups get the User role. To work on admin or operator screens locally, change the role field of your user document in MongoDB to Admin or Operator, or have an existing admin promote you from the admin user list.