Running Everything Locally
This platform is a set of independent apps (not a single deployable) that run side‑by‑side in development. There's no monorepo build framework — each app keeps its own dependencies and dev server, and a thin root script starts them together.
What runs, and where
| App | Port | Stack | Start command (from repo root) |
|---|---|---|---|
| Storefront | 8000 | Next.js (App Router) | npm run dev:storefront |
| Medusa (commerce + admin) | 9000 | MedusaJS · PostgreSQL | npm run dev:medusa |
| NestJS API (auth, warranty, events) | 4000 | NestJS · MongoDB · Redis | npm run dev:api |
| Blog CMS (Payload admin) | 3000 | Payload 3 · MongoDB | npm run dev:cms |
| Docs (this site) | 3100 | Docusaurus | npm run dev:docs |
Backing services (Docker):
| Service | Port | Used by |
|---|---|---|
| PostgreSQL 16 | 5432 | Medusa (catalog, orders, pricing) |
| MongoDB 7 | 27017 | Payload CMS and NestJS domains |
| Redis 7 | 6379 | NestJS (BullMQ queues / cache) |
Prerequisites
- Node.js ≥ 20
- npm (most apps) and pnpm ≥ 9 (the Blog CMS uses pnpm)
- Docker Desktop (for Postgres / Mongo / Redis)
Quick start
# 1. Start the databases (Postgres, Mongo, Redis)
npm run infra:up
# 2. Install deps once, per app
npm --prefix apps/storefront install
npm --prefix apps/medusa install
npm --prefix apps/api install
pnpm --dir apps/blog-cms install
npm --prefix docs install
npm install # root: installs `concurrently` only
# 3. Start everything in one terminal
npm run dev
npm run dev launches all five apps together (color‑coded, prefixed logs) via concurrently. Prefer separate terminals? Run the individual dev:* scripts from the table above.
Seeding data
The NestJS API auto‑seeds demo users on boot — no command needed. Medusa and Payload need a one‑time seed:
# Medusa: catalog (8 UTL products + India/INR region) then the sale price list
cd apps/medusa
npx medusa exec ./src/scripts/seed-solar.ts
npx medusa exec ./src/scripts/seed-sale.ts # MRP strike-through + % off
# Payload: blog posts, then the header/footer globals (en/hi/ta/gu)
cd ../blog-cms
pnpm payload run src/seed.ts
pnpm payload run src/seed-site.ts
seed-solar prints a publishable API key and region id. Copy them into apps/storefront/.env as NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY and NEXT_PUBLIC_MEDUSA_REGION_ID, then restart the storefront. This is what lets the storefront read the Medusa Store API.
URLs & demo logins
| URL | What | Login |
|---|---|---|
| http://localhost:8000 | Storefront | customer: customer@utlsolar.test / demo-pass-123 |
| http://localhost:9000/app | Medusa admin (AWX ecommerce backend) | created on first /app visit, or via npx medusa user -e you@x.com -p ... |
| http://localhost:3000/admin | Payload admin (AWX Blog backend) | admin@utlsolar.test / demo-admin-pass |
| http://localhost:4000/health | NestJS API health | — |
| http://localhost:3100 | These docs | — |
The API seeds one user per persona (all @utlsolar.test): admin / demo-admin-pass, and north.manager, service.head, dealer1, customer / demo-pass-123.
Environment files
Each app reads its own .env (not committed). The values that matter most:
- Storefront →
NEXT_PUBLIC_MEDUSA_URL,NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY,NEXT_PUBLIC_MEDUSA_REGION_ID,NEXT_PUBLIC_PAYLOAD_URL(http://localhost:3000),NEXT_PUBLIC_API_URL(http://localhost:4000),NEXT_PUBLIC_DOCS_URL(http://localhost:3100),REVALIDATE_SECRET. - Medusa →
DATABASE_URL(Postgres), CORS vars,JWT_SECRET/COOKIE_SECRET,STOREFRONT_REVALIDATE_URL+REVALIDATE_SECRET(to push ISR refreshes). - NestJS API → Mongo URI,
REDIS_URL,JWT_SECRET,PORT(defaults4000). - Blog CMS (Payload) →
DATABASE_URL(Mongo),PAYLOAD_SECRET,STOREFRONT_REVALIDATE_URL+REVALIDATE_SECRET.
The shared REVALIDATE_SECRET must match between Medusa/Payload and the storefront, or on‑demand cache revalidation will 401.
Do we need a monorepo tool (Turborepo / Nx)?
Not yet. The apps are independent stacks (Medusa, Next, Nest, Payload, Docusaurus) with separate node_modules and almost no shared code, so a build‑graph/cache framework would add config without much payoff. The only real friction — “start five things at once” — is solved by the root concurrently script.
Reach for Turborepo or Nx when any of these become true:
- you extract shared packages (TS types, a design system, the Tenant Config Contract, shared ESLint config),
- you want remote build caching / affected‑only builds in CI,
- the number of apps or shared libraries grows enough that task orchestration hurts.
Until then, the lightweight root scripts are the right amount of tooling.
Troubleshooting
- A port is already in use — find and stop the stray process. On Windows:
netstat -ano | findstr :9000thentaskkill /PID <pid> /F. - Medusa keeps restarting in a loop — its dev watcher restarts on file changes; don't write a log file inside
apps/medusa/. Pipe logs outside the project instead. - Admin still shows old branding — the admin is a cached SPA bundle; hard‑refresh (Ctrl/Cmd+Shift+R). For Medusa, clearing
apps/medusa/node_modules/.viteforces a rebuild. - Storefront shows no products — confirm the Medusa seed ran and the publishable key + region id are in
apps/storefront/.env. - Docker services won't start — make sure Docker Desktop is running, then
npm run infra:upagain;npm run infra:logsto inspect.