Local Setup

This guide walks you through setting up the entire Siyahfy platform on your local machine for development.

Prerequisites

Before starting, ensure you have the following installed:

Tool	Minimum Version	Required	Notes
Node.js	18.x	Yes	LTS recommended (20.x preferred)
npm	9.x	Yes	Comes with Node.js
PostgreSQL	14.x	Yes	Primary database
Redis	7.x	No	Optional — backend starts without it but caching is disabled
Git	2.x	Yes	Version control

Clone the Repository


git clone https://github.com/your-org/siyahfy.git
cd siyahfy

The repository contains all platform applications in a monorepo structure:


siyahfy/
  app.siyahfy.com/          # Vendor dashboard
  backend.siyahfy.com/       # Backend API
  backend-store.siyahfy.com/ # Storefront proxy
  editor.siyahfy.com/        # Theme editor
  store.siyahfy.com/         # Store theme
  studio.siyahfy.com/        # Developer studio
  developer.siyahfy.com/     # Developer portal
  affiliate.siyahfy.com/     # Affiliate portal
  siyahfy.com/               # Marketing site
  docs.siyahfy.com/          # Documentation site

Database Setup

1. Create the Database

Start PostgreSQL and create the siyahfy database:


# Connect to PostgreSQL
psql -U postgres
 
# Create the database
CREATE DATABASE siyahfy;
 
# Verify
\l

2. Migrations

Migrations run automatically when the backend server starts. The backend’s config/index.js checks for a _migrations tracking table and executes any pending .sql files from the migrations/ directory in alphabetical order.

You do not need to run migrations manually. Just start the backend and it handles the rest.

Backend Setup

The backend is the core API server. All frontend apps depend on it.

1. Install Dependencies


cd backend.siyahfy.com
npm install

2. Environment Variables

Create a .env file in backend.siyahfy.com/:


# Server
PORT=3003
SECRET_KEY=your-jwt-secret-key

# PostgreSQL
DB_USER=postgres
DB_HOST=localhost
DB_DATABASE=siyahfy
DB_PASSWORD=your-postgres-password
DB_PORT=5432

# Redis (optional -- server starts without it)
REDIS_URL=redis://127.0.0.1:6379

# Razorpay (test keys)
RAZORPAY_KEY_ID=rzp_test_xxxxx
RAZORPAY_SECRET_KEY=your-razorpay-secret
LIVE_RAZORPAY_KEY_ID=rzp_test_xxxxx
LIVE_RAZORPAY_KEY_SECRET=your-live-razorpay-secret

# Cashfree (test keys)
CLIENT_ID=your-cashfree-client-id
CLIENT_SECRET=your-cashfree-client-secret

# Backblaze B2 Storage
BACKBLAZE_KEY_ID=your-b2-key-id
BACKBLAZE_APP_KEY=your-b2-app-key
BACKBLAZE_BUCKET_NAME=your-bucket-name
BACKBLAZE_PRODUCTS_FOLDER=products
BACKBLAZE_REGION=us-east-005
BACKBLAZE_BUCKET_ID=your-bucket-id

# Cloudflare R2 Storage
CLOUDFLARE_ACCOUNT_ID=your-cloudflare-account-id
CLOUDFLARE_ACCESS_KEY_ID=your-r2-access-key
CLOUDFLARE_SECRET_ACCESS_KEY=your-r2-secret-key
CLOUDFLARE_BUCKET_NAME=your-r2-bucket-name
R2_PUBLIC_URL=https://your-r2-public-url.r2.dev

# Email (Gmail SMTP)
MAIL_HOST=smtp.gmail.com
MAIL_PORT=587
[email protected]
MAIL_PASSWORD="your-app-password"

# Google OAuth
GOOGLE_CLIENT_ID=your-google-client-id

# WhatsApp Business API (optional)
WHATSAPP_TOKEN=your-whatsapp-token
WHATSAPP_BUSINESS_ID=your-whatsapp-business-id

# Google Places (optional)
GOOGLE_PLACES_API_KEY=your-places-api-key

# Gemini AI (optional)
GEMINI_API_KEY=your-gemini-key

# Backend URL
BACKEND_URL=http://localhost:3003

# Free trial config
FREE_TRIAL_DAYS=7

3. Start the Backend


# Development with nodemon (auto-restart)
npx nodemon index.js
 
# Or standard start
npm start

The backend runs on port 3003. You should see:


Connected to the PostgreSQL server
Server is running on port 3003

If Redis is available, you will also see:


Redis connected successfully!

App Dashboard Setup (app.siyahfy.com)

The vendor dashboard is the primary admin and vendor interface.

1. Install Dependencies


cd app.siyahfy.com
npm install

2. Environment Variables

Create a .env.local file in app.siyahfy.com/:


WEBSITE_NAME=Siyahfy
ADMINURL=http://localhost:3003
FRONTEND_URL=http://app.siyahfy.com

# Backblaze public URL (for image display)
BACKBLAZE_URL=https://your-bucket.s3.us-east-005.backblazeb2.com

# PostgreSQL (used by Next.js server-side)
PG_USER=postgres
PG_HOST=localhost
PG_DATABASE=siyahfy
PG_PASSWORD=your-postgres-password
PG_PORT=5432

# App URLs
NEXT_PUBLIC_APP_URL=http://localhost:3003
NEXT_PUBLIC_COOKIE_DOMAIN=.siyahfy.com
NEXT_PUBLIC_STORE_URL=http://localhost:3002
NEXT_PUBLIC_EDITOR_URL=http://localhost:3001
NEXT_PUBLIC_STUDIO_URL=http://localhost:3012

# Google OAuth
NEXT_PUBLIC_GOOGLE_CLIENT_ID=your-google-client-id

