Development Setup

Everything needed to run every part of the ecosystem locally. Sections are independent — set up only what you're working on.

Prerequisites

Tool	Needed for	Notes
Node.js ≥ 20 + npm	website, docs, JS tooling	Vite 7 / VitePress require modern Node
Python 3.10+	ediky_tools pipelines	plus pip install -r per tool where present
g++ / python3 / java	qgen verification	solutions are cross-verified in C++, Python, Java
Wrangler (npm i -g wrangler)	Pages Functions + Workers locally	one CLI for the whole Cloudflare surface
A Firebase project	auth + Firestore	free Spark tier is enough for development

1. The website (ediky-website/ediky/)

git clone <ediky-website>
cd ediky-website/ediky
npm install
cp .env.example .env        # fill in the VITE_FIREBASE_* + VITE_CLOUDINARY_* values
npm run dev                 # Vite dev server (SPA only — no Functions)

npm run dev serves the SPA. AI grading, code running, and notes fetching go through Pages Functions, which Vite doesn't emulate — for those, run through Wrangler instead:

npm run build               # build-content.mjs + lint + vite build → dist/
npx wrangler pages dev dist # SPA + functions/ together, with local env bindings

Server-side keys for local Functions go in .dev.vars (see .dev.vars.example): any of the AI provider keys (GEMINI_API_KEY, GROQ_API_KEY, …), JUDGE0_URL/JUDGE0_TOKEN for code running, and GITHUB_TOKEN for Docy notes. Every one is optional — each Function degrades explicitly (the AI routes fall back to an honest echo stub; notes return a clear "token missing" error).

Firestore rules are in firestore-rules/firestore.rules — deploy them to your dev project with the Firebase CLI (firebase deploy --only firestore:rules) or paste them in the console. Without rules deployed, client reads/writes will be denied.

2. Ediky Tools (ediky_tools/)

Clone as a sibling of the website (the pipelines resolve the website checkout automatically):

code/
├── ediky_tools/
└── ediky-website/
    └── ediky/          ← app root

If your layout differs: export EDIKY_WEBSITE_ROOT=/path/to/ediky-website/ediky. Sanity-check resolution any time:

python3 tools/site_config.py

Then, per pipeline (details in the Tools section):

# DSA
python3 tools/qgen/qgen.py drafts/<slug>.md

# CS fundamentals / Aptitude / SQL
python3 tools/cs_pipeline.py drafts/cs/<slug>.md
python3 tools/aptitude_pipeline.py drafts/aptitude/<slug>.md
python3 tools/sql_pipeline.py drafts/sql-practice/<slug>.md

The qgen verifiers auto-detect the Python interpreter on Windows (py -3 / python), so the same commands work cross-platform.

3. Docy

No build. Clone, edit markdown under the subject folder, push. The live site picks changes up on the next /get-notes fetch — no website deploy required. Keep the numeric filename convention (<index>.md) since list-notes ordering and playlist mapping rely on it.

4. This docs portal (ediky-core → Ediky Workflow)

git clone <ediky-core>
cd ediky-core
npm install
npm run dev        # regenerates the AI index, then vitepress dev (http://localhost:5173)

The Ask AI widget needs the Pages Function, which vitepress dev doesn't run. To exercise it locally:

npm run build
npx wrangler pages dev docs/.vitepress/dist
# add an AI key for real answers:
#   echo 'GEMINI_API_KEY=...' >> .dev.vars

Without a key the assistant answers with the labelled echo stub — useful for UI work, honest about not being a real model.

5. Workers (optional, production-focused)

Each Worker directory (worker/, worker-reminders/) is its own Wrangler project:

cd worker-reminders
npx wrangler dev          # local run with .dev.vars
npx wrangler deploy       # cron goes live per wrangler.toml

Both authenticate to Firestore with a service account (RS256 JWT → OAuth2 token → REST). Store the private key with wrangler secret put — never in the repo. See Cloudflare Workers for their exact claim/retry semantics before touching either.

Common first-run failures

Symptom	Cause → fix
Login loops / permission-denied	Firestore rules not deployed to your dev project
AI verdicts say [echo provider]	No provider key in .dev.vars / Pages env — expected, add one
/get-notes 500 "token missing"	GITHUB_TOKEN not set server-side
Judge0 calls hang from Functions	direct-IP blocked by Cloudflare egress — use the DNS A-record hostname, not the raw IP
Pipeline "website root not found"	repos not siblings → set EDIKY_WEBSITE_ROOT

More in Troubleshooting.