---
title: "Basic Setup"
description: "Quick-start a Ring Platform instance with PostgreSQL, Auth.js v5, and minimal configuration — for founders and developers"
locale: "en"
---
# 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.

  Node.js 20+, PostgreSQL 16, and Git. Full prerequisites are documented in the [Installation guide](/docs/en/getting-started/installation.md).

### For founders

## 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](/docs/en/development/local-setup.md) for white-label customization, feature flags, and advanced configuration. For production deployment, refer to [Environment Configuration](/docs/en/deployment/environment.md).

### For developers

## 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:

```bash
cp env.local.template .env.local
```

At minimum, set these in `.env.local`:

```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
```

  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](/docs/en/deployment/environment.md). For local development `AUTH_TRUST_HOST=true` is recommended.

### Database Setup

Start PostgreSQL and create the database:

```bash
docker run -d --name ring-postgres-dev \
  -e POSTGRES_USER=ring_user \
  -e POSTGRES_PASSWORD=ring_password_2024 \
  -e POSTGRES_DB=ring_platform \
  -p 5432:5432 \
  postgres:16-alpine
```

Apply the schema and migrations:

```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
```

Alternatively, use the install script which handles database setup:

```bash
./install.sh --quick
```

See [Installation > PostgreSQL Setup](/docs/en/getting-started/installation.md#postgresql-setup) for more options.

### Start Development Server

```bash
npm run dev
```

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

### Verify

```bash
curl http://localhost:3000/api/health
```

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 |

  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:

```bash
psql "postgresql://ring_user:ring_password_2024@localhost:5432/ring_platform" -c "SELECT 1"
```

### Google OAuth not working

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

### Auth secret errors

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

```bash
npx auth secret
```

Then copy the output into `AUTH_SECRET`.

## Next Steps

- [Installation guide](/docs/en/getting-started/installation.md) — full setup with install script and advanced database config
- [Local Setup](/docs/en/development/local-setup.md) — white-label configuration, feature toggles, and development workflow
- [Environment Configuration](/docs/en/deployment/environment.md) — reference for all environment variables
- [Advanced Features](/docs/en/examples/advanced-features.md) — AI matcher, verification, PaymentConductor, and more