# Razorpay (for client-side checkout)
RAZORPAY_KEY_ID=rzp_test_xxxxx
LIVE_RAZORPAY_KEY_ID=rzp_test_xxxxx

# Trial config
FREE_TRIAL_DAYS=7

3. Start the App


npm run dev

The dashboard runs on port 3000 (default Next.js dev port).

Theme Editor Setup (editor.siyahfy.com)

The theme editor provides a visual drag-and-drop interface for customizing store themes.

1. Install Dependencies


cd editor.siyahfy.com
npm install

2. Environment Variables

Create a .env.local file in editor.siyahfy.com/:


NEXT_PUBLIC_BACKEND_URL=http://localhost:3003
NEXT_PUBLIC_APP_URL=http://localhost:3003

3. Start the Editor


npm run dev -- --port 3001

The theme editor runs on port 3001.

Developer Studio Setup (studio.siyahfy.com)

The developer studio is where third-party developers build and test store apps.

1. Install Dependencies


cd studio.siyahfy.com
npm install

2. Environment Variables

Create a .env.local file in studio.siyahfy.com/:


ADMINURL=http://localhost:3003
NEXT_PUBLIC_API_URL=http://localhost:3002
NEXT_PUBLIC_THEME_URL=http://localhost:3002

3. Start the Studio


npm run dev -- --port 3012

The developer studio runs on port 3012.

Store Theme Setup (store.siyahfy.com)

The store theme renders the customer-facing storefront.

1. Install Dependencies


cd store.siyahfy.com
npm install

2. Start the Store


npm run dev -- --port 3002

The store theme runs on port 3002. It fetches configuration from the backend via API keys.

Developer Portal Setup (developer.siyahfy.com)

The developer portal is the public-facing site for third-party developers.

1. Install Dependencies


cd developer.siyahfy.com
npm install

2. Start the Portal


npm run dev -- --port 3010

The developer portal runs on port 3010.

Affiliate Portal Setup (affiliate.siyahfy.com)

The affiliate portal allows referral partners to manage their accounts and track earnings.

1. Install Dependencies


cd affiliate.siyahfy.com
npm install

2. Start the Portal


npm run dev -- --port 3011

The affiliate portal runs on port 3011.

Marketing Site Setup (siyahfy.com)

The marketing site is the public landing page for the platform.

1. Install Dependencies


cd siyahfy.com
npm install

2. Environment Variables

Create a .env.local file in siyahfy.com/:


NEXT_PUBLIC_APP_DOMAIN=http://localhost:3006
NEXT_PUBLIC_APP_NAME=Siyahfy
NEXT_PUBLIC_GOOGLE_CLIENT_ID=your-google-client-id
BACKEND=http://localhost:3002
NEXT_PUBLIC_LOCALE=https://app.siyahfy.com
NEXT_PUBLIC_FREE_TRIAL_DAYS=7

3. Start the Marketing Site


npm run dev -- --port 3006

The marketing site runs on port 3006.

Documentation Site Setup (docs.siyahfy.com)

The documentation site is what you are reading right now.

1. Install Dependencies


cd docs.siyahfy.com
npm install

2. Start the Docs


npm run dev

The docs site runs on port 3004.

Ports Summary

All applications and their local development ports at a glance:

Application	Directory	Port	Description
Backend API	`backend.siyahfy.com`	3003	Express.js REST API
App Dashboard	`app.siyahfy.com`	3000	Vendor & admin dashboard
Theme Editor	`editor.siyahfy.com`	3001	Visual theme editor
Store Theme	`store.siyahfy.com`	3002	Customer-facing storefront
Marketing Site	`siyahfy.com`	3006	Platform landing page
Developer Portal	`developer.siyahfy.com`	3010	Developer documentation & portal
Affiliate Portal	`affiliate.siyahfy.com`	3011	Affiliate management
Developer Studio	`studio.siyahfy.com`	3012	App development environment
Documentation	`docs.siyahfy.com`	3004	This docs site
Storefront Proxy	`backend-store.siyahfy.com`	5014	Theme routing proxy (production)

Start Order

Services must be started in the correct order because of dependencies:


1. PostgreSQL        (must be running first)
2. Redis             (optional, but start before backend if available)
3. Backend API       (port 3003 -- all frontends depend on this)
4. Any frontend app  (can start in any order after backend)

Quick Start (Minimum)

To get the core platform running, you need only three things:


# Terminal 1: Ensure PostgreSQL is running
# (it should be running as a system service)
 
# Terminal 2: Start the backend
cd backend.siyahfy.com
npm start
 
# Terminal 3: Start the dashboard
cd app.siyahfy.com
npm run dev

This gives you the backend API on http://localhost:3003 and the vendor dashboard on http://localhost:3000.

Troubleshooting

PostgreSQL Connection Refused

Make sure PostgreSQL is running and the credentials in your .env file match:


# Check if PostgreSQL is running
pg_isready -h localhost -p 5432
 
# Test connection
psql -U postgres -d siyahfy -c "SELECT 1"

Redis Connection Error

The backend logs a Redis connection error but continues to function without caching. If you need Redis:


# Check if Redis is running
redis-cli ping
# Expected: PONG
 
# Start Redis (if installed)
redis-server

Port Already in Use

If a port is occupied, either stop the conflicting process or use a different port:


# Find what is using a port (example: 3003)
# On Windows
netstat -ano | findstr :3003
 
# On macOS/Linux
lsof -i :3003
 
# Start on a different port
npm run dev -- --port 3005

CORS Issues

The backend allows requests from *.siyahfy.com domains and localhost. If you encounter CORS errors during local development, ensure your frontend is making requests to http://localhost:3003 (the backend port), not a different origin.