Basic Setup

This guide walks through a minimal Ring Platform local setup. It is the fastest way to see a running instance after cloning the repository.

Prerequisites

Node.js 20+, PostgreSQL 16, and Git. Full prerequisites are documented in the Installation guide.

What You Get

A running Ring Platform with:

PostgreSQL as the application database (k8s-postgres-fcm mode)
Auth.js v5 authentication with Google OAuth sign-in
Entity management — create and manage organizations
Opportunity marketplace — post and discover listings
Real-time notifications via WebSocket tunnel

The platform runs on http://localhost:3000. No cloud dependencies are required for basic local operation.

Next Steps After Setup

After verifying the local instance, see Local Setup for white-label customization, feature flags, and advanced configuration. For production deployment, refer to Environment Configuration.

Step-by-Step Setup

Clone and Install

bash


git clone https://github.com/connectplatform/ring.git
cd ring
npm install

Configure Environment

Copy the template and edit the required variables:

At minimum, set these in .env.local:

AUTH_SECRET generation

Auth.js v5 can generate a secret automatically on first run. Alternatively, use npx auth secret to generate one explicitly. The openssl rand -hex 32 approach is not needed.

The full variable reference is in Environment Configuration. For local development AUTH_TRUST_HOST=true is recommended.

Database Setup

Start PostgreSQL and create the database:

Apply the schema and migrations:

Alternatively, use the install script which handles database setup:

See Installation > PostgreSQL Setup for more options.

Start Development Server

The custom server.ts starts Next.js 16 with the WebSocket tunnel on port 3000.

Verify

Expected response: {"status":"ok","timestamp":"..."}

Visit http://localhost:3000/login to test Google OAuth sign-in.

Key Files

File	Purpose
`auth.ts`	Auth.js v5 configuration — providers, callbacks, JWT session strategy
`lib/database/DatabaseService.ts`	Unified database abstraction (PostgreSQL or Firestore)
`lib/firebase-admin.server.ts`	Firebase Admin SDK for FCM push (server-side only)
`public/firebase-messaging-sw.js`	Service worker with Firebase client SDK for push notifications
`lib/tunnel/`	Real-time WebSocket transport
`data/schema.sql`	PostgreSQL schema v4

No lib/firebase.ts

Ring Platform does not have a lib/firebase.ts client initialization file. Firebase client SDK is loaded exclusively inside the service worker (public/firebase-messaging-sw.js) via CDN importScripts(). There is no client-side firebaseConfig object. Server-side Firebase Admin uses lib/firebase-admin.server.ts with explicit service-account credentials.

Technology Stack

Component	Version / Provider
Framework	Next.js 16 App Router
UI	React 19
Auth	Auth.js v5 (`auth()` / `useSession()`)
Database	PostgreSQL 16 + PostGIS (or Firestore via `DB_BACKEND_MODE=firebase-full`)
Push	Firebase Cloud Messaging (server Admin SDK, client service worker)
Payments	WayForPay (HMAC server-side verification)
Locales	`next-intl`, supported locales: en, uk, ru

Troubleshooting

"FETCH_FAILED" or database connection errors

Verify PostgreSQL is running and the credentials in .env.local match:

Google OAuth not working

Check Google Cloud Console — add http://localhost:3000 to Authorized JavaScript origins
Add http://localhost:3000/api/auth/callback/google to Authorized redirect URIs
Verify AUTH_GOOGLE_ID and AUTH_GOOGLE_SECRET in .env.local

Auth secret errors

Ensure AUTH_SECRET is set in .env.local. Generate with:

Then copy the output into AUTH_SECRET.

Next Steps

Installation guide — full setup with install script and advanced database config
Local Setup — white-label configuration, feature toggles, and development workflow
Environment Configuration — reference for all environment variables
Advanced Features — AI matcher, verification, PaymentConductor, and more

Basic Setup

This guide walks through a minimal Ring Platform local setup. It is the fastest way to see a running instance after cloning the repository.

Prerequisites

Node.js 20+, PostgreSQL 16, and Git. Full prerequisites are documented in the Installation guide.

What You Get

A running Ring Platform with:

PostgreSQL as the application database (k8s-postgres-fcm mode)
Auth.js v5 authentication with Google OAuth sign-in
Entity management — create and manage organizations
Opportunity marketplace — post and discover listings
Real-time notifications via WebSocket tunnel

The platform runs on http://localhost:3000. No cloud dependencies are required for basic local operation.

Next Steps After Setup

After verifying the local instance, see Local Setup for white-label customization, feature flags, and advanced configuration. For production deployment, refer to Environment Configuration.

Step-by-Step Setup

Clone and Install

bash


git clone https://github.com/connectplatform/ring.git
cd ring
npm install

Configure Environment

Copy the template and edit the required variables:

At minimum, set these in .env.local:

AUTH_SECRET generation

Auth.js v5 can generate a secret automatically on first run. Alternatively, use npx auth secret to generate one explicitly. The openssl rand -hex 32 approach is not needed.

The full variable reference is in Environment Configuration. For local development AUTH_TRUST_HOST=true is recommended.

Database Setup

Start PostgreSQL and create the database:

Apply the schema and migrations:

Alternatively, use the install script which handles database setup:

See Installation > PostgreSQL Setup for more options.

Start Development Server

The custom server.ts starts Next.js 16 with the WebSocket tunnel on port 3000.

Verify

Expected response: {"status":"ok","timestamp":"..."}

Visit http://localhost:3000/login to test Google OAuth sign-in.

Key Files

File	Purpose
`auth.ts`	Auth.js v5 configuration — providers, callbacks, JWT session strategy
`lib/database/DatabaseService.ts`	Unified database abstraction (PostgreSQL or Firestore)
`lib/firebase-admin.server.ts`	Firebase Admin SDK for FCM push (server-side only)
`public/firebase-messaging-sw.js`	Service worker with Firebase client SDK for push notifications
`lib/tunnel/`	Real-time WebSocket transport
`data/schema.sql`	PostgreSQL schema v4

No lib/firebase.ts

Technology Stack

Component	Version / Provider
Framework	Next.js 16 App Router
UI	React 19
Auth	Auth.js v5 (`auth()` / `useSession()`)
Database	PostgreSQL 16 + PostGIS (or Firestore via `DB_BACKEND_MODE=firebase-full`)
Push	Firebase Cloud Messaging (server Admin SDK, client service worker)
Payments	WayForPay (HMAC server-side verification)
Locales	`next-intl`, supported locales: en, uk, ru

Troubleshooting

"FETCH_FAILED" or database connection errors

Verify PostgreSQL is running and the credentials in .env.local match:

Google OAuth not working

Check Google Cloud Console — add http://localhost:3000 to Authorized JavaScript origins
Add http://localhost:3000/api/auth/callback/google to Authorized redirect URIs
Verify AUTH_GOOGLE_ID and AUTH_GOOGLE_SECRET in .env.local

Auth secret errors

Ensure AUTH_SECRET is set in .env.local. Generate with:

Then copy the output into AUTH_SECRET.

Next Steps

Installation guide — full setup with install script and advanced database config
Local Setup — white-label configuration, feature toggles, and development workflow
Environment Configuration — reference for all environment variables
Advanced Features — AI matcher, verification, PaymentConductor, and more

Basic Setup

This guide walks through a minimal Ring Platform local setup. It is the fastest way to see a running instance after cloning the repository.

Prerequisites

Node.js 20+, PostgreSQL 16, and Git. Full prerequisites are documented in the Installation guide.

What You Get

A running Ring Platform with:

PostgreSQL as the application database (k8s-postgres-fcm mode)
Auth.js v5 authentication with Google OAuth sign-in
Entity management — create and manage organizations
Opportunity marketplace — post and discover listings
Real-time notifications via WebSocket tunnel

The platform runs on http://localhost:3000. No cloud dependencies are required for basic local operation.

Next Steps After Setup

After verifying the local instance, see Local Setup for white-label customization, feature flags, and advanced configuration. For production deployment, refer to Environment Configuration.

Step-by-Step Setup

Clone and Install

bash


git clone https://github.com/connectplatform/ring.git
cd ring
npm install

Configure Environment

Copy the template and edit the required variables:

At minimum, set these in .env.local:

AUTH_SECRET generation

Auth.js v5 can generate a secret automatically on first run. Alternatively, use npx auth secret to generate one explicitly. The openssl rand -hex 32 approach is not needed.

The full variable reference is in Environment Configuration. For local development AUTH_TRUST_HOST=true is recommended.

Database Setup

Start PostgreSQL and create the database:

Apply the schema and migrations:

Alternatively, use the install script which handles database setup:

See Installation > PostgreSQL Setup for more options.

Start Development Server

The custom server.ts starts Next.js 16 with the WebSocket tunnel on port 3000.

Verify

Expected response: {"status":"ok","timestamp":"..."}

Visit http://localhost:3000/login to test Google OAuth sign-in.

Key Files

File	Purpose
`auth.ts`	Auth.js v5 configuration — providers, callbacks, JWT session strategy
`lib/database/DatabaseService.ts`	Unified database abstraction (PostgreSQL or Firestore)
`lib/firebase-admin.server.ts`	Firebase Admin SDK for FCM push (server-side only)
`public/firebase-messaging-sw.js`	Service worker with Firebase client SDK for push notifications
`lib/tunnel/`	Real-time WebSocket transport
`data/schema.sql`	PostgreSQL schema v4

No lib/firebase.ts

Technology Stack

Component	Version / Provider
Framework	Next.js 16 App Router
UI	React 19
Auth	Auth.js v5 (`auth()` / `useSession()`)
Database	PostgreSQL 16 + PostGIS (or Firestore via `DB_BACKEND_MODE=firebase-full`)
Push	Firebase Cloud Messaging (server Admin SDK, client service worker)
Payments	WayForPay (HMAC server-side verification)
Locales	`next-intl`, supported locales: en, uk, ru

Troubleshooting

"FETCH_FAILED" or database connection errors

Verify PostgreSQL is running and the credentials in .env.local match:

Google OAuth not working

Check Google Cloud Console — add http://localhost:3000 to Authorized JavaScript origins
Add http://localhost:3000/api/auth/callback/google to Authorized redirect URIs
Verify AUTH_GOOGLE_ID and AUTH_GOOGLE_SECRET in .env.local

Auth secret errors

Ensure AUTH_SECRET is set in .env.local. Generate with:

Then copy the output into AUTH_SECRET.

Next Steps

Installation guide — full setup with install script and advanced database config
Local Setup — white-label configuration, feature toggles, and development workflow
Environment Configuration — reference for all environment variables
Advanced Features — AI matcher, verification, PaymentConductor, and more

bash


# Database backend (required)
DB_BACKEND_MODE=k8s-postgres-fcm

# Auth.js secret (required)
AUTH_SECRET=your-secret

# Database connection (required for k8s-postgres-fcm)
DB_HOST=localhost
DB_PORT=5432
DB_NAME=ring_platform
DB_USER=ring_user
DB_PASSWORD=ring_password_2024

# Google OAuth (required for sign-in)
AUTH_GOOGLE_ID=your-client-id
AUTH_GOOGLE_SECRET=your-client-secret

bash


export DATABASE_URL="postgresql://ring_user:ring_password_2024@localhost:5432/ring_platform"
psql "$DATABASE_URL" -f data/schema.sql
psql "$DATABASE_URL" -f data/migrations/002_news_content_schema.sql
psql "$DATABASE_URL" -f data/migrations/003_news_kingdom_upgrade.sql
psql "$DATABASE_URL" -f data/migrations/004_payment_transactions.sql

bash


# Database backend (required)
DB_BACKEND_MODE=k8s-postgres-fcm

# Auth.js secret (required)
AUTH_SECRET=your-secret

# Database connection (required for k8s-postgres-fcm)
DB_HOST=localhost
DB_PORT=5432
DB_NAME=ring_platform
DB_USER=ring_user
DB_PASSWORD=ring_password_2024

# Google OAuth (required for sign-in)
AUTH_GOOGLE_ID=your-client-id
AUTH_GOOGLE_SECRET=your-client-secret

bash


export DATABASE_URL="postgresql://ring_user:ring_password_2024@localhost:5432/ring_platform"
psql "$DATABASE_URL" -f data/schema.sql
psql "$DATABASE_URL" -f data/migrations/002_news_content_schema.sql
psql "$DATABASE_URL" -f data/migrations/003_news_kingdom_upgrade.sql
psql "$DATABASE_URL" -f data/migrations/004_payment_transactions.sql

bash


# Database backend (required)
DB_BACKEND_MODE=k8s-postgres-fcm

# Auth.js secret (required)
AUTH_SECRET=your-secret

# Database connection (required for k8s-postgres-fcm)
DB_HOST=localhost
DB_PORT=5432
DB_NAME=ring_platform
DB_USER=ring_user
DB_PASSWORD=ring_password_2024

# Google OAuth (required for sign-in)
AUTH_GOOGLE_ID=your-client-id
AUTH_GOOGLE_SECRET=your-client-secret

bash


export DATABASE_URL="postgresql://ring_user:ring_password_2024@localhost:5432/ring_platform"
psql "$DATABASE_URL" -f data/schema.sql
psql "$DATABASE_URL" -f data/migrations/002_news_content_schema.sql
psql "$DATABASE_URL" -f data/migrations/003_news_kingdom_upgrade.sql
psql "$DATABASE_URL" -f data/migrations/004_payment_transactions.sql

Documentation

Quick entry (CTOs · auditors · agents)

Documentation

Quick entry (CTOs · auditors · agents)

Documentation

Quick entry (CTOs · auditors · agents)

Loading documentation...

Documentation

Quick entry (CTOs · auditors · agents)

Loading documentation...

Documentation

Quick entry (CTOs · auditors · agents)

Loading documentation...

Documentation

Quick entry (CTOs · auditors · agents)

Loading documentation...

Loading documentation...

Loading documentation...

Basic Setup

What You Get

Next Steps After Setup

Basic Setup

What You Get

Next Steps After Setup

Basic Setup

What You Get

Next Steps After Setup