Customer Portal — Local Dev Setup
Status: populated Owner: Product Engineering (Frontend) Last updated: 2026-04-18
1. Prerequisites
| Tool | Version | Install |
|---|---|---|
| Node.js | 20 LTS | nvm install 20 |
| pnpm | 9.x | npm install -g pnpm |
| Docker Desktop | latest | docker.com |
| Firebase CLI | latest | npm install -g firebase-tools |
2. Clone and Install
git clone https://github.com/ghasitech/ghasi-sms-gateway.git
cd ghasi-sms-gateway/services/customer-portal
pnpm install
3. Environment Configuration
cp .env.example .env.local
Edit .env.local:
# API (point to local Kong or mock)
API_BASE_URL=http://localhost:8000
NEXT_PUBLIC_API_BASE_URL=http://localhost:8000
# Firebase (use a dev Firebase project)
NEXT_PUBLIC_FIREBASE_API_KEY=AIza...
NEXT_PUBLIC_FIREBASE_AUTH_DOMAIN=ghasi-dev.firebaseapp.com
FIREBASE_PROJECT_ID=ghasi-dev
# Session encryption (generate with: openssl rand -hex 32)
SESSION_SECRET=<32-byte-hex-string>
SESSION_COOKIE_SECURE=false
4. Local Backend Options
Option A: Run Kong + backend services locally (full stack)
# From repo root
docker compose up kong auth-service sms-orchestrator billing-service webhook-dispatcher
Option B: Use mock API server (MSW)
The portal includes a Mock Service Worker setup for frontend development without a running backend.
pnpm dev:mock
MSW handlers are in src/mocks/handlers/. Mock data is in src/mocks/fixtures/.
5. Run Development Server
pnpm dev
App available at http://localhost:3000.
6. Running Tests
# Unit tests (Vitest)
pnpm test
# Unit tests with coverage
pnpm test:coverage
# E2E tests (Playwright)
pnpm e2e
# E2E tests (headful)
pnpm e2e:headed
7. Firebase Emulator (Optional)
For offline Firebase Auth without a live Firebase project:
firebase emulators:start --only auth
Set NEXT_PUBLIC_FIREBASE_AUTH_EMULATOR_HOST=127.0.0.1:9099 in .env.local.
8. Storybook
Component-level development:
pnpm storybook
Available at http://localhost:6006.
9. Common Issues
| Issue | Fix |
|---|---|
SESSION_SECRET must be 32 bytes | Generate with openssl rand -hex 32 |
| Firebase SDK warning about emulator | Set NEXT_PUBLIC_FIREBASE_AUTH_EMULATOR_HOST |
| Kong 401 on all API calls | Ensure JWT is valid; check clock skew on dev machine |
| CORS errors from browser | All API calls go through Next.js route handlers (server-side); browser never calls Kong directly |