Skip to main content

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​

AppPortStackStart command (from repo root)
Storefront8000Next.js (App Router)npm run dev:storefront
Medusa (commerce + admin)9000MedusaJS · PostgreSQLnpm run dev:medusa
NestJS API (auth, warranty, events)4000NestJS · MongoDB · Redisnpm run dev:api
Blog CMS (Payload admin)3000Payload 3 · MongoDBnpm run dev:cms
Docs (this site)3100Docusaurusnpm run dev:docs

Backing services (Docker):

ServicePortUsed by
PostgreSQL 165432Medusa (catalog, orders, pricing)
MongoDB 727017Payload CMS and NestJS domains
Redis 76379NestJS (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
One manual wiring step

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​

URLWhatLogin
http://localhost:8000Storefrontcustomer: customer@utlsolar.test / demo-pass-123
http://localhost:9000/appMedusa admin (AWX ecommerce backend)created on first /app visit, or via npx medusa user -e you@x.com -p ...
http://localhost:3000/adminPayload admin (AWX Blog backend)admin@utlsolar.test / demo-admin-pass
http://localhost:4000/healthNestJS API health—
http://localhost:3100These 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 (defaults 4000).
  • 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 :9000 then taskkill /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/.vite forces 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:up again; npm run infra:logs to inspect.