From b0cbe248cd752bedbdf3e154c153be024b004b8e Mon Sep 17 00:00:00 2001
From: Yen Nguyen <yen.nguyen@vibentec-it.io>
Date: Thu, 16 Oct 2025 15:43:00 +0000
Subject: [PATCH] Add How-to-run

---
 How-to-run.-.md | 65 +++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 65 insertions(+)
 create mode 100644 How-to-run.-.md

diff --git a/How-to-run.-.md b/How-to-run.-.md
new file mode 100644
index 0000000..583d278
--- /dev/null
+++ b/How-to-run.-.md
@@ -0,0 +1,65 @@
+# Development — Run both repos (Medusa backend + Next.js storefront)
+
+This workspace contains two repositories you run together:
+
+- Medusa backend: vibentecit-store — see [vibentecit-store/README.md](vibentecit-store/README.md) and [vibentecit-store/package.json](vibentecit-store/package.json)  
+  - Key config: [`medusa-config.ts`](vibentecit-store/medusa-config.ts)  
+  - Tests config: [`jest.config.js`](vibentecit-store/jest.config.js)  
+  - Example scripts: [vibentecit-store/src/scripts/README.md](vibentecit-store/src/scripts/README.md)
+
+- Next.js storefront: vibentecit-store-storefront — see [vibentecit-store-storefront/README.md](vibentecit-store-storefront/README.md)  
+  - Key files: [`next.config.js`](vibentecit-store-storefront/next.config.js) and [`check-env-variables.js`](vibentecit-store-storefront/check-env-variables.js) (function: [`checkEnvVariables`](vibentecit-store-storefront/check-env-variables.js))
+
+Use this guide to run both locally.
+
+Prerequisites
+- Node >= 18 (or the version your team enforces)
+- Yarn (workspace uses Yarn in examples)
+- A running Postgres/SQLite DB as configured by your env (see backend env vars in [`medusa-config.ts`](vibentecit-store/medusa-config.ts))
+
+Quick setup (per-repo)
+1. Backend (Medusa)
+   - cd vibentecit-store
+   - Copy env template and adjust: mv .env.template .env (or create .env with required vars referenced by [`medusa-config.ts`](vibentecit-store/medusa-config.ts))
+   - Install deps:
+     ```
+     yarn
+     ```
+   - Seed (optional):
+     ```
+     yarn seed
+     ```
+     This runs `medusa exec ./src/scripts/seed.ts` as defined in [package.json](http://_vscodecontentref_/0).
+   - Start dev server:
+     ```
+     yarn dev
+     ```
+     This runs `medusa develop` and will serve the API (default port 9000 unless overridden).
+
+2. Frontend (Next.js storefront)
+   - cd vibentecit-store-storefront
+   - Copy env template and adjust:
+     ```
+     mv [.env.template](http://_vscodecontentref_/1) [.env.local](http://_vscodecontentref_/2)
+     ```
+     Ensure you set at minimum the store connection keys (see `checkEnvVariables` — it validates `NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY` by default) and any Stripe keys if needed per [README.md](http://_vscodecontentref_/3).
+   - Install deps:
+     ```
+     yarn
+     ```
+   - Start dev server:
+     ```
+     yarn dev
+     ```
+     By default the storefront runs at http://localhost:8000 (see the storefront README).
+
+Run both together
+- Start the backend first (so the storefront can connect to the API).
+- Start the storefront after the backend is up.
+
+Common env notes
+- The storefront uses `NEXT_PUBLIC_MEDUSA_PUBLISHABLE_KEY` and optionally Medusa Cloud S3 vars ([MEDUSA_CLOUD_S3_HOSTNAME](http://_vscodecontentref_/4), [MEDUSA_CLOUD_S3_PATHNAME](http://_vscodecontentref_/5)) referenced in `next.config.js` and validated by `checkEnvVariables`.
+- The backend reads DB and CORS secrets from environment and from `medusa-config.ts`. Ensure `DATABASE_URL`, `STORE_CORS`, `ADMIN_CORS`, and `JWT_SECRET`/`COOKIE_SECRET` are set as needed.
+
+Testing
+- Backend tests use Jest. See [jest.config.js](http://_vscodecontentref_/6). Run integration/unit tests from the backend repo:
\ No newline at end of file