​
Quick Start Guide

Get RippleCore running locally for development or evaluation in under 5 minutes.

​
Prerequisites

Node.js 18+

JavaScript runtime for building and running the application

pnpm 9+

Fast, disk-efficient package manager

Docker

For running PostgreSQL and Redis containers

Git

Version control for cloning the repository

​
Installation Steps

​
Step 1: Clone the Repository

git clone https://github.com/ripplecore/ripplecore.git
cd ripplecore

​
Step 2: Install Dependencies

pnpm install
This installs all workspace packages across the monorepo.

​
Step 3: Start Infrastructure

Start the PostgreSQL and Redis containers: 
pnpm db:up
This runs Docker Compose to start:
  • PostgreSQL 18 on port 5433
  • Redis 7 on port 6380

​
Step 4: Configure Environment

Copy the example environment file and configure your secrets: 
cp apps/app/.env.example apps/app/.env.local
Generate a Better Auth secret: 
npx @better-auth/cli secret
Add the generated secret to your .env.local: 
# Database
DATABASE_URL="postgresql://ripplecore:ripplecore_dev@localhost:5433/ripplecore"

# Authentication
BETTER_AUTH_SECRET="your-generated-secret-here"
BETTER_AUTH_URL="http://localhost:3000"

​
Step 5: Initialize Database

Run database migrations and seed with sample data: 
pnpm db:migrate
pnpm db:seed

​
Step 6: Start Development Server

pnpm dev
Success! The RippleCore dashboard is now available at http://localhost:3000

​
Test Account

After seeding, you can log in with:
EmailPasswordRole
admin@example.compassword123Admin
user@example.compassword123Member

​
Available Apps

The monorepo includes multiple applications:
AppPortDescription
app3000Main dashboard application
web3001Marketing website
api3002Serverless API for webhooks
email3003Email template preview
docs3004Documentation (you’re here!)
Run a specific app: 
pnpm --filter app dev      # Main app only
pnpm --filter web dev      # Marketing site only

​
First Actions

Once logged in, try these quick actions:
1

Log a Kindness Act

Navigate to Kindness and tap to log your first recognition. Add a photo or voice note for higher verification tier.
2

Track Volunteer Hours

Go to Volunteer → Log Hours to record community impact. Use QR code or GPS check-in for automatic verification.
3

Record a Donation

Open Donations and add a charitable contribution. Supports payroll, JustGiving, CAF, and manual entry.
4

View Your Impact

Check the Dashboard to see your Ripple Score and total verified impact metrics.

​
Common Commands

# Development
pnpm dev              # Start all apps
pnpm build            # Build for production
pnpm test             # Run unit tests
pnpm test:e2e         # Run E2E tests

# Database
pnpm db:up            # Start PostgreSQL + Redis
pnpm db:down          # Stop containers
pnpm db:studio        # Open Drizzle Studio
pnpm db:reset:seed    # Reset and reseed database

# Code Quality
pnpm check            # Run Biome linter
pnpm fix              # Auto-fix lint issues
pnpm typecheck        # TypeScript check

​
Next Steps

Explore Core Modules

Learn about Kindness, Volunteer, Donations, and Wellbeing modules

API Integration

Integrate with the RippleCore REST API

Portal Setup

Configure Charity, Council, or Consultant portals

Development Guide

Advanced development setup and architecture