Завантаження документації...
Підготовка контенту платформи Ring
Concepts, value, and typical clone scenarios — less code.
Concepts, value, and typical clone scenarios — less code.
Підготовка контенту платформи Ring
Підготовка контенту платформи Ring
Підготовка контенту платформи Ring
Install Ring Platform on your machine for local development. This guide matches the open-source repo (connectplatform/ring) and the PostgreSQL-primary default (DB_BACKEND_MODE=k8s-postgres-fcm).
45–90 minutes for a full Postgres-primary install (first time). ./install.sh --quick plus an existing PostgreSQL instance can be faster.
Node.js 20+, Git, hardware, and optional Docker
data/schema.sql v4+ and kingdom migration order
k8s-postgres-fcm, supabase-fcm, or firebase-full
Smoke-test checklist after npm run dev
| Component | Version / entry |
|---|---|
| Framework | Next.js 16 App Router + React 19 |
| Auth | Auth.js v5 (auth.ts, AUTH_SECRET, OAuth providers) |
| Default data plane | PostgreSQL (k8s-postgres-fcm) — not Firestore for app data |
| Dev server | Custom server.ts — Next.js + native WebSocket tunnel (/api/tunnel/ws) |
| White-label config | ring-config.json (created by install.sh) |
install.sh v2.0 scaffolds ring-config.json, copies env.local.template → .env.local, generates secrets, and runs npm install.
Useful flags:
--clone-name my-ring — white-label slug in ring-config.json--quick — non-interactive defaultsdev / prod — explicit setup mode--help — full option list.env.local valuesThe template is copied automatically. At minimum, set database connection vars and one OAuth provider before first boot (see Configure environment below).
Production-style local dev uses database ring_platform with user ring_user. App schema lives in data/schema.sql (v4.0.1+).
DB_BACKEND_MODE is mandatory. The platform expects PostgreSQL when set to k8s-postgres-fcm (the template default). See Database migrations for the full apply order.
Start PostgreSQL 16 locally (standalone clone — no Ringdom monorepo required):
Apply schema and kingdom migrations:
Incremental files 005–008 and 011 are idempotent when already merged into schema.sql. See Database migrations — do not apply deprecated 001_email_crm_schema.sql.
Set these in .env.local (from env.local.template). Values shown are local dev defaults.
Application data on PostgreSQL; Firebase Admin used only for FCM push when configured. Matches ring-platform.org production.
In Google Cloud Console, add authorized redirect URI:
http://localhost:3000/api/auth/callback/google
npm run dev starts the unified custom server (server.ts) with native WebSocket at /api/tunnel/ws. On Vercel, set RING_DEPLOY_TARGET=vercel for SSE-only mode.
For push notifications, add Firebase Admin + client keys from the template. Not required to load the homepage or browse entities with Postgres-only auth.
Keep AUTH_FIREBASE_PRIVATE_KEY in double quotes with literal \\n newlines (or real newlines inside quotes). Never commit .env.local.
Defaults match ring-platform.org community portal:
Expected log line:
First compile may take 30–60 seconds.
Visit http://localhost:3000 — home renders via HomeWrapper and locale files under locales/{en,uk,ru}/.
If the homepage loads without database adapter errors, proceed to First success validation.
| Symptom | Fix |
|---|---|
| Port 3000 in use | lsof -ti:3000 | xargs kill or PORT=3001 npm run dev |
| Database connection failed | Verify Postgres is running, DB_* vars match, and data/schema.sql was applied |
| Google sign-in fails | Check AUTH_GOOGLE_*, Firebase/Google redirect URI, and AUTH_SECRET |
| Module not found | Re-run npm install from repo root |
| Tunnel errors in console | Confirm RING_DEPLOY_TARGET=self-hosted for local WSS |
More: Troubleshooting.
Install Ring Platform on your machine for local development. This guide matches the open-source repo (connectplatform/ring) and the PostgreSQL-primary default (DB_BACKEND_MODE=k8s-postgres-fcm).
45–90 minutes for a full Postgres-primary install (first time). ./install.sh --quick plus an existing PostgreSQL instance can be faster.
Node.js 20+, Git, hardware, and optional Docker
data/schema.sql v4+ and kingdom migration order
k8s-postgres-fcm, supabase-fcm, or firebase-full
Smoke-test checklist after npm run dev
| Component | Version / entry |
|---|---|
| Framework | Next.js 16 App Router + React 19 |
| Auth | Auth.js v5 (auth.ts, AUTH_SECRET, OAuth providers) |
| Default data plane | PostgreSQL (k8s-postgres-fcm) — not Firestore for app data |
| Dev server | Custom server.ts — Next.js + native WebSocket tunnel (/api/tunnel/ws) |
| White-label config | ring-config.json (created by install.sh) |
install.sh v2.0 scaffolds ring-config.json, copies env.local.template → .env.local, generates secrets, and runs npm install.
Useful flags:
--clone-name my-ring — white-label slug in ring-config.json--quick — non-interactive defaultsdev / prod — explicit setup mode--help — full option list.env.local valuesThe template is copied automatically. At minimum, set database connection vars and one OAuth provider before first boot (see Configure environment below).
Production-style local dev uses database ring_platform with user ring_user. App schema lives in data/schema.sql (v4.0.1+).
DB_BACKEND_MODE is mandatory. The platform expects PostgreSQL when set to k8s-postgres-fcm (the template default). See Database migrations for the full apply order.
Start PostgreSQL 16 locally (standalone clone — no Ringdom monorepo required):
Apply schema and kingdom migrations:
Incremental files 005–008 and 011 are idempotent when already merged into schema.sql. See Database migrations — do not apply deprecated 001_email_crm_schema.sql.
Set these in .env.local (from env.local.template). Values shown are local dev defaults.
Application data on PostgreSQL; Firebase Admin used only for FCM push when configured. Matches ring-platform.org production.
In Google Cloud Console, add authorized redirect URI:
http://localhost:3000/api/auth/callback/google
npm run dev starts the unified custom server (server.ts) with native WebSocket at /api/tunnel/ws. On Vercel, set RING_DEPLOY_TARGET=vercel for SSE-only mode.
For push notifications, add Firebase Admin + client keys from the template. Not required to load the homepage or browse entities with Postgres-only auth.
Keep AUTH_FIREBASE_PRIVATE_KEY in double quotes with literal \\n newlines (or real newlines inside quotes). Never commit .env.local.
Defaults match ring-platform.org community portal:
Expected log line:
First compile may take 30–60 seconds.
Visit http://localhost:3000 — home renders via HomeWrapper and locale files under locales/{en,uk,ru}/.
If the homepage loads without database adapter errors, proceed to First success validation.
| Symptom | Fix |
|---|---|
| Port 3000 in use | lsof -ti:3000 | xargs kill or PORT=3001 npm run dev |
| Database connection failed | Verify Postgres is running, DB_* vars match, and data/schema.sql was applied |
| Google sign-in fails | Check AUTH_GOOGLE_*, Firebase/Google redirect URI, and AUTH_SECRET |
| Module not found | Re-run npm install from repo root |
| Tunnel errors in console | Confirm RING_DEPLOY_TARGET=self-hosted for local WSS |
More: Troubleshooting.
Install Ring Platform on your machine for local development. This guide matches the open-source repo (connectplatform/ring) and the PostgreSQL-primary default (DB_BACKEND_MODE=k8s-postgres-fcm).
45–90 minutes for a full Postgres-primary install (first time). ./install.sh --quick plus an existing PostgreSQL instance can be faster.
Node.js 20+, Git, hardware, and optional Docker
data/schema.sql v4+ and kingdom migration order
k8s-postgres-fcm, supabase-fcm, or firebase-full
Smoke-test checklist after npm run dev
| Component | Version / entry |
|---|---|
| Framework | Next.js 16 App Router + React 19 |
| Auth | Auth.js v5 (auth.ts, AUTH_SECRET, OAuth providers) |
| Default data plane | PostgreSQL (k8s-postgres-fcm) — not Firestore for app data |
| Dev server | Custom server.ts — Next.js + native WebSocket tunnel (/api/tunnel/ws) |
| White-label config | ring-config.json (created by install.sh) |
install.sh v2.0 scaffolds ring-config.json, copies env.local.template → .env.local, generates secrets, and runs npm install.
Useful flags:
--clone-name my-ring — white-label slug in ring-config.json--quick — non-interactive defaultsdev / prod — explicit setup mode--help — full option list.env.local valuesThe template is copied automatically. At minimum, set database connection vars and one OAuth provider before first boot (see Configure environment below).
Production-style local dev uses database ring_platform with user ring_user. App schema lives in data/schema.sql (v4.0.1+).
DB_BACKEND_MODE is mandatory. The platform expects PostgreSQL when set to k8s-postgres-fcm (the template default). See Database migrations for the full apply order.
Start PostgreSQL 16 locally (standalone clone — no Ringdom monorepo required):
Apply schema and kingdom migrations:
Incremental files 005–008 and 011 are idempotent when already merged into schema.sql. See Database migrations — do not apply deprecated 001_email_crm_schema.sql.
Set these in .env.local (from env.local.template). Values shown are local dev defaults.
Application data on PostgreSQL; Firebase Admin used only for FCM push when configured. Matches ring-platform.org production.
In Google Cloud Console, add authorized redirect URI:
http://localhost:3000/api/auth/callback/google
npm run dev starts the unified custom server (server.ts) with native WebSocket at /api/tunnel/ws. On Vercel, set RING_DEPLOY_TARGET=vercel for SSE-only mode.
For push notifications, add Firebase Admin + client keys from the template. Not required to load the homepage or browse entities with Postgres-only auth.
Keep AUTH_FIREBASE_PRIVATE_KEY in double quotes with literal \\n newlines (or real newlines inside quotes). Never commit .env.local.
Defaults match ring-platform.org community portal:
Expected log line:
First compile may take 30–60 seconds.
Visit http://localhost:3000 — home renders via HomeWrapper and locale files under locales/{en,uk,ru}/.
If the homepage loads without database adapter errors, proceed to First success validation.
| Symptom | Fix |
|---|---|
| Port 3000 in use | lsof -ti:3000 | xargs kill or PORT=3001 npm run dev |
| Database connection failed | Verify Postgres is running, DB_* vars match, and data/schema.sql was applied |
| Google sign-in fails | Check AUTH_GOOGLE_*, Firebase/Google redirect URI, and AUTH_SECRET |
| Module not found | Re-run npm install from repo root |
| Tunnel errors in console | Confirm RING_DEPLOY_TARGET=self-hosted for local WSS |
More: Troubleshooting.
> Ready on http://localhost:3000 [self-hosted]
[server] Native WSS attached at /api/tunnel/ws (RING_DEPLOY_TARGET=self-hosted)
> Ready on http://localhost:3000 [self-hosted]
[server] Native WSS attached at /api/tunnel/ws (RING_DEPLOY_TARGET=self-hosted)
> Ready on http://localhost:3000 [self-hosted]
[server] Native WSS attached at /api/tunnel/ws (RING_DEPLOY_TARGET=self-hosted)