Loading documentation...
Preparing Ring content
Concepts, value, and typical clone scenarios — less code.
Concepts, value, and typical clone scenarios — less code.
Preparing Ring content
Preparing Ring content
Preparing Ring content
Use Founder / Developer tabs in the docs sidebar to filter this page. Complete Prerequisites first. This guide matches the open-source repo (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.
| 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 |
You are standing up a dev clone so stakeholders can click through branding, auth, and core marketplace flows before production hosting.
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.
No. WayForPay / Stripe belong later — after First success, before checkout demos.
Fresh installs: apply data/schema.sql, then news/payment/email increments as documented on Migrations. Do not apply obsolete 001_email_crm_schema.sql.
Same app DB name (ring_platform) and DB_* contract. Monorepo compose uses volume ringdom_postgres_data and init scripts under infrastructure/postgres/init/.
lsof -ti:3000 | xargs kill or PORT=3001 npm run dev.
Check AUTH_GOOGLE_*, redirect URI http://localhost:3000/api/auth/callback/google, and non-empty AUTH_SECRET.
Confirm RING_DEPLOY_TARGET=self-hosted (and public twin) for local WSS. On Vercel use vercel / SSE-only.
More: Troubleshooting.
Prerequisite: confirm Node, Postgres, and ports before you clone.
Next-step: apply data/schema.sql and kingdom migration order after env scaffold.
Next-step: smoke-test health, auth, and CRUD once npm run dev is up.
Deep-dive: choose k8s-postgres-fcm, supabase-fcm, or firebase-full.
Use Founder / Developer tabs in the docs sidebar to filter this page. Complete Prerequisites first. This guide matches the open-source repo (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.
| 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 |
You are standing up a dev clone so stakeholders can click through branding, auth, and core marketplace flows before production hosting.
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.
No. WayForPay / Stripe belong later — after First success, before checkout demos.
Fresh installs: apply data/schema.sql, then news/payment/email increments as documented on Migrations. Do not apply obsolete 001_email_crm_schema.sql.
Same app DB name (ring_platform) and DB_* contract. Monorepo compose uses volume ringdom_postgres_data and init scripts under infrastructure/postgres/init/.
lsof -ti:3000 | xargs kill or PORT=3001 npm run dev.
Check AUTH_GOOGLE_*, redirect URI http://localhost:3000/api/auth/callback/google, and non-empty AUTH_SECRET.
Confirm RING_DEPLOY_TARGET=self-hosted (and public twin) for local WSS. On Vercel use vercel / SSE-only.
More: Troubleshooting.
Prerequisite: confirm Node, Postgres, and ports before you clone.
Next-step: apply data/schema.sql and kingdom migration order after env scaffold.
Next-step: smoke-test health, auth, and CRUD once npm run dev is up.
Deep-dive: choose k8s-postgres-fcm, supabase-fcm, or firebase-full.
Use Founder / Developer tabs in the docs sidebar to filter this page. Complete Prerequisites first. This guide matches the open-source repo (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.
| 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 |
You are standing up a dev clone so stakeholders can click through branding, auth, and core marketplace flows before production hosting.
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.
No. WayForPay / Stripe belong later — after First success, before checkout demos.
Fresh installs: apply data/schema.sql, then news/payment/email increments as documented on Migrations. Do not apply obsolete 001_email_crm_schema.sql.
Same app DB name (ring_platform) and DB_* contract. Monorepo compose uses volume ringdom_postgres_data and init scripts under infrastructure/postgres/init/.
lsof -ti:3000 | xargs kill or PORT=3001 npm run dev.
Check AUTH_GOOGLE_*, redirect URI http://localhost:3000/api/auth/callback/google, and non-empty AUTH_SECRET.
Confirm RING_DEPLOY_TARGET=self-hosted (and public twin) for local WSS. On Vercel use vercel / SSE-only.
More: Troubleshooting.
Prerequisite: confirm Node, Postgres, and ports before you clone.
Next-step: apply data/schema.sql and kingdom migration order after env scaffold.
Next-step: smoke-test health, auth, and CRUD once npm run dev is up.
Deep-dive: choose k8s-postgres-fcm, supabase-fcm, or firebase-full.
Smoke-test checklist after npm run dev
| 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 |
| Ringdom-managed settler | Skip most of this | Cluster is already provisioned — customize via ring-config / ops, not local Docker |
Payments, FCM push, and Web3 wallets are not required for first boot. Add them before checkout or production push — see Environment.
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 |
.env.local valuesThe 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).
Use Docker / existing server / Ringdom monorepo tabs below, or:
Full incremental order: Database migrations.
Use when you already control env files or package manager.
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.
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 for apply order.
Standalone clone — no Ringdom monorepo required:
Apply base schema, then kingdom increments (abbreviated — full matrix on the migrations page):
001_email_crm_schema.sql is obsolete. Prefer 009 + 010 JSONB. Idempotent increments already merged into schema.sql are covered in Migrations.
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.
Application data on PostgreSQL; Firebase Admin used only for FCM push when configured. Matches ring-platform.org production posture.
In Google Cloud Console, add authorized redirect URI:
http://localhost:3000/api/auth/callback/google
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.
Expect log lines similar to:
> 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.
Visit http://localhost:3000 — home renders via HomeWrapper (components/wrappers/home-wrapper.tsx) and locale files under locales/{en,uk,ru}/.
Optional:
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.
| 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 |
Same-workflow: project structure and day-to-day local tools after install.
Smoke-test checklist after npm run dev
| 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 |
| Ringdom-managed settler | Skip most of this | Cluster is already provisioned — customize via ring-config / ops, not local Docker |
Payments, FCM push, and Web3 wallets are not required for first boot. Add them before checkout or production push — see Environment.
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 |
.env.local valuesThe 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).
Use Docker / existing server / Ringdom monorepo tabs below, or:
Full incremental order: Database migrations.
Use when you already control env files or package manager.
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.
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 for apply order.
Standalone clone — no Ringdom monorepo required:
Apply base schema, then kingdom increments (abbreviated — full matrix on the migrations page):
001_email_crm_schema.sql is obsolete. Prefer 009 + 010 JSONB. Idempotent increments already merged into schema.sql are covered in Migrations.
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.
Application data on PostgreSQL; Firebase Admin used only for FCM push when configured. Matches ring-platform.org production posture.
In Google Cloud Console, add authorized redirect URI:
http://localhost:3000/api/auth/callback/google
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.
Expect log lines similar to:
> 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.
Visit http://localhost:3000 — home renders via HomeWrapper (components/wrappers/home-wrapper.tsx) and locale files under locales/{en,uk,ru}/.
Optional:
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.
| 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 |
Same-workflow: project structure and day-to-day local tools after install.
Smoke-test checklist after npm run dev
| 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 |
| Ringdom-managed settler | Skip most of this | Cluster is already provisioned — customize via ring-config / ops, not local Docker |
Payments, FCM push, and Web3 wallets are not required for first boot. Add them before checkout or production push — see Environment.
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 |
.env.local valuesThe 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).
Use Docker / existing server / Ringdom monorepo tabs below, or:
Full incremental order: Database migrations.
Use when you already control env files or package manager.
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.
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 for apply order.
Standalone clone — no Ringdom monorepo required:
Apply base schema, then kingdom increments (abbreviated — full matrix on the migrations page):
001_email_crm_schema.sql is obsolete. Prefer 009 + 010 JSONB. Idempotent increments already merged into schema.sql are covered in Migrations.
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.
Application data on PostgreSQL; Firebase Admin used only for FCM push when configured. Matches ring-platform.org production posture.
In Google Cloud Console, add authorized redirect URI:
http://localhost:3000/api/auth/callback/google
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.
Expect log lines similar to:
> 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.
Visit http://localhost:3000 — home renders via HomeWrapper (components/wrappers/home-wrapper.tsx) and locale files under locales/{en,uk,ru}/.
Optional:
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.
| 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 |
Same-workflow: project structure and day-to-day local tools after install.