Self-hosted deployment

The public repository connectplatform/ring (Apache 2.0) contains everything you need to run a clone on one server: the Next.js app in web/, the install.sh wizard, a flattened PostgreSQL schema, Docker files and the ring CLI. Kubernetes manifests, CI workflows and Ringdom's build pipeline are not in it.

Frequently asked questions

Ops

Do I need Firebase?

No, not in k8s-postgres-fcm mode. Without NEXT_PUBLIC_FIREBASE_PROJECT_ID the app logs a warning and turns push off. firebase-full mode is different: it requires the AUTH_FIREBASE_* keys.

Can I upgrade later without losing my changes?

Yes. Use ring upgrade for a preview, then ring upgrade --apply. It merges upstream system files and never commits for you.

Known gaps

Related documentation

Self-hosted deployment

The public repository connectplatform/ring (Apache 2.0) contains everything you need to run a clone on one server: the Next.js app in web/, the install.sh wizard, a flattened PostgreSQL schema, Docker files and the ring CLI. Kubernetes manifests, CI workflows and Ringdom's build pipeline are not in it.

Frequently asked questions

Ops

Do I need Firebase?

No, not in k8s-postgres-fcm mode. Without NEXT_PUBLIC_FIREBASE_PROJECT_ID the app logs a warning and turns push off. firebase-full mode is different: it requires the AUTH_FIREBASE_* keys.

Can I upgrade later without losing my changes?

Yes. Use ring upgrade for a preview, then ring upgrade --apply. It merges upstream system files and never commits for you.

Known gaps

Related documentation

Self-hosted deployment

The public repository connectplatform/ring (Apache 2.0) contains everything you need to run a clone on one server: the Next.js app in web/, the install.sh wizard, a flattened PostgreSQL schema, Docker files and the ring CLI. Kubernetes manifests, CI workflows and Ringdom's build pipeline are not in it.

Frequently asked questions

Ops

Do I need Firebase?

No, not in k8s-postgres-fcm mode. Without NEXT_PUBLIC_FIREBASE_PROJECT_ID the app logs a warning and turns push off. firebase-full mode is different: it requires the AUTH_FIREBASE_* keys.

Can I upgrade later without losing my changes?

Yes. Use ring upgrade for a preview, then ring upgrade --apply. It merges upstream system files and never commits for you.

Known gaps

Related documentation

What you need before go-live

1. A domain and TLS in front of the app (for example a reverse proxy on port 443 forwarding to port 3000).
2. PostgreSQL 16 with one database for your clone.
3. Sign-in providers. At least one Auth.js provider (Google, Apple, Telegram, email) with keys.
4. A payment processor account if you sell anything: WayForPay, Stripe or PayPal.
5. Optional Firebase project for push notifications. Without it, push is disabled and the app still starts.

Typical scenarios

• Pilot community. One small VPS, PostgreSQL on the same box, WayForPay for memberships.
• Data-residency requirement. Everything in your own data center. Nothing leaves your network except payment and OAuth calls.
• Agency handover. A developer sets the clone up with install.sh, then hands you the server and the .env.local secrets.

1. 1

   Clone and run the wizard

   Dev mode checks your system, seeds ring-config.json from ring-config.template.json if missing, runs npm install, walks through Firebase and OAuth setup, and writes web/.env.local from env.local.template with a generated AUTH_SECRET. Answer no to the database prompt for now (see the warning above).

2. 2

   Create the database and apply the schema

   Grant your app role access to the public schema. Do not replay data/migrations/*.sql on an empty database. Those files are already folded into schema.sql.

3. 3

   Set the required environment

   Variable	Why
   DB_BACKEND_MODE=k8s-postgres-fcm	Required. PostgreSQL plus optional FCM push. The cluster does not have to be Kubernetes
   DB_HOST, DB_NAME, DB_USER, DB_PASSWORD	Required in this mode (validateBackendModeConfig)
   DB_PORT, DB_SSL	Defaults 5432 and false in the template
   AUTH_SECRET	Auth.js session encryption
   NEXT_PUBLIC_API_URL, AUTH_URL	Your public origin
   PAYMENT_DEFAULT_PROCESSOR	wayforpay, stripe or paypal
   NEXT_PUBLIC_FIREBASE_PROJECT_ID	Optional. Missing means push is disabled

4. 4

   Build, start and check health

   npm start runs the custom server.ts, not next start. Keep it under a process manager such as systemd. From the repo root, npm run build and npm start delegate to web/ through scripts/run-web.sh.

Other deploy modes in install.sh

./install.sh prod offers three options: Vercel (installs the Vercel CLI, runs vercel --prod), Ubuntu over SSH, and Kubernetes. The Kubernetes option applies k8s/*.yaml only if you have created a k8s/ directory yourself. For containers, start from Dockerfile (multi-stage node:25-alpine, runtime target, port 3000) and docker-compose.template.yml.

What stays private

What you need before go-live

1. A domain and TLS in front of the app (for example a reverse proxy on port 443 forwarding to port 3000).
2. PostgreSQL 16 with one database for your clone.
3. Sign-in providers. At least one Auth.js provider (Google, Apple, Telegram, email) with keys.
4. A payment processor account if you sell anything: WayForPay, Stripe or PayPal.
5. Optional Firebase project for push notifications. Without it, push is disabled and the app still starts.

Typical scenarios

• Pilot community. One small VPS, PostgreSQL on the same box, WayForPay for memberships.
• Data-residency requirement. Everything in your own data center. Nothing leaves your network except payment and OAuth calls.
• Agency handover. A developer sets the clone up with install.sh, then hands you the server and the .env.local secrets.

1. 1

   Clone and run the wizard

   Dev mode checks your system, seeds ring-config.json from ring-config.template.json if missing, runs npm install, walks through Firebase and OAuth setup, and writes web/.env.local from env.local.template with a generated AUTH_SECRET. Answer no to the database prompt for now (see the warning above).

2. 2

   Create the database and apply the schema

   Grant your app role access to the public schema. Do not replay data/migrations/*.sql on an empty database. Those files are already folded into schema.sql.

3. 3

   Set the required environment

   Variable	Why
   DB_BACKEND_MODE=k8s-postgres-fcm	Required. PostgreSQL plus optional FCM push. The cluster does not have to be Kubernetes
   DB_HOST, DB_NAME, DB_USER, DB_PASSWORD	Required in this mode (validateBackendModeConfig)
   DB_PORT, DB_SSL	Defaults 5432 and false in the template
   AUTH_SECRET	Auth.js session encryption
   NEXT_PUBLIC_API_URL, AUTH_URL	Your public origin
   PAYMENT_DEFAULT_PROCESSOR	wayforpay, stripe or paypal
   NEXT_PUBLIC_FIREBASE_PROJECT_ID	Optional. Missing means push is disabled

4. 4

   Build, start and check health

   npm start runs the custom server.ts, not next start. Keep it under a process manager such as systemd. From the repo root, npm run build and npm start delegate to web/ through scripts/run-web.sh.

Other deploy modes in install.sh

./install.sh prod offers three options: Vercel (installs the Vercel CLI, runs vercel --prod), Ubuntu over SSH, and Kubernetes. The Kubernetes option applies k8s/*.yaml only if you have created a k8s/ directory yourself. For containers, start from Dockerfile (multi-stage node:25-alpine, runtime target, port 3000) and docker-compose.template.yml.

What stays private

What you need before go-live

1. A domain and TLS in front of the app (for example a reverse proxy on port 443 forwarding to port 3000).
2. PostgreSQL 16 with one database for your clone.
3. Sign-in providers. At least one Auth.js provider (Google, Apple, Telegram, email) with keys.
4. A payment processor account if you sell anything: WayForPay, Stripe or PayPal.
5. Optional Firebase project for push notifications. Without it, push is disabled and the app still starts.

Typical scenarios

• Pilot community. One small VPS, PostgreSQL on the same box, WayForPay for memberships.
• Data-residency requirement. Everything in your own data center. Nothing leaves your network except payment and OAuth calls.
• Agency handover. A developer sets the clone up with install.sh, then hands you the server and the .env.local secrets.

1. 1

   Clone and run the wizard

   Dev mode checks your system, seeds ring-config.json from ring-config.template.json if missing, runs npm install, walks through Firebase and OAuth setup, and writes web/.env.local from env.local.template with a generated AUTH_SECRET. Answer no to the database prompt for now (see the warning above).

2. 2

   Create the database and apply the schema

   Grant your app role access to the public schema. Do not replay data/migrations/*.sql on an empty database. Those files are already folded into schema.sql.

3. 3

   Set the required environment

   Variable	Why
   DB_BACKEND_MODE=k8s-postgres-fcm	Required. PostgreSQL plus optional FCM push. The cluster does not have to be Kubernetes
   DB_HOST, DB_NAME, DB_USER, DB_PASSWORD	Required in this mode (validateBackendModeConfig)
   DB_PORT, DB_SSL	Defaults 5432 and false in the template
   AUTH_SECRET	Auth.js session encryption
   NEXT_PUBLIC_API_URL, AUTH_URL	Your public origin
   PAYMENT_DEFAULT_PROCESSOR	wayforpay, stripe or paypal
   NEXT_PUBLIC_FIREBASE_PROJECT_ID	Optional. Missing means push is disabled

4. 4

   Build, start and check health

   npm start runs the custom server.ts, not next start. Keep it under a process manager such as systemd. From the repo root, npm run build and npm start delegate to web/ through scripts/run-web.sh.

Other deploy modes in install.sh

./install.sh prod offers three options: Vercel (installs the Vercel CLI, runs vercel --prod), Ubuntu over SSH, and Kubernetes. The Kubernetes option applies k8s/*.yaml only if you have created a k8s/ directory yourself. For containers, start from Dockerfile (multi-stage node:25-alpine, runtime target, port 3000) and docker-compose.template.yml.

What stays private