Skip to main content

Getting Started

This guide walks you through setting up the CivicPulse platform locally — from cloning the repository to running both the frontend and backend with live reload.

Prerequisites​

Before you begin, ensure the following tools are installed and configured:

RequirementMinimum VersionNotes
Node.js18.x LTSRequired for both frontend and backend
npm9.xComes with Node 18
AWS CLI2.xFor DynamoDB and S3 access
GitAny recent version

AWS CLI Configuration​

CivicPulse uses DynamoDB for issue storage and S3 for media uploads. Configure your AWS credentials before starting:

aws configure
# AWS Access Key ID:     <your-access-key>
# AWS Secret Access Key: <your-secret-key>
# Default region name:   ap-south-1
# Default output format: json

For local development, you can use LocalStack as a drop-in replacement for AWS services, or point to a real AWS account with appropriate IAM permissions.

Required IAM permissions:

  • dynamodb:GetItem, dynamodb:PutItem, dynamodb:UpdateItem, dynamodb:DeleteItem, dynamodb:Query, dynamodb:Scan
  • s3:GetObject, s3:PutObject, s3:DeleteObject, s3:GeneratePresignedUrl

Clone the Repository​

git clone https://github.com/yashmody/civicpulse.git
cd civicpulse

The repository contains two main directories:

civicpulse/
├── frontend/          # React 19 + Vite 7 application
├── backend/           # Node.js + Express API server
├── docs/              # This Docusaurus documentation site
└── README.md

Install Dependencies​

Install frontend and backend dependencies separately. They are independent Node.js projects.

Backend:

cd backend
npm install

Frontend:

cd frontend
npm install

Documentation site (optional):

cd docs
npm install

Environment Variables​

Backend — backend/.env​

Create a .env file in the backend/ directory. All variables marked Required must be set before the server will start.

# Server
PORT=3001
NODE_ENV=development

# Auth — generate strong random secrets (min 64 chars recommended)
JWT_SECRET=your-jwt-secret-at-least-64-characters-long-replace-in-production
JWT_REFRESH_SECRET=your-refresh-secret-different-from-jwt-secret-replace-in-production

# AWS
AWS_REGION=ap-south-1
DYNAMO_TABLE=civicpulse-issues
S3_BUCKET=civicpulse-media

# CORS — comma-separated list of allowed origins
CORS_ORIGIN=http://localhost:5174

# Rate limiting (optional — defaults shown)
RATE_LIMIT_WINDOW_MS=900000
RATE_LIMIT_MAX=100

Generate secure secrets with:

node -e "console.log(require('crypto').randomBytes(64).toString('hex'))"

Frontend — frontend/.env​

Create a .env file in the frontend/ directory:

VITE_API_URL=http://localhost:3001/api
VITE_WS_URL=http://localhost:3001

Note: Vite only exposes variables prefixed with VITE_ to the browser bundle. Never put secrets in frontend environment variables.

Start the Backend​

The backend runs as an Express cluster, spawning one worker per CPU core. For development, a single worker is used with nodemon for auto-reload.

cd backend
npm run dev

Expected output:

[PM2][CLUSTER] Master process started
[Worker 1] CivicPulse API running on port 3001
[Worker 1] DynamoDB connected — table: civicpulse-issues
[Worker 1] Socket.IO initialized

The API is now available at http://localhost:3001/api.

Verify the backend is running:

curl http://localhost:3001/api/health
# {"status":"ok","uptime":3.2,"timestamp":"2025-01-01T00:00:00.000Z"}

Start the Frontend​

The frontend uses Vite's dev server with HMR (Hot Module Replacement).

cd frontend
npm run dev

Expected output:

  VITE v7.x.x  ready in 312 ms

  ➜  Local:   http://localhost:5174/
  ➜  Network: use --host to expose

Access the Application​

Once both services are running:

ServiceURL
Frontend apphttp://localhost:5174
Backend APIhttp://localhost:3001/api
API root (machine-readable index)http://localhost:3001/api/
Health checkhttp://localhost:3001/api/health
WebSocket endpointws://localhost:3001

Open http://localhost:5174 in your browser. You will see the CivicPulse landing page. Use the Sign in with Google button to authenticate — this requires a valid Google OAuth client ID configured in the backend (see Environment Variables for GOOGLE_CLIENT_ID).

Next Steps​