---
title: "Installation"
description: "Install Ring Platform locally — clone, install.sh or manual env, PostgreSQL-primary backend, Auth.js v5, schema, and the unified custom server"
locale: "en"
---
# Installation

> **Info**
> Use **Founder** / **Developer** tabs in the docs sidebar to filter this page. Complete [Prerequisites](/docs/getting-started/prerequisites.md) first. This guide matches the open-source repo ([connectplatform/ring](https://github.com/connectplatform/ring)) and the **PostgreSQL-primary** default (`DB_BACKEND_MODE=k8s-postgres-fcm`).

Install Ring on your machine for local development. **Final-Split:** the Next.js app lives under `web/` — the repo-root `install.sh` delegates into `web/`, or you can run `./install.sh` from `ring/web` directly.

| Path | Best when | Outcome |
|------|-----------|---------|
| **Recommended — `install.sh`** | First clone, white-label scaffold | Copies `env.local.template` → `.env.local`, seeds `ring-config.json` if missing, generates `AUTH_SECRET`, runs `npm install` |
| **Manual** | You already manage env/config | Same files by hand; you own every copy and secret |

  Full Postgres-primary install (first time): about **45–90 minutes**. `./install.sh --quick` plus an existing PostgreSQL instance is usually faster — you still apply schema and one OAuth provider before a useful sign-in.

## What you are installing

| Component | Verified entry |
|-----------|----------------|
| **Framework** | Next.js 16 App Router + React 19 |
| **Auth** | Auth.js v5 (`auth.ts`, `AUTH_SECRET`, OAuth providers) |
| **Default data plane** | PostgreSQL via `DB_BACKEND_MODE=k8s-postgres-fcm` (mandatory env — no silent default) |
| **Dev server** | Custom `server.ts` — Next.js + native WebSocket tunnel (`/api/tunnel/ws`) when self-hosted |
| **White-label config** | `ring-config.json` (Layer1 may already ship community defaults; installer seeds from template only if missing) |
| **Installer** | `install.sh` **v2.2.0** (`SCRIPT_VERSION`) — includes `setup-db` |

```mermaid
flowchart LR
  A[Clone ring] --> B[install.sh or manual env]
  B --> C[PostgreSQL + schema]
  C --> D[Auth + ring-config]
  D --> E[npm run dev]
  E --> F[localhost:3000]
```

### For founders

## Why this matters for your clone

You are standing up a **dev clone** so stakeholders can click through branding, auth, and core marketplace flows before production hosting.

  
- **[Prerequisites](/docs/getting-started/prerequisites.md)** — Node 20+, Git, Postgres, ports — confirm before cloning

  
- **[Database migrations](/docs/getting-started/migrations.md)** — Apply `data/schema.sql` and kingdom migration order

  
- **[Database backend selection](/docs/customization/database-selection.md)** — `k8s-postgres-fcm` vs `supabase-fcm` vs `firebase-full`

  
- **[First success validation](/docs/getting-started/first-success.md)** — Smoke-test checklist after `npm run dev`

### Typical scenarios

| Scenario | Install choice | Stop when… |
|----------|----------------|------------|
| Explore UI / branding | `./install.sh --quick` + Postgres (or short `firebase-full` prototype) | Homepage loads without adapter errors |
| Production-parity local | Postgres-primary + migrations | Auth + one CRUD path pass [First success](/docs/getting-started/first-success.md) |
| Ringdom-managed settler | Skip most of this | Cluster is already provisioned — customize via ring-config / ops, not local Docker |

> **Warning**
> Payments, FCM push, and Web3 wallets are **not** required for first boot. Add them before checkout or production push — see [Environment](/docs/deployment/environment.md).

### For developers

## Recommended path — `install.sh`

`install.sh` v2.2.0 scaffolds env, optional `ring-config.json`, secrets, and dependencies. Prefer this for a clean first clone.

### Prerequisites

- Node.js **20+** (installer fails earlier majors)
- Git, and later PostgreSQL 14+ (16 Docker / 18 Homebrew recommended)
- From OSS checkout: repo root **or** `web/` (Final-Split)

### Steps

### Clone and run the installer

{`git clone https://github.com/connectplatform/ring.git
cd ring
./install.sh --quick
# equivalent Final-Split entry from app root:
# cd ring/web && ./install.sh --quick`}

Useful flags and modes:

| Flag / mode | Effect |
|-------------|--------|
| `--quick` | Non-interactive defaults |
| `--clone-name NAME` | White-label slug in `ring-config.json` |
| `dev` / `prod` | Explicit setup mode |
| `setup-db` | Create DB + apply `data/schema.sql` (flattened SSOT) |
| `--help` | Full option list |

### Finish required `.env.local` values

The template is copied automatically; installer generates `AUTH_SECRET` when `openssl` is available. Before first useful boot, set **database** vars and at least one OAuth provider (see [Configure environment](#configure-environment)).

### Apply PostgreSQL schema

Use Docker / existing server / Ringdom monorepo tabs below, or:

{`./install.sh setup-db --clone-name platform --db-name ring_platform`}

Full incremental order: [Database migrations](/docs/getting-started/migrations.md).

## Manual path

Use when you already control env files or package manager.

### Clone and install dependencies

{`git clone https://github.com/connectplatform/ring.git
cd ring/web
npm install`}

  
    
{`npm install`}

  
  
    
{`pnpm install`}

  
  
    
{`yarn install`}

### Create environment and clone config

{`cp env.local.template .env.local
# Only if ring-config.json is missing:
cp ring-config.template.json ring-config.json
# AUTH_SECRET — match installer behavior:
# openssl rand -base64 32`}

Edit `ring-config.json` — `clone.displayName`, `domains.development`, and `features` for your white-label instance. Layer1 often already commits community `ring-config.json`; do not overwrite casually.

## PostgreSQL setup

Production-style local dev uses database **`ring_platform`** with user **`ring_user`**. App schema SSOT: `data/schema.sql` (v4 family — see `schema_versions` rows in the dump).

`DB_BACKEND_MODE` is **mandatory** (`lib/database/backend-mode-config.ts`). The platform expects PostgreSQL when set to `k8s-postgres-fcm` (template default). See [Database migrations](/docs/getting-started/migrations.md) for apply order.

Standalone clone — no Ringdom monorepo required:

{`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 base schema, then kingdom increments (abbreviated — full matrix on the migrations page):

{`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
psql "$DATABASE_URL" -f data/migrations/009_email_crm_jsonb.sql
psql "$DATABASE_URL" -f data/migrations/010_email_crm_tasks_jsonb.sql`}

`001_email_crm_schema.sql` is **obsolete**. Prefer **009 + 010** JSONB. Idempotent increments already merged into `schema.sql` are covered in [Migrations](/docs/getting-started/migrations.md).

Point `.env.local` at PostgreSQL **14+** (18 recommended), create `ring_platform`, then run the same `psql` commands using your `DATABASE_URL`.

From the Ringdom kingdom checkout (multiple Ring clones):

{`docker compose -f docker-compose.dev.yml up -d postgres
# or Homebrew:
brew install postgresql@18 postgis
brew services start postgresql@18
./infrastructure/postgres/bootstrap-brew-dev.sh ring-platform.org`}

Container **`ring-postgres-dev`** + volume **`ringdom_postgres_data`** bootstraps via `infrastructure/postgres/init/`. See `infrastructure/postgres/init/README.md`.

## Configure environment

Set these in `.env.local` (from `env.local.template`). Values shown are local-dev oriented — the template’s `NEXT_PUBLIC_BASE_URL` may default to the public portal; override for localhost.

### Backend mode and database

{`DB_BACKEND_MODE=k8s-postgres-fcm
DB_HOST=localhost
DB_PORT=5432
DB_NAME=ring_platform
DB_USER=ring_user
DB_PASSWORD=ring_password_2024
DB_SSL=false`}

Application data on PostgreSQL; Firebase Admin used **only for FCM push** when configured. Matches ring-platform.org production posture.

{`DB_BACKEND_MODE=firebase-full`}

Fastest edge-style prototype — Firestore holds app data. Not recommended for PaymentConductor, News Kingdom, or ERP depth. Details: [Database selection](/docs/customization/database-selection.md).

{`DB_BACKEND_MODE=supabase-fcm
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_KEY=your-service-key`}

Managed PostgreSQL — same SQL schema family as self-hosted clones.

### Auth.js and URLs

{`AUTH_SECRET=   # openssl rand -base64 32  (installer sets this)
AUTH_GOOGLE_ID=your_google_client_id
AUTH_GOOGLE_SECRET=your_google_client_secret
NEXT_PUBLIC_BASE_URL=http://localhost:3000
NODE_ENV=development`}

In [Google Cloud Console](https://console.cloud.google.com/), add authorized redirect URI:
`http://localhost:3000/api/auth/callback/google`

### Tunnel, FCM, locales

{`RING_DEPLOY_TARGET=self-hosted
NEXT_PUBLIC_RING_DEPLOY_TARGET=self-hosted
NEXT_PUBLIC_SUPPORTED_LOCALES=en,uk,ru
NEXT_PUBLIC_DEFAULT_LOCALE=en`}

`npm run dev` runs `node --import tsx server.ts`. On Vercel, set `RING_DEPLOY_TARGET=vercel` for SSE-only (no native WSS).

FCM keys (`AUTH_FIREBASE_*`, `NEXT_PUBLIC_FIREBASE_*`) are in `env.local.template` — **optional** for Postgres-primary homepage/auth. Quote `AUTH_FIREBASE_PRIVATE_KEY` with literal `\\n`; never commit `.env.local`.

## Run the development server

### Start the app

{`npm run dev`}

Expect log lines similar to:

```text
> Ready on http://localhost:3000 [self-hosted]
[server] Native WSS attached at /api/tunnel/ws (RING_DEPLOY_TARGET=self-hosted)
```

First compile can take tens of seconds.

### Open and smoke-check

Visit [http://localhost:3000](http://localhost:3000) — home renders via `HomeWrapper` (`components/wrappers/home-wrapper.tsx`) and locale files under `locales/{en,uk,ru}/`.

Optional:

{`npm run type-check
curl -sS http://localhost:3000/api/health | jq .`}

Health shape: `app/api/health/route.ts` — `status` is `healthy` | `degraded` | `unhealthy`. Missing `AUTH_SECRET` → `degraded` and HTTP **503**.

If the homepage loads without database adapter errors, continue to [First success validation](/docs/getting-started/first-success.md).

### Module map (verified paths)

| Concern | Path |
|---------|------|
| Installer | `install.sh` (root launcher → `web/install.sh`) |
| Env template | `env.local.template` |
| Backend mode | `lib/database/backend-mode-config.ts` |
| Schema SSOT | `data/schema.sql` |
| Dev entry | `package.json` → `server.ts` |
| Tunnel WSS | `server.ts` → `/api/tunnel/ws` |
| Health | `app/api/health/route.ts` |

## Frequently asked questions

### Impact

#### Will my clone work without Firebase?

Yes for **browse + Auth.js + Postgres CRUD** when `DB_BACKEND_MODE=k8s-postgres-fcm`. Firebase Admin/client keys are needed for **FCM push**, not for the first homepage load.

#### Do I need payments credentials on day one?

No. WayForPay / Stripe belong later — after [First success](/docs/getting-started/first-success.md), before checkout demos.

### Migration

#### Schema only or full kingdom migrations?

Fresh installs: apply **`data/schema.sql`**, then news/payment/email increments as documented on [Migrations](/docs/getting-started/migrations.md). Do **not** apply obsolete `001_email_crm_schema.sql`.

#### Ringdom monorepo vs standalone Docker?

Same app DB name (`ring_platform`) and `DB_*` contract. Monorepo compose uses volume `ringdom_postgres_data` and init scripts under `infrastructure/postgres/init/`.

### Ops

#### Port 3000 already in use?

`lsof -ti:3000 | xargs kill` or `PORT=3001 npm run dev`.

#### Google sign-in fails?

Check `AUTH_GOOGLE_*`, redirect URI `http://localhost:3000/api/auth/callback/google`, and non-empty `AUTH_SECRET`.

#### Tunnel errors in the console?

Confirm `RING_DEPLOY_TARGET=self-hosted` (and public twin) for local WSS. On Vercel use `vercel` / SSE-only.

More: [Troubleshooting](/docs/getting-started/troubleshooting.md).

## Related documentation

  
- [getting-started/prerequisites](/docs/getting-started/prerequisites.md) — Prerequisite: confirm Node, Postgres, and ports before you clone.

  
- [getting-started/migrations](/docs/getting-started/migrations.md) — Next-step: apply data/schema.sql and kingdom migration order after env scaffold.

  
- [getting-started/first-success](/docs/getting-started/first-success.md) — Next-step: smoke-test health, auth, and CRUD once npm run dev is up.

  
- [customization/database-selection](/docs/customization/database-selection.md) — Deep-dive: choose k8s-postgres-fcm, supabase-fcm, or firebase-full.

  
- [development/local-setup](/docs/development/local-setup.md) — Same-workflow: project structure and day-to-day local tools after install.