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
Before Installation: 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.
| 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 |
Default for ring-platform.org and clone parity: DB_BACKEND_MODE=k8s-postgres-fcm. See Backend modes and Database selection.
| 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 |
| PostgreSQL | 14+ (Docker image 16; Homebrew 18 common in docs) | DB ring_platform, user ring_user — env.local.template |
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.
Use the Getting Started hub flow: meet this checklist → run install.sh → apply schema → smoke-test.
./install.sh --quick or manual env).Decide OSS self-host vs Ringdom-managed. Free 3000 and 5432 (or set DB_PORT / app PORT deliberately).
Create DB ring_platform / user ring_user (or match your DATABASE_URL). Confirm CREATE EXTENSION postgis will succeed before applying data/schema.sql.
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.
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).
Not for Postgres-primary app data. Firebase Admin / NEXT_PUBLIC_FIREBASE_* matter when you enable FCM push, or when you choose firebase-full.
No for a single-replica local npm run dev. Set REDIS_URL when you want shared rate-limit / set-nx across processes.
No. install.sh requires Node 20+. Prefer Node 22+ per INSTALL.md troubleshooting examples.
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.
Mostly yes for first boot. Keep it as the contract when you later attach custom OAuth, payments, or a fork of Layer1.
Next-step: run install.sh and apply schema after this checklist.
Depends-on: Postgres + PostGIS before data/schema.sql apply.
Next-step: smoke-test after npm run dev.
Deep-dive: full env.local.template surface beyond the first-boot minimum.
Prerequisites met? Continue to Installation.
Before Installation: 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.
| 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 |
Default for ring-platform.org and clone parity: DB_BACKEND_MODE=k8s-postgres-fcm. See Backend modes and Database selection.
| 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 |
| PostgreSQL | 14+ (Docker image 16; Homebrew 18 common in docs) | DB ring_platform, user ring_user — env.local.template |
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.
Use the Getting Started hub flow: meet this checklist → run install.sh → apply schema → smoke-test.
./install.sh --quick or manual env).Decide OSS self-host vs Ringdom-managed. Free 3000 and 5432 (or set DB_PORT / app PORT deliberately).
Create DB ring_platform / user ring_user (or match your DATABASE_URL). Confirm CREATE EXTENSION postgis will succeed before applying data/schema.sql.
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.
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).
Not for Postgres-primary app data. Firebase Admin / NEXT_PUBLIC_FIREBASE_* matter when you enable FCM push, or when you choose firebase-full.
No for a single-replica local npm run dev. Set REDIS_URL when you want shared rate-limit / set-nx across processes.
No. install.sh requires Node 20+. Prefer Node 22+ per INSTALL.md troubleshooting examples.
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.
Mostly yes for first boot. Keep it as the contract when you later attach custom OAuth, payments, or a fork of Layer1.
Next-step: run install.sh and apply schema after this checklist.
Depends-on: Postgres + PostGIS before data/schema.sql apply.
Next-step: smoke-test after npm run dev.
Deep-dive: full env.local.template surface beyond the first-boot minimum.
Prerequisites met? Continue to Installation.
Before Installation: 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.
| 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 |
Default for ring-platform.org and clone parity: DB_BACKEND_MODE=k8s-postgres-fcm. See Backend modes and Database selection.
| 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 |
| PostgreSQL | 14+ (Docker image 16; Homebrew 18 common in docs) | DB ring_platform, user ring_user — env.local.template |
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.
Use the Getting Started hub flow: meet this checklist → run install.sh → apply schema → smoke-test.
./install.sh --quick or manual env).Decide OSS self-host vs Ringdom-managed. Free 3000 and 5432 (or set DB_PORT / app PORT deliberately).
Create DB ring_platform / user ring_user (or match your DATABASE_URL). Confirm CREATE EXTENSION postgis will succeed before applying data/schema.sql.
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.
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).
Not for Postgres-primary app data. Firebase Admin / NEXT_PUBLIC_FIREBASE_* matter when you enable FCM push, or when you choose firebase-full.
No for a single-replica local npm run dev. Set REDIS_URL when you want shared rate-limit / set-nx across processes.
No. install.sh requires Node 20+. Prefer Node 22+ per INSTALL.md troubleshooting examples.
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.
Mostly yes for first boot. Keep it as the contract when you later attach custom OAuth, payments, or a fork of Layer1.
Next-step: run install.sh and apply schema after this checklist.
Depends-on: Postgres + PostGIS before data/schema.sql apply.
Next-step: smoke-test after npm run dev.
Deep-dive: full env.local.template surface beyond the first-boot minimum.
Prerequisites met? Continue to Installation.
| 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 |
At least one Auth.js path: Google OAuth, Apple, or Ring Mailer (SMTP_* or EMAIL_MODE=ethereal).
| 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 |
| 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.
Ringdom-managed hosting skips most of this checklist — settlers receive a configured cluster. Self-hosters on GitHub follow this page (OSS vs enterprise).
supabase-fcm| Postgres on Supabase + optional FCM |
firebase-full | Firestore prototype only |
DATABASE_MODE is removed — do not set it. Deep dive: Backend modes.
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 uploadsWAYFORPAY_* / STRIPE_* — PaymentConductorNEXT_PUBLIC_FIREBASE_* + Admin service account — FCM push (not Firestore DB on postgres-primary)OPENAI_API_KEY / ANTHROPIC_API_KEY — AI matcher / Email CRMREDIS_URL — optional; in-process fallback when unsetNever commit .env.local. See Environment configuration.
Expect "healthy" when AUTH_SECRET is set (app/api/health/route.ts treats missing AUTH_SECRET as critical). See Monitoring.
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.
Same-workflow: choose DB_BACKEND_MODE before first boot.
| 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 |
At least one Auth.js path: Google OAuth, Apple, or Ring Mailer (SMTP_* or EMAIL_MODE=ethereal).
| 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 |
| 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.
Ringdom-managed hosting skips most of this checklist — settlers receive a configured cluster. Self-hosters on GitHub follow this page (OSS vs enterprise).
supabase-fcm| Postgres on Supabase + optional FCM |
firebase-full | Firestore prototype only |
DATABASE_MODE is removed — do not set it. Deep dive: Backend modes.
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 uploadsWAYFORPAY_* / STRIPE_* — PaymentConductorNEXT_PUBLIC_FIREBASE_* + Admin service account — FCM push (not Firestore DB on postgres-primary)OPENAI_API_KEY / ANTHROPIC_API_KEY — AI matcher / Email CRMREDIS_URL — optional; in-process fallback when unsetNever commit .env.local. See Environment configuration.
Expect "healthy" when AUTH_SECRET is set (app/api/health/route.ts treats missing AUTH_SECRET as critical). See Monitoring.
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.
Same-workflow: choose DB_BACKEND_MODE before first boot.
| 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 |
At least one Auth.js path: Google OAuth, Apple, or Ring Mailer (SMTP_* or EMAIL_MODE=ethereal).
| 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 |
| 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.
Ringdom-managed hosting skips most of this checklist — settlers receive a configured cluster. Self-hosters on GitHub follow this page (OSS vs enterprise).
supabase-fcm| Postgres on Supabase + optional FCM |
firebase-full | Firestore prototype only |
DATABASE_MODE is removed — do not set it. Deep dive: Backend modes.
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 uploadsWAYFORPAY_* / STRIPE_* — PaymentConductorNEXT_PUBLIC_FIREBASE_* + Admin service account — FCM push (not Firestore DB on postgres-primary)OPENAI_API_KEY / ANTHROPIC_API_KEY — AI matcher / Email CRMREDIS_URL — optional; in-process fallback when unsetNever commit .env.local. See Environment configuration.
Expect "healthy" when AUTH_SECRET is set (app/api/health/route.ts treats missing AUTH_SECRET as critical). See Monitoring.
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.
Same-workflow: choose DB_BACKEND_MODE before first boot.