---
title: "Getting Started"
description: "Bootstrap Ring Platform locally — install.sh, PostgreSQL-primary backend, Auth.js v5, schema migrations, and first-success validation"
locale: "en"
---
# Getting Started

Bootstrap a **Ring Platform** white-label clone on your machine. This hub maps the real dev flow used in the open-source tree ([connectplatform/ring](https://github.com/connectplatform/ring)) and on **ring-platform.org** — the community portal for self-hosted enthusiasts.

| Path | Time | Outcome |
|------|------|---------|
| **`./install.sh --quick`** + existing PostgreSQL | ~20–40 min | Clone config, deps, env scaffold — you still apply schema + OAuth |
| **Full Postgres-primary bootstrap** | 45–90 min | Production-parity local stack (`k8s-postgres-fcm`) |
| **Prototype (`firebase-full`)** | ~15–30 min | Firestore-only — skips ERP, News Kingdom, PaymentConductor depth |

New to the vision first? Read [Welcome to Ring](/docs/welcome.md), then return here.

**Self-hosting from GitHub?** Follow this section. **Ringdom turn-key hosting?** Start at [ringdom.org](https://ringdom.org) — after handoff use [Customization guide](/docs/customization/customization-guide.md). The public OSS tree ships `install.sh` and community scripts; enterprise k8s/CLI tooling stays outside the public boundary ([`FEATURESET.md`](https://github.com/connectplatform/ring/blob/main/FEATURESET.md)).

## What you will configure

| Layer | Canonical artifact | Purpose |
|-------|-------------------|---------|
| **Clone identity** | `ring-config.json` | Branding, feature flags, domains (`ring-config.template.json`) |
| **Secrets & backend** | `.env.local` | `DB_BACKEND_MODE`, `AUTH_*`, Firebase FCM, tunnel deploy target |
| **Application data** | PostgreSQL `ring_platform` | `data/schema.sql` v4.0.1+ + kingdom migrations |
| **Auth** | Auth.js v5 (`auth.ts`) | `AUTH_SECRET` + at least one OAuth provider for login |
| **Dev runtime** | `server.ts` | `npm run dev` — Next.js 16 + React 19 + native WSS when `RING_DEPLOY_TARGET=self-hosted` |

## Three ways to obtain Ring Platform

Interactive paths with **copyable install commands** — self-deploy from GitHub, LegioX-guided customization, or Promptor partnership.

## Recommended bootstrap (Postgres-primary)

Production and local dev use **`DB_BACKEND_MODE=k8s-postgres-fcm`** — PostgreSQL for app data, Firebase Admin **only for FCM push** when configured.

### 1 — Clone and run `install.sh`

{`git clone https://github.com/connectplatform/ring.git
cd ring
chmod +x install.sh
./install.sh --quick`}

`install.sh` v2.0 (see [`INSTALL.md`](https://github.com/connectplatform/ring/blob/main/INSTALL.md)):

- System requirements check (Node.js 20+, npm 10+)
- Creates **`ring-config.json`** from template (`--clone-name` for white-label slug)
- Copies **`env.local.template`** → **`.env.local`** with generated `AUTH_SECRET` and `WALLET_ENCRYPTION_KEY`
- Runs **`npm install`**
- Optionally materializes `next.config.mjs`, `docker-compose.yml`, `Dockerfile` from templates

Flags: `--quick`, `--clone-name my-ring`, `--verbose`, `--help`.

### 2 — Provision PostgreSQL

Start Postgres 16+ and database **`ring_platform`** (user **`ring_user`**). Options:

- **Docker** — one-container dev (see [Installation](/docs/getting-started/installation.md#postgresql-setup))
- **Ringdom monorepo** — `docker compose -f docker-compose.dev.yml up -d postgres` or `./infrastructure/postgres/bootstrap-brew-dev.sh`
- **Existing server** — create DB + set `DB_HOST` / `DB_*` in `.env.local`

### 3 — Apply schema and kingdom migrations

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

Full order, idempotent increments, and Ring-clone matrix: [Database migrations](/docs/getting-started/migrations.md). Helper: `./scripts/run-migration.sh` when pointed at your `ring-postgres-dev` container.

### 4 — Finish auth and local URLs

Minimum in `.env.local`:

{`DB_BACKEND_MODE=k8s-postgres-fcm
AUTH_SECRET=          # openssl rand -base64 32
AUTH_GOOGLE_ID=
AUTH_GOOGLE_SECRET=
NEXT_PUBLIC_BASE_URL=http://localhost:3000
RING_DEPLOY_TARGET=self-hosted
NEXT_PUBLIC_RING_DEPLOY_TARGET=self-hosted`}

Add Google OAuth redirect: `http://localhost:3000/api/auth/callback/google`.

Interactive env wizard (after template copy): `npm run setup:env` or `./scripts/setup-dev.sh`.

### 5 — Start dev server and validate

{`npm run dev`}

Expect: `Ready on http://localhost:3000 [self-hosted]` and native WSS at `/api/tunnel/ws`.

Then run [First success validation](/docs/getting-started/first-success.md) — homepage, `/login`, entities/opportunities without DB adapter errors. Optional: `npm run type-check`, `npm run portal:health`.

Visit [http://localhost:3000](http://localhost:3000). Customize branding in `ring-config.json` and explore [Next steps](/docs/getting-started/next-steps.md).

## Alternative paths

Skip the installer wizard — same outcome, more control:

{`git clone https://github.com/connectplatform/ring.git
cd ring
npm install
cp env.local.template .env.local
cp ring-config.template.json ring-config.json
# edit ring-config.json + .env.local
# provision PostgreSQL + apply migrations (steps 2–3 above)
npm run dev`}

Deep dive: [Installation](/docs/getting-started/installation.md).

Fast Vercel-edge prototyping — **not** the ring-platform.org production data plane:

{`DB_BACKEND_MODE=firebase-full`}

Configure Firebase Admin + client keys from `env.local.template`. No `data/schema.sql` required. Feature gaps: [Database selection](/docs/customization/database-selection.md).

When `ring-platform.org` lives inside the Ringdom kingdom checkout:

{`docker compose -f docker-compose.dev.yml up -d postgres
cd ring-platform.org
npm install
# .env.local already or: npm run setup:env
npm run dev`}

Multi-clone Postgres manifest: `infrastructure/postgres/DEV-DATABASE-MANIFEST.json`.

## Guides in this section

  
- **[Prerequisites](/docs/getting-started/prerequisites.md)** — Node.js 20+, hardware, OS support, Firebase/Google Cloud accounts

  
- **[Installation](/docs/getting-started/installation.md)** — Full install paths, env reference, tunnel config, common issues table

  
- **[Database migrations](/docs/getting-started/migrations.md)** — `schema.sql` v4.0.1+, kingdom files 002–011, clone DB matrix

  
- **[First success validation](/docs/getting-started/first-success.md)** — Smoke-test auth, entities, opportunities, and API health

  
- **[Troubleshooting](/docs/getting-started/troubleshooting.md)** — FETCH_FAILED, wallet bootstrap, OAuth redirects, diagnostics

  
- **[Next steps](/docs/getting-started/next-steps.md)** — Admin, first entity, opportunities, messaging, deployment pointer

## Related docs

  
- **[Customization quick start](/docs/customization/quick-start.md)** — White-label clone checklist beyond first boot

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

  
- **[Local development setup](/docs/development/local-setup.md)** — Project structure, testing, Homebrew Postgres bootstrap

  
- **[Architecture — backend modes](/docs/architecture/backend-modes-and-databases.md)** — BackendSelector, adapters, FCM vs Firestore

## Quick reference — bootstrap commands

| Task | Command |
|------|---------|
| One-command install | `git clone … && ./install.sh --quick` |
| Env wizard | `npm run setup:env` |
| Dev env script | `./scripts/setup-dev.sh` |
| Apply migration file | `./scripts/run-migration.sh data/schema.sql` |
| Dev server | `npm run dev` |
| Type check | `npm run type-check` |
| Portal health | `npm run portal:health` |
| Repo install guide | [`INSTALL.md`](https://github.com/connectplatform/ring/blob/main/INSTALL.md) |

**`install.sh`** — first-time clone bootstrap (config files + `npm install`). **`setup-dev.sh`** — post-clone environment hardening and optional service wiring. Use **`npm run setup:env`** for a non-destructive interactive pass over an existing `.env.local`.