Local Development Setup

Guide to setting up Ring Platform for local development.

What You Need

Node.js 22, pnpm/npm, and Git installed on your machine
PostgreSQL 16 + PostGIS (via Homebrew, Docker, or native install)
A code editor (VS Code recommended)

Setup Overview

Clone the repository
Install dependencies
Configure environment variables from env.local.template
Set up PostgreSQL and run migrations
Start the development server

Prerequisites

Required Software

Node.js 22 — Download from nodejs.org
npm 10+ or pnpm 9+ — Package manager
Git — Version control
PostgreSQL 16 with PostGIS extension — See database setup section
VS Code — Recommended IDE

Optional Tools

Docker — For containerized PostgreSQL (alternative to Homebrew install)
Postman or Bruno — API testing

Installation

1. Clone the Repository

2. Install Dependencies

3. Environment Configuration

Copy the environment template:

The DB_BACKEND_MODE variable is required — the platform will not start without it. For local development with PostgreSQL, set it to k8s-postgres-fcm.

Configure your .env.local file with these essential variables:

Generate AUTH_SECRET with: npx @better-auth/cli secret

See Environment Configuration for the full list of supported variables and their descriptions.

4. Database Setup

Option A: Docker (Recommended for local dev)

Option B: Homebrew (macOS)

For multi-clone local development, use the bootstrap script at infrastructure/postgres/bootstrap-brew-dev.sh. See infrastructure/postgres/MIGRATION-KINGDOM-MATRIX.md.

Run Migrations

Migration files live in data/ directory. The migration runner reads DB_BACKEND_MODE to select the correct adapter. For local PostgreSQL (k8s-postgres-fcm), it applies SQL migrations from data/schema.sql and data/migrations/.

5. Start Development Server

The application will be available at:

Frontend: http://localhost:3000
API Routes: http://localhost:3000/api/*
Health Check: http://localhost:3000/api/health

Development Tools

Hot Reload

The Next.js development server supports hot reload for:

React components and Server Components
API routes
Tailwind CSS changes
Locale files (requires server restart for new keys)

Type Checking

Linting

Project Structure

Testing

Common Issues

Port 3000 Already in Use

Database Connection Refused

Verify PostgreSQL is running: pg_isready
Check .env.local values for DB_HOST, DB_PORT, DB_USER, DB_PASSWORD
Ensure database ring_platform exists
Confirm DB_BACKEND_MODE is set to k8s-postgres-fcm

Auth.js OAuth Errors

Verify AUTH_GOOGLE_ID and AUTH_GOOGLE_SECRET in .env.local
Check that http://localhost:3000 is in the Google OAuth console authorized redirect URIs
Ensure AUTH_SECRET is set and consistent
Callback URL format: http://localhost:3000/api/auth/callback/google

Firebase FCM Not Working (Optional)

Firebase is used only for push notifications (FCM) in k8s-postgres-fcm mode. The app will work without Firebase configured, but push notifications will not be delivered. Configure AUTH_FIREBASE_* and NEXT_PUBLIC_FIREBASE_* vars if needed.

Next Steps

Environment Configuration — Full env var reference
Deployment — Deploying to production
Installation Guide — Production installation
Code Structure — Codebase organization
Development Workflow — Git workflow and best practices
Testing — Writing and running tests

Need help? Check the troubleshooting guide or join our Discord Community.

Local Development Setup

Guide to setting up Ring Platform for local development.

What You Need

Node.js 22, pnpm/npm, and Git installed on your machine
PostgreSQL 16 + PostGIS (via Homebrew, Docker, or native install)
A code editor (VS Code recommended)

Setup Overview

Clone the repository
Install dependencies
Configure environment variables from env.local.template
Set up PostgreSQL and run migrations
Start the development server

Prerequisites

Required Software

Node.js 22 — Download from nodejs.org
npm 10+ or pnpm 9+ — Package manager
Git — Version control
PostgreSQL 16 with PostGIS extension — See database setup section
VS Code — Recommended IDE

Optional Tools

Docker — For containerized PostgreSQL (alternative to Homebrew install)
Postman or Bruno — API testing

Installation

1. Clone the Repository

2. Install Dependencies

3. Environment Configuration

Copy the environment template:

The DB_BACKEND_MODE variable is required — the platform will not start without it. For local development with PostgreSQL, set it to k8s-postgres-fcm.

Configure your .env.local file with these essential variables:

Generate AUTH_SECRET with: npx @better-auth/cli secret

See Environment Configuration for the full list of supported variables and their descriptions.

4. Database Setup

Option A: Docker (Recommended for local dev)

Option B: Homebrew (macOS)

For multi-clone local development, use the bootstrap script at infrastructure/postgres/bootstrap-brew-dev.sh. See infrastructure/postgres/MIGRATION-KINGDOM-MATRIX.md.

Run Migrations

5. Start Development Server

The application will be available at:

Frontend: http://localhost:3000
API Routes: http://localhost:3000/api/*
Health Check: http://localhost:3000/api/health

Development Tools

Hot Reload

The Next.js development server supports hot reload for:

React components and Server Components
API routes
Tailwind CSS changes
Locale files (requires server restart for new keys)

Type Checking

Linting

Project Structure

Testing

Common Issues

Port 3000 Already in Use

Database Connection Refused

Verify PostgreSQL is running: pg_isready
Check .env.local values for DB_HOST, DB_PORT, DB_USER, DB_PASSWORD
Ensure database ring_platform exists
Confirm DB_BACKEND_MODE is set to k8s-postgres-fcm

Auth.js OAuth Errors

Verify AUTH_GOOGLE_ID and AUTH_GOOGLE_SECRET in .env.local
Check that http://localhost:3000 is in the Google OAuth console authorized redirect URIs
Ensure AUTH_SECRET is set and consistent
Callback URL format: http://localhost:3000/api/auth/callback/google

Firebase FCM Not Working (Optional)

Next Steps

Environment Configuration — Full env var reference
Deployment — Deploying to production
Installation Guide — Production installation
Code Structure — Codebase organization
Development Workflow — Git workflow and best practices
Testing — Writing and running tests

Need help? Check the troubleshooting guide or join our Discord Community.

Local Development Setup

Guide to setting up Ring Platform for local development.

What You Need

Node.js 22, pnpm/npm, and Git installed on your machine
PostgreSQL 16 + PostGIS (via Homebrew, Docker, or native install)
A code editor (VS Code recommended)

Setup Overview

Clone the repository
Install dependencies
Configure environment variables from env.local.template
Set up PostgreSQL and run migrations
Start the development server

Prerequisites

Required Software

Node.js 22 — Download from nodejs.org
npm 10+ or pnpm 9+ — Package manager
Git — Version control
PostgreSQL 16 with PostGIS extension — See database setup section
VS Code — Recommended IDE

Optional Tools

Docker — For containerized PostgreSQL (alternative to Homebrew install)
Postman or Bruno — API testing

Installation

1. Clone the Repository

2. Install Dependencies

3. Environment Configuration

Copy the environment template:

The DB_BACKEND_MODE variable is required — the platform will not start without it. For local development with PostgreSQL, set it to k8s-postgres-fcm.

Configure your .env.local file with these essential variables:

Generate AUTH_SECRET with: npx @better-auth/cli secret

See Environment Configuration for the full list of supported variables and their descriptions.

4. Database Setup

Option A: Docker (Recommended for local dev)

Option B: Homebrew (macOS)

For multi-clone local development, use the bootstrap script at infrastructure/postgres/bootstrap-brew-dev.sh. See infrastructure/postgres/MIGRATION-KINGDOM-MATRIX.md.

Run Migrations

5. Start Development Server

The application will be available at:

Frontend: http://localhost:3000
API Routes: http://localhost:3000/api/*
Health Check: http://localhost:3000/api/health

Development Tools

Hot Reload

The Next.js development server supports hot reload for:

React components and Server Components
API routes
Tailwind CSS changes
Locale files (requires server restart for new keys)

Type Checking

Linting

Project Structure

Testing

Common Issues

Port 3000 Already in Use

Database Connection Refused

Verify PostgreSQL is running: pg_isready
Check .env.local values for DB_HOST, DB_PORT, DB_USER, DB_PASSWORD
Ensure database ring_platform exists
Confirm DB_BACKEND_MODE is set to k8s-postgres-fcm

Auth.js OAuth Errors

Verify AUTH_GOOGLE_ID and AUTH_GOOGLE_SECRET in .env.local
Check that http://localhost:3000 is in the Google OAuth console authorized redirect URIs
Ensure AUTH_SECRET is set and consistent
Callback URL format: http://localhost:3000/api/auth/callback/google

Firebase FCM Not Working (Optional)

Next Steps

Environment Configuration — Full env var reference
Deployment — Deploying to production
Installation Guide — Production installation
Code Structure — Codebase organization
Development Workflow — Git workflow and best practices
Testing — Writing and running tests

Need help? Check the troubleshooting guide or join our Discord Community.

text


ring-platform.org/
├── app/                  # Next.js 16 App Router
│   ├── (auth)/           # Auth pages (login, register)
│   ├── api/              # API routes
│   └── (public)/         # Public pages
├── features/             # Feature modules
│   ├── news/             # News management
│   ├── entities/         # Entity management
│   ├── opportunities/    # Opportunity system
│   └── wallet/           # Web3 wallet
├── lib/                  # Core libraries
│   ├── database/         # Database abstraction
│   │   ├── DatabaseService.ts
│   │   └── adapters/     # PostgreSQLAdapter, FirebaseAdapter
│   ├── firebase-admin.server.ts  # Firebase Admin (FCM only)
│   └── auth-adapter-singleton.ts # Auth.js adapter selection
├── @actions/             # Server actions
├── data/                 # SQL migrations
├── infrastructure/       # Postgres bootstrap scripts
├── public/               # Static assets, firebase-messaging-sw.js
├── locales/              # i18n translation files
├── env.local.template    # Single source of truth for env vars
└── ring-config.json      # Clone configuration

text


ring-platform.org/
├── app/                  # Next.js 16 App Router
│   ├── (auth)/           # Auth pages (login, register)
│   ├── api/              # API routes
│   └── (public)/         # Public pages
├── features/             # Feature modules
│   ├── news/             # News management
│   ├── entities/         # Entity management
│   ├── opportunities/    # Opportunity system
│   └── wallet/           # Web3 wallet
├── lib/                  # Core libraries
│   ├── database/         # Database abstraction
│   │   ├── DatabaseService.ts
│   │   └── adapters/     # PostgreSQLAdapter, FirebaseAdapter
│   ├── firebase-admin.server.ts  # Firebase Admin (FCM only)
│   └── auth-adapter-singleton.ts # Auth.js adapter selection
├── @actions/             # Server actions
├── data/                 # SQL migrations
├── infrastructure/       # Postgres bootstrap scripts
├── public/               # Static assets, firebase-messaging-sw.js
├── locales/              # i18n translation files
├── env.local.template    # Single source of truth for env vars
└── ring-config.json      # Clone configuration

text


ring-platform.org/
├── app/                  # Next.js 16 App Router
│   ├── (auth)/           # Auth pages (login, register)
│   ├── api/              # API routes
│   └── (public)/         # Public pages
├── features/             # Feature modules
│   ├── news/             # News management
│   ├── entities/         # Entity management
│   ├── opportunities/    # Opportunity system
│   └── wallet/           # Web3 wallet
├── lib/                  # Core libraries
│   ├── database/         # Database abstraction
│   │   ├── DatabaseService.ts
│   │   └── adapters/     # PostgreSQLAdapter, FirebaseAdapter
│   ├── firebase-admin.server.ts  # Firebase Admin (FCM only)
│   └── auth-adapter-singleton.ts # Auth.js adapter selection
├── @actions/             # Server actions
├── data/                 # SQL migrations
├── infrastructure/       # Postgres bootstrap scripts
├── public/               # Static assets, firebase-messaging-sw.js
├── locales/              # i18n translation files
├── env.local.template    # Single source of truth for env vars
└── ring-config.json      # Clone configuration

Documentation

Quick entry (CTOs · auditors · agents)

Documentation

Quick entry (CTOs · auditors · agents)

Documentation

Quick entry (CTOs · auditors · agents)

Завантаження документації...

Documentation

Quick entry (CTOs · auditors · agents)

Завантаження документації...

Documentation

Quick entry (CTOs · auditors · agents)

Завантаження документації...

Documentation

Quick entry (CTOs · auditors · agents)

Завантаження документації...

Завантаження документації...

Завантаження документації...

Local Development Setup

What You Need

Setup Overview

Local Development Setup

What You Need

Setup Overview

Local Development Setup

What You Need

Setup Overview