---
title: "Prerequisites"
description: "Accounts, Node, PostgreSQL, and env gates before installing a Ring Platform clone — verified against install.sh and env.local.template"
locale: "en"
---
# Prerequisites

> **Info**
> **Before [Installation](/docs/getting-started/installation.md):** you need a machine that can run **Node.js 20+**, a **PostgreSQL** instance for production-parity work, and (for tester sign-in) at least one Auth.js path. Versions below match `install.sh`, `INSTALL.md`, and `env.local.template` — not legacy Node 18 guidance. Use **Founder** / **Developer** in the docs sidebar to filter this page.

Ring Platform is a **Next.js 16 + React 19** app with a **mandatory** `DB_BACKEND_MODE`. Local and production-parity clones use **PostgreSQL-primary** (`k8s-postgres-fcm`). Firestore-only (`firebase-full`) is a narrower prototype path.

## Deploy target comparison

| Path | Who | What you must bring | Skips |
|------|-----|---------------------|-------|
| **OSS self-host** (GitHub + `install.sh`) | Indie / hired integrator | Node 20+, Git, Postgres (or Docker), `.env.local`, OAuth or Ring Mailer | Managed k8s / settler handoff |
| **Ringdom-managed** (turn-key hosting) | Founder / settler | Domain + settler brief; cluster secrets after handoff | Most of this checklist locally |
| **`firebase-full` prototype** | Quick UI spike | Firebase project + Node 20+ | ERP / PaymentConductor / News Kingdom depth on Postgres |

> **Tip**
> Default for ring-platform.org and clone parity: **`DB_BACKEND_MODE=k8s-postgres-fcm`**. See [Backend modes](/docs/architecture/backend-modes-and-databases.md) and [Database selection](/docs/customization/database-selection.md).

## At a glance

| Requirement | Verified baseline | Source / notes |
|-------------|-------------------|----------------|
| **Node.js** | **v20+** (v22+ recommended) | `install.sh` fails below 20; `INSTALL.md` recommends 22+ |
| **npm** | **10+** | `INSTALL.md`; installer runs `npm install` |
| **Git** | Recent | Clone [connectplatform/ring](https://github.com/connectplatform/ring) |
| **PostgreSQL** | **14+** (Docker image **16**; Homebrew **18** common in docs) | DB `ring_platform`, user `ring_user` — `env.local.template` |
| **PostGIS** | Needed for fresh `data/schema.sql` | Schema header enables `CREATE EXTENSION postgis` (v4.1.0+) |
| **Ports** | `3000` (app), `5432` (Postgres) | Custom server: `node --import tsx server.ts` via `npm run dev` |
| **Redis** | Optional | `REDIS_URL` — rate-limit / set-nx fall back in-process when unset |
| **Disk / RAM** | Comfortable laptop class | Soft operator guidance only — not a measured SLA |

### For founders

## What founders need before ringizing

You are preparing a **white-label clone** — branding in `ring-config.json`, secrets in `.env.local`, and (for production features) Postgres with `data/schema.sql` applied.

### MVP vs production-ready

  
- **[Explore UI locally](/docs/getting-started/installation.md)** — Node 20+, `install.sh --quick`, Postgres **or** short-lived `firebase-full` — see [Database selection](/docs/customization/database-selection.md).

  
- **[Production-parity clone](/docs/getting-started/migrations.md)** — **Postgres-primary** + `data/schema.sql` (v4.1+) + kingdom migrations — store, PaymentConductor, News Kingdom depth.

  
- **[Sign-in for testers](/docs/features/authentication.md)** — At least one Auth.js path: Google OAuth, Apple, or Ring Mailer (`SMTP_*` or `EMAIL_MODE=ethereal`).

  
- **[Payments later](/docs/features/payment-conductor.md)** — WayForPay / Stripe credentials — **not** required for first `npm run dev`; add before checkout.

### Accounts checklist (founder)

| Account / artifact | When required |
|--------------------|---------------|
| GitHub clone of `connectplatform/ring` | Always for OSS self-host |
| PostgreSQL (local Docker, Homebrew, or hosted) | Postgres modes (`k8s-postgres-fcm`, `supabase-fcm`) |
| Google Cloud OAuth client **or** Apple Sign In **or** SMTP / Ethereal | Before real tester login |
| Firebase project (FCM keys) | Optional until push notifications |
| WayForPay / Stripe | Only before PaymentConductor checkout |
| Ringdom settler handoff | If you skip self-host and use managed hosting |

### Honest time budget (approximate)

| Path | Typical first-pass | Outcome |
|------|--------------------|---------|
| `./install.sh --quick` + existing Postgres | Tens of minutes | Env scaffold; you still apply schema + OAuth |
| Full Postgres-primary bootstrap | About an hour-class session | Matches ring-platform.org-style local stack |
| `firebase-full` prototype | Shorter spike | Skips ERP / conductor depth |

Times vary by machine and credential setup — treat as planning ranges, not SLAs.

> **Warning**
> **Ringdom-managed hosting** skips most of this checklist — settlers receive a configured cluster. Self-hosters on GitHub follow this page ([OSS vs enterprise](/docs/development/oss-vs-enterprise.md)).

### For developers

## Toolchain

### Node.js and package manager

{`node --version   # v20.0.0+ (v22+ recommended in INSTALL.md)
npm --version    # 10+`}

`install.sh` fails early if Node is below v20. Use nvm, fnm, or official installers — see `INSTALL.md`. The public tree’s installer path is **npm**; other package managers are not the documented install SSOT.

### PostgreSQL + PostGIS

Default connection (from `env.local.template`):

{`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
# or: DATABASE_URL=postgresql://ring_user:ring_password_2024@localhost:5432/ring_platform`}

Quick Docker database (matches `docker-compose.template.yml` image tag):

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

Fresh `data/schema.sql` (header **4.1.0**) runs `CREATE EXTENSION` for `uuid-ossp`, `pgcrypto`, and **`postgis`**. Prefer a PostGIS-capable image or Homebrew `postgresql@18` + `postgis` when applying schema — see [Database migrations](/docs/getting-started/migrations.md).

### Backend mode (required)

Set **`DB_BACKEND_MODE`** before first boot (`lib/database/backend-mode-config.ts` — no silent default at runtime):

| Value | When |
|-------|------|
| `k8s-postgres-fcm` | **Default path** — Postgres app data + optional FCM push |
| `supabase-fcm` | Postgres on Supabase + optional FCM |
| `firebase-full` | Firestore prototype only |

**`DATABASE_MODE` is removed** — do not set it. Deep dive: [Backend modes](/docs/architecture/backend-modes-and-databases.md).

### Minimum environment variables

{`cp env.local.template .env.local
# install.sh generates AUTH_SECRET and WALLET_ENCRYPTION_KEY

AUTH_SECRET=...                    # required — npx @better-auth/cli secret
DB_BACKEND_MODE=k8s-postgres-fcm
DB_* or DATABASE_URL               # required for postgres modes

# At least one sign-in path:
AUTH_GOOGLE_ID / AUTH_GOOGLE_SECRET
# and/or AUTH_APPLE_*
# and/or Ring Mailer: EMAIL_MODE=ethereal or SMTP_HOST + SMTP_USER + SMTP_PASSWORD
# (email_login_tokens table — migration 038 / included in flattened schema.sql)`}

Providers registered in `auth.ts`: **Ring Mailer** Credentials (`email-otp`, `email-magic`, `credentials`), **Google** OAuth, **Google One Tap**, **Apple**, wallet/crypto credentials. GitHub/Discord OAuth are **not** in the default provider list. **Resend / `AUTH_RESEND_KEY` are not part of the mailer SSOT** (use `SMTP_*` / Ethereal).

Optional for later features:

- `BLOB_READ_WRITE_TOKEN` — Vercel Blob uploads  
- `WAYFORPAY_*` / `STRIPE_*` — PaymentConductor  
- `NEXT_PUBLIC_FIREBASE_*` + Admin service account — FCM push (not Firestore DB on postgres-primary)  
- `OPENAI_API_KEY` / `ANTHROPIC_API_KEY` — AI matcher / Email CRM  
- `REDIS_URL` — optional; in-process fallback when unset  

Never commit `.env.local`. See [Environment configuration](/docs/deployment/environment.md).

### Validation checklist

### System

{`node --version && npm --version
curl -fsS -o /dev/null https://registry.npmjs.org/ || echo "npm registry unreachable"`}

### Database

{`psql "$DATABASE_URL" -c "SELECT version();"
# or:
docker exec ring-postgres-dev psql -U ring_user -d ring_platform -c "SELECT 1;"`}

### Health (after install)

{`curl -sS http://localhost:3000/api/health | jq .status`}

Expect `"healthy"` when `AUTH_SECRET` is set (`app/api/health/route.ts` treats missing `AUTH_SECRET` as critical). See [Monitoring](/docs/deployment/monitoring.md).

### Optional: Docker Compose stack

`install.sh` can materialize `docker-compose.yml` from `docker-compose.template.yml` (app + **postgres:16-alpine** + **redis:7-alpine**, plus optional monitoring profile). For day-one `npm run dev`, a single Postgres container (or Homebrew) is enough; Redis stays optional.

## Recommended path

Use the Getting Started hub flow: meet this checklist → run `install.sh` → apply schema → smoke-test.

1. Confirm Node 20+ and a Postgres plan (Docker 16 or Homebrew 18 + PostGIS).
2. Continue to [Installation](/docs/getting-started/installation.md) (`./install.sh --quick` or manual env).
3. Apply [Database migrations](/docs/getting-started/migrations.md), then [First success](/docs/getting-started/first-success.md).

## Manual path

### Inventory accounts and ports

Decide OSS self-host vs Ringdom-managed. Free **3000** and **5432** (or set `DB_PORT` / app `PORT` deliberately).

### Provision Postgres with PostGIS

Create DB `ring_platform` / user `ring_user` (or match your `DATABASE_URL`). Confirm `CREATE EXTENSION postgis` will succeed before applying `data/schema.sql`.

### Scaffold env without inventing keys

Copy `env.local.template` → `.env.local` (or let `install.sh` do it). Set `DB_BACKEND_MODE`, generate `AUTH_SECRET` / `WALLET_ENCRYPTION_KEY`, add one auth path. Do not paste production secrets into docs or git.

## Frequently asked questions

### Impact

#### Will my clone boot without Google OAuth?

Yes for process boot — `AUTH_SECRET` + `DB_BACKEND_MODE` matter first. Tester login still needs **at least one** provider: Google, Apple, or Ring Mailer (Ethereal/SMTP).

#### Do I need Firebase on day one?

Not for Postgres-primary app data. Firebase Admin / `NEXT_PUBLIC_FIREBASE_*` matter when you enable **FCM push**, or when you choose `firebase-full`.

#### Do I need Redis?

No for a single-replica local `npm run dev`. Set `REDIS_URL` when you want shared rate-limit / set-nx across processes.

### Ops

#### Node 18 — still supported?

No. `install.sh` requires **Node 20+**. Prefer Node 22+ per `INSTALL.md` troubleshooting examples.

#### PostGIS failed on `schema.sql`?

Install PostGIS for your Postgres (Homebrew `postgis`, or a PostGIS image). Flattened schema **4.1.0** enables the extension on fresh apply.

#### `/api/health` is not healthy?

Check `.env.local` has `AUTH_SECRET`. On Postgres detection paths the health route treats that secret as critical; missing Firebase vars matter more on non-Postgres setups.

#### Managed hosting — skip this page?

Mostly yes for first boot. Keep it as the contract when you later attach custom OAuth, payments, or a fork of Layer1.

## Related documentation

  
- [getting-started/installation](/docs/getting-started/installation.md) — Next-step: run install.sh and apply schema after this checklist.

  
- [getting-started/migrations](/docs/getting-started/migrations.md) — Depends-on: Postgres + PostGIS before data/schema.sql apply.

  
- [getting-started/first-success](/docs/getting-started/first-success.md) — Next-step: smoke-test after npm run dev.

  
- [deployment/environment](/docs/deployment/environment.md) — Deep-dive: full env.local.template surface beyond the first-boot minimum.

  
- [architecture/backend-modes-and-databases](/docs/architecture/backend-modes-and-databases.md) — Same-workflow: choose DB_BACKEND_MODE before first boot.

> **Success**
> Prerequisites met? Continue to [Installation](/docs/getting-started/installation.md).

=20 in package.json so npm/yarn warn early — today only install.sh enforces Node 20+."
  implementationCost={4}
  labels={['tooling']}
  voteCount={0}
/>