---
title: "Instalación"
description: "Instala Ring Platform en local: clonado, install.sh o env manual, backend con PostgreSQL como base principal, Auth.js v5, esquema y el servidor propio unificado"
locale: "es"
---
# Instalación

> **Info**
> Usa las pestañas **Fundador** / **Desarrollador** de la barra lateral para filtrar esta página. Completa primero los [Requisitos previos](/docs/getting-started/prerequisites.md). Esta guía coincide con el repositorio de código abierto ([connectplatform/ring](https://github.com/connectplatform/ring)) y con el valor predeterminado de **PostgreSQL como base principal** (`DB_BACKEND_MODE=k8s-postgres-fcm`).

Instala Ring en tu máquina para el desarrollo local. **Final-Split:** la app Next.js vive en `web/`. El `install.sh` de la raíz del repo delega en `web/`, o puedes ejecutar `./install.sh` directamente desde `ring/web`.

| Camino | Ideal cuando | Resultado |
|------|-----------|---------|
| **Recomendado: `install.sh`** | Primer clon, estructura white-label | Copia `env.local.template` → `.env.local`, crea `ring-config.json` si falta, genera `AUTH_SECRET` y ejecuta `npm install` |
| **Manual** | Ya gestionas el env y la configuración | Los mismos archivos a mano; cada copia y cada secreto son responsabilidad tuya |

  Instalación completa con Postgres como base principal (la primera vez): unos **45–90 minutos**. `./install.sh --quick` con una instancia de PostgreSQL ya existente suele ser más rápido. Aun así tienes que aplicar el esquema y un proveedor OAuth antes de que el inicio de sesión sirva de algo.

## Qué vas a instalar

| Componente | Entrada verificada |
|-----------|----------------|
| **Framework** | Next.js 16 App Router + React 19 |
| **Autenticación** | Auth.js v5 (`auth.ts`, `AUTH_SECRET`, proveedores OAuth) |
| **Plano de datos predeterminado** | PostgreSQL mediante `DB_BACKEND_MODE=k8s-postgres-fcm` (env obligatorio, sin valor predeterminado silencioso) |
| **Servidor de desarrollo** | `server.ts` propio: Next.js + túnel WebSocket nativo (`/api/tunnel/ws`) cuando hay autoalojamiento |
| **Configuración white-label** | `ring-config.json` (Layer1 puede incluir ya los valores de la comunidad; el instalador lo crea desde la plantilla solo si falta) |
| **Instalador** | `install.sh` **v2.2.0** (`SCRIPT_VERSION`), incluye `setup-db` |

```mermaid
flowchart LR
  A[Clonar ring] --> B[install.sh o env manual]
  B --> C[PostgreSQL + esquema]
  C --> D[Auth + ring-config]
  D --> E[npm run dev]
  E --> F[localhost:3000]
```

### For founders

## Por qué importa para tu clon

Estás levantando un **clon de desarrollo** para que las partes interesadas puedan recorrer la marca, la autenticación y los flujos principales del marketplace antes del alojamiento de producción.

  
- **[Requisitos previos](/docs/getting-started/prerequisites.md)** — Node 20+, Git, Postgres, puertos. Confírmalos antes de clonar

  
- **[Migraciones de base de datos](/docs/getting-started/migrations.md)** — Aplica `data/schema.sql` y el orden de las migraciones del reino

  
- **[Selección del backend de base de datos](/docs/customization/database-selection.md)** — `k8s-postgres-fcm` frente a `supabase-fcm` frente a `firebase-full`

  
- **[Validación del primer éxito](/docs/getting-started/first-success.md)** — Lista de prueba rápida después de `npm run dev`

### Escenarios típicos

| Escenario | Opción de instalación | Para cuando… |
|----------|----------------|------------|
| Explorar la UI / la marca | `./install.sh --quick` + Postgres (o un prototipo corto `firebase-full`) | La página de inicio carga sin errores del adaptador |
| Local con paridad de producción | Postgres como base principal + migraciones | La autenticación y un camino CRUD superan el [Primer éxito](/docs/getting-started/first-success.md) |
| Colono gestionado por Ringdom | Sáltate casi todo esto | El clúster ya está aprovisionado. Personaliza mediante ring-config / ops, no con Docker local |

> **Warning**
> Los pagos, el push FCM y las billeteras Web3 **no** son necesarios para el primer arranque. Añádelos antes del checkout o del push en producción. Consulta [Entorno](/docs/deployment/environment.md).

### For developers

## Camino recomendado: `install.sh`

`install.sh` v2.2.0 prepara el env, el `ring-config.json` opcional, los secretos y las dependencias. Úsalo para un primer clon limpio.

### Requisitos previos

- Node.js **20+** (el instalador falla con versiones mayores anteriores)
- Git y, más adelante, PostgreSQL 14+ (se recomienda 16 con Docker / 18 con Homebrew)
- Desde un checkout OSS: la raíz del repo **o** `web/` (Final-Split)

### Pasos

### Clona y ejecuta el instalador

{`git clone https://github.com/connectplatform/ring.git
cd ring
./install.sh --quick
# equivalent Final-Split entry from app root:
# cd ring/web && ./install.sh --quick`}

Flags y modos útiles:

| Flag / modo | Efecto |
|-------------|--------|
| `--quick` | Valores predeterminados no interactivos |
| `--clone-name NAME` | Slug white-label en `ring-config.json` |
| `dev` / `prod` | Modo de configuración explícito |
| `setup-db` | Crea la base de datos y aplica `data/schema.sql` (fuente de verdad aplanada) |
| `--help` | Lista completa de opciones |

### Completa los valores obligatorios de `.env.local`

La plantilla se copia automáticamente. El instalador genera `AUTH_SECRET` cuando `openssl` está disponible. Antes del primer arranque útil, define las variables de la **base de datos** y al menos un proveedor OAuth (consulta [Configurar el entorno](#configurar-el-entorno)).

### Aplica el esquema de PostgreSQL

Usa las pestañas de Docker / servidor existente / monorepo de Ringdom de abajo, o:

{`./install.sh setup-db --clone-name platform --db-name ring_platform`}

Orden incremental completo: [Migraciones de base de datos](/docs/getting-started/migrations.md).

## Camino manual

Úsalo cuando ya controlas los archivos de env o el gestor de paquetes.

### Clona e instala las dependencias

{`git clone https://github.com/connectplatform/ring.git
cd ring/web
npm install`}

  
    
{`npm install`}

  
  
    
{`pnpm install`}

  
  
    
{`yarn install`}

### Crea el entorno y la configuración del clon

{`cp env.local.template .env.local
# Only if ring-config.json is missing:
cp ring-config.template.json ring-config.json
# AUTH_SECRET: match installer behavior:
# openssl rand -base64 32`}

Edita `ring-config.json`: `clone.displayName`, `domains.development` y `features` para tu instancia white-label. Layer1 a menudo ya incluye en el repositorio el `ring-config.json` de la comunidad; no lo sobrescribas a la ligera.

## Preparar PostgreSQL

El desarrollo local al estilo de producción usa la base de datos **`ring_platform`** con el usuario **`ring_user`**. Fuente de verdad del esquema de la app: `data/schema.sql` (familia v4, consulta las filas de `schema_versions` en el volcado).

`DB_BACKEND_MODE` es **obligatorio** (`lib/database/backend-mode-config.ts`). La plataforma espera PostgreSQL cuando su valor es `k8s-postgres-fcm` (el predeterminado de la plantilla). Consulta [Migraciones de base de datos](/docs/getting-started/migrations.md) para el orden de aplicación.

Clon independiente, sin necesidad del monorepo de Ringdom:

{`docker run -d --name ring-postgres-dev \\
  -e POSTGRES_USER=ring_user \\
  -e POSTGRES_PASSWORD=ring_password_2024 \\
  -e POSTGRES_DB=ring_platform \\
  -p 5432:5432 \\
  postgres:16-alpine`}

Aplica el esquema base y después los incrementos del reino (versión abreviada; la matriz completa está en la página de migraciones):

{`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
psql "$DATABASE_URL" -f data/migrations/009_email_crm_jsonb.sql
psql "$DATABASE_URL" -f data/migrations/010_email_crm_tasks_jsonb.sql`}

`001_email_crm_schema.sql` está **obsoleto**. Usa **009 + 010** con JSONB. Los incrementos idempotentes ya integrados en `schema.sql` se explican en [Migraciones](/docs/getting-started/migrations.md).

Apunta `.env.local` a PostgreSQL **14+** (se recomienda 18), crea `ring_platform` y ejecuta los mismos comandos `psql` con tu `DATABASE_URL`.

Desde el checkout del reino Ringdom (varios clones de Ring):

{`docker compose -f docker-compose.dev.yml up -d postgres
# or Homebrew:
brew install postgresql@18 postgis
brew services start postgresql@18
./infrastructure/postgres/bootstrap-brew-dev.sh ring-platform.org`}

El contenedor **`ring-postgres-dev`** + el volumen **`ringdom_postgres_data`** se inicializan mediante `infrastructure/postgres/init/`. Consulta `infrastructure/postgres/init/README.md`.

## Configurar el entorno

Define estos valores en `.env.local` (a partir de `env.local.template`). Los valores mostrados están pensados para desarrollo local. El `NEXT_PUBLIC_BASE_URL` de la plantilla puede apuntar por defecto al portal público; cámbialo para localhost.

### Modo de backend y base de datos

{`DB_BACKEND_MODE=k8s-postgres-fcm
DB_HOST=localhost
DB_PORT=5432
DB_NAME=ring_platform
DB_USER=ring_user
DB_PASSWORD=ring_password_2024
DB_SSL=false`}

Datos de la aplicación en PostgreSQL; Firebase Admin se usa **solo para el push FCM** cuando está configurado. Coincide con la configuración de producción de ring-platform.org.

{`DB_BACKEND_MODE=firebase-full`}

El prototipo más rápido al estilo edge: Firestore guarda los datos de la app. No se recomienda para la profundidad de PaymentConductor, News Kingdom o ERP. Detalles: [Selección de base de datos](/docs/customization/database-selection.md).

{`DB_BACKEND_MODE=supabase-fcm
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key
SUPABASE_SERVICE_KEY=your-service-key`}

PostgreSQL gestionado, con la misma familia de esquema SQL que los clones autoalojados.

### Auth.js y URL

{`AUTH_SECRET=   # openssl rand -base64 32  (installer sets this)
AUTH_GOOGLE_ID=your_google_client_id
AUTH_GOOGLE_SECRET=your_google_client_secret
NEXT_PUBLIC_BASE_URL=http://localhost:3000
NODE_ENV=development`}

En [Google Cloud Console](https://console.cloud.google.com/), añade la URI de redirección autorizada:
`http://localhost:3000/api/auth/callback/google`

### Túnel, FCM e idiomas

{`RING_DEPLOY_TARGET=self-hosted
NEXT_PUBLIC_RING_DEPLOY_TARGET=self-hosted
NEXT_PUBLIC_SUPPORTED_LOCALES=en,uk,ru
NEXT_PUBLIC_DEFAULT_LOCALE=en`}

`npm run dev` ejecuta `node --import tsx server.ts`. En Vercel, define `RING_DEPLOY_TARGET=vercel` para usar solo SSE (sin WSS nativo).

Las claves de FCM (`AUTH_FIREBASE_*`, `NEXT_PUBLIC_FIREBASE_*`) están en `env.local.template` y son **opcionales** para la página de inicio y la autenticación con Postgres como base principal. Pon `AUTH_FIREBASE_PRIVATE_KEY` entre comillas con `\\n` literales; nunca hagas commit de `.env.local`.

## Ejecutar el servidor de desarrollo

### Inicia la app

{`npm run dev`}

Espera líneas de log parecidas a:

```text
> Ready on http://localhost:3000 [self-hosted]
[server] Native WSS attached at /api/tunnel/ws (RING_DEPLOY_TARGET=self-hosted)
```

La primera compilación puede tardar decenas de segundos.

### Abre y haz una prueba rápida

Visita [http://localhost:3000](http://localhost:3000): la página de inicio se renderiza mediante `HomeWrapper` (`components/wrappers/home-wrapper.tsx`) y los archivos de idioma de `locales/{en,uk,ru}/`.

Opcional:

{`npm run type-check
curl -sS http://localhost:3000/api/health | jq .`}

Forma de la respuesta de salud: `app/api/health/route.ts`. `status` es `healthy` | `degraded` | `unhealthy`. Si falta `AUTH_SECRET` → `degraded` y HTTP **503**.

Si la página de inicio carga sin errores del adaptador de base de datos, continúa con la [Validación del primer éxito](/docs/getting-started/first-success.md).

### Mapa de módulos (rutas verificadas)

| Aspecto | Ruta |
|---------|------|
| Instalador | `install.sh` (lanzador en la raíz → `web/install.sh`) |
| Plantilla del env | `env.local.template` |
| Modo de backend | `lib/database/backend-mode-config.ts` |
| Fuente de verdad del esquema | `data/schema.sql` |
| Entrada de desarrollo | `package.json` → `server.ts` |
| WSS del túnel | `server.ts` → `/api/tunnel/ws` |
| Salud | `app/api/health/route.ts` |

## Preguntas frecuentes

### Impacto

#### ¿Funcionará mi clon sin Firebase?

Sí para **navegación + Auth.js + CRUD en Postgres** cuando `DB_BACKEND_MODE=k8s-postgres-fcm`. Las claves de cliente y de Admin de Firebase se necesitan para el **push FCM**, no para la primera carga de la página de inicio.

#### ¿Necesito credenciales de pago el primer día?

No. WayForPay / Stripe vienen después: tras el [Primer éxito](/docs/getting-started/first-success.md) y antes de las demos de checkout.

### Migración

#### ¿Solo el esquema o todas las migraciones del reino?

Instalaciones nuevas: aplica **`data/schema.sql`** y después los incrementos de noticias/pagos/correo según se documenta en [Migraciones](/docs/getting-started/migrations.md). **No** apliques el obsoleto `001_email_crm_schema.sql`.

#### ¿Monorepo de Ringdom o Docker independiente?

El mismo nombre de base de datos de la app (`ring_platform`) y el mismo contrato `DB_*`. El compose del monorepo usa el volumen `ringdom_postgres_data` y los scripts de inicialización de `infrastructure/postgres/init/`.

### Operación

#### ¿El puerto 3000 ya está en uso?

`lsof -ti:3000 | xargs kill` o `PORT=3001 npm run dev`.

#### ¿Falla el inicio de sesión con Google?

Comprueba `AUTH_GOOGLE_*`, la URI de redirección `http://localhost:3000/api/auth/callback/google` y que `AUTH_SECRET` no esté vacío.

#### ¿Errores del túnel en la consola?

Confirma `RING_DEPLOY_TARGET=self-hosted` (y su gemelo público) para el WSS local. En Vercel usa `vercel` / solo SSE.

Más: [Solución de problemas](/docs/getting-started/troubleshooting.md).

## Documentación relacionada

  
- [getting-started/prerequisites](/docs/getting-started/prerequisites.md) — Requisito previo: confirma Node, Postgres y los puertos antes de clonar.

  
- [getting-started/migrations](/docs/getting-started/migrations.md) — Siguiente paso: aplica data/schema.sql y el orden de migraciones del reino después de preparar el env.

  
- [getting-started/first-success](/docs/getting-started/first-success.md) — Siguiente paso: prueba rápida de salud, autenticación y CRUD cuando npm run dev esté en marcha.

  
- [customization/database-selection](/docs/customization/database-selection.md) — En detalle: elige k8s-postgres-fcm, supabase-fcm o firebase-full.

  
- [development/local-setup](/docs/development/local-setup.md) — Mismo flujo: estructura del proyecto y herramientas locales del día a día después de instalar.