Skip to Content
Ranlanka CRM documentation — pre-release, subject to change.
Getting Started

Getting Started

This walks through running Ranlanka CRM locally from a clean clone: the Spring Boot API, then the React frontend.

Both repos (ranlanka-API, ranlanka-UI) are independently git-initialized under the project root — clone each separately.

Prerequisites

Install the toolchain

  • Java 23 (or newer) — the API’s pom.xml targets Java 23
  • Node.js 20+ and npm
  • A Postgres database — the project uses Supabase-hosted Postgres; a local Postgres instance also works for development

Get database credentials

Create a free Supabase  project (or point at any Postgres instance you control) and grab the connection string from Project Settings → Database → Connection string.

Backend (ranlanka-API)

Configure environment variables

cd ranlanka-API
cp .env.example .env

Fill in at minimum:

.env
SPRING_DATASOURCE_URL=jdbc:postgresql://<PROJECT-REF>.supabase.co:5432/postgres
SPRING_DATASOURCE_USERNAME=postgres
SPRING_DATASOURCE_PASSWORD=your-supabase-db-password
 
SPRING_PROFILES_ACTIVE=local
APP_JWT_SECRET=<generate with: openssl rand -base64 32>
APP_SECURITY_COOKIE_SECURE=false
APP_FRONTEND_URL=http://localhost:3000
APP_CORS_ALLOWED_ORIGINS=http://localhost:3000,http://127.0.0.1:3000

APP_JWT_SECRET must be a real base64-encoded key — the app refuses to start with the insecure repo-default value outside local/dev profiles. Generate your own with openssl rand -base64 32.

Mail (SPRING_MAIL_*) and the exchange-rate API key are only needed for features that send email or handle non-LKR currency — safe to leave as placeholders for local backend-only work.

Run the API

./mvnw spring-boot:run

Flyway runs pending migrations automatically on startup. The API listens on http://localhost:8080 by default, with routes under /api/v1.

Verify it’s up

curl http://localhost:8080/actuator/health

Should return {"status":"UP"}.

Frontend (ranlanka-UI)

Configure environment variables

cd ranlanka-UI
cp .env.example .env
.env
VITE_API_BASE_URL=http://localhost:8080/api/v1
VITE_APP_URL=http://localhost:3000

Install and run

npm install
npm run dev

The app runs at http://localhost:3000.

First login

There’s no public sign-up — staff accounts are created via the invite flow. For a fresh database, insert a seed owner role staff record directly (see ranlanka-API’s migration files under src/main/resources/db/migration for the staff/roles table shape), then log in and invite additional staff from the app itself.

Next steps

  • Architecture — how the backend and frontend are structured
  • Security — auth model, permissions, and the guardrails around dev-only bypass flags
Last updated on
Guide for StaffArchitecture