---
title: "Installation"
description: "Ring Platform lokal installieren: klonen, install.sh oder manuelles Env, Backend mit PostgreSQL als Primärdatenbank, Auth.js v5, Schema und der vereinheitlichte eigene Server"
locale: "de"
---
# Installation

> **Info**
> Nutze die Tabs **Gründer** / **Entwickler** in der Seitenleiste, um diese Seite zu filtern. Erledige zuerst die [Voraussetzungen](/docs/getting-started/prerequisites.md). Diese Anleitung entspricht dem Open-Source-Repo ([connectplatform/ring](https://github.com/connectplatform/ring)) und dem Standard **PostgreSQL als Primärdatenbank** (`DB_BACKEND_MODE=k8s-postgres-fcm`).

Installiere Ring für die lokale Entwicklung auf deinem Rechner. **Final-Split:** Die Next.js-App liegt unter `web/`. Das `install.sh` im Repo-Root delegiert an `web/`, oder du führst `./install.sh` direkt in `ring/web` aus.

| Weg | Am besten, wenn | Ergebnis |
|------|-----------|---------|
| **Empfohlen: `install.sh`** | Erster Klon, White-Label-Gerüst | Kopiert `env.local.template` → `.env.local`, legt `ring-config.json` an, falls es fehlt, erzeugt `AUTH_SECRET` und führt `npm install` aus |
| **Manuell** | Du verwaltest Env und Konfiguration bereits | Dieselben Dateien von Hand; jede Kopie und jedes Secret liegt bei dir |

  Vollständige Installation mit Postgres als Primärdatenbank (beim ersten Mal): etwa **45–90 Minuten**. `./install.sh --quick` mit einer vorhandenen PostgreSQL-Instanz geht meist schneller. Schema und einen OAuth-Anbieter musst du trotzdem anwenden, bevor die Anmeldung sinnvoll funktioniert.

## Was du installierst

| Komponente | Geprüfter Einstieg |
|-----------|----------------|
| **Framework** | Next.js 16 App Router + React 19 |
| **Authentifizierung** | Auth.js v5 (`auth.ts`, `AUTH_SECRET`, OAuth-Anbieter) |
| **Standard-Datenebene** | PostgreSQL über `DB_BACKEND_MODE=k8s-postgres-fcm` (verpflichtendes Env, kein stiller Standardwert) |
| **Entwicklungsserver** | Eigener `server.ts`: Next.js + nativer WebSocket-Tunnel (`/api/tunnel/ws`) beim Self-Hosting |
| **White-Label-Konfiguration** | `ring-config.json` (Layer1 liefert eventuell schon Community-Standardwerte; der Installer legt die Datei nur aus der Vorlage an, wenn sie fehlt) |
| **Installer** | `install.sh` **v2.2.0** (`SCRIPT_VERSION`), enthält `setup-db` |

```mermaid
flowchart LR
  A[ring klonen] --> B[install.sh oder manuelles Env]
  B --> C[PostgreSQL + Schema]
  C --> D[Auth + ring-config]
  D --> E[npm run dev]
  E --> F[localhost:3000]
```

### For founders

## Warum das für deinen Klon wichtig ist

Du setzt einen **Entwicklungsklon** auf, damit Stakeholder Branding, Authentifizierung und die zentralen Marketplace-Abläufe durchklicken können, bevor es ein Produktions-Hosting gibt.

  
- **[Voraussetzungen](/docs/getting-started/prerequisites.md)** — Node 20+, Git, Postgres, Ports. Vor dem Klonen prüfen

  
- **[Datenbankmigrationen](/docs/getting-started/migrations.md)** — `data/schema.sql` und die Reihenfolge der Kingdom-Migrationen anwenden

  
- **[Auswahl des Datenbank-Backends](/docs/customization/database-selection.md)** — `k8s-postgres-fcm` oder `supabase-fcm` oder `firebase-full`

  
- **[Validierung des ersten Erfolgs](/docs/getting-started/first-success.md)** — Smoke-Test-Checkliste nach `npm run dev`

### Typische Szenarien

| Szenario | Installationswahl | Fertig, wenn… |
|----------|----------------|------------|
| UI / Branding erkunden | `./install.sh --quick` + Postgres (oder ein kurzer Prototyp mit `firebase-full`) | Die Startseite lädt ohne Adapterfehler |
| Lokal mit Produktionsparität | Postgres als Primärdatenbank + Migrationen | Authentifizierung und ein CRUD-Weg bestehen den [Ersten Erfolg](/docs/getting-started/first-success.md) |
| Von Ringdom verwalteter Siedler | Das meiste hiervon überspringen | Der Cluster ist bereits bereitgestellt. Anpassung über ring-config / Ops, nicht über lokales Docker |

> **Warning**
> Zahlungen, FCM-Push und Web3-Wallets sind für den ersten Start **nicht** nötig. Ergänze sie vor dem Checkout oder vor Push in Produktion. Siehe [Umgebung](/docs/deployment/environment.md).

### For developers

## Empfohlener Weg: `install.sh`

`install.sh` v2.2.0 legt Env, optionales `ring-config.json`, Secrets und Abhängigkeiten an. Für einen sauberen ersten Klon ist das der bevorzugte Weg.

### Voraussetzungen

- Node.js **20+** (der Installer bricht bei älteren Hauptversionen ab)
- Git und später PostgreSQL 14+ (empfohlen: 16 mit Docker / 18 mit Homebrew)
- Aus einem OSS-Checkout: Repo-Root **oder** `web/` (Final-Split)

### Schritte

### Klonen und den Installer ausführen

{`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`}

Nützliche Flags und Modi:

| Flag / Modus | Wirkung |
|-------------|--------|
| `--quick` | Nicht interaktive Standardwerte |
| `--clone-name NAME` | White-Label-Slug in `ring-config.json` |
| `dev` / `prod` | Expliziter Setup-Modus |
| `setup-db` | Datenbank anlegen und `data/schema.sql` anwenden (zusammengeführte Referenz) |
| `--help` | Vollständige Optionsliste |

### Pflichtwerte in `.env.local` ergänzen

Die Vorlage wird automatisch kopiert. Der Installer erzeugt `AUTH_SECRET`, wenn `openssl` verfügbar ist. Setze vor dem ersten sinnvollen Start die **Datenbank**-Variablen und mindestens einen OAuth-Anbieter (siehe [Umgebung konfigurieren](#umgebung-konfigurieren)).

### PostgreSQL-Schema anwenden

Nutze die Tabs Docker / vorhandener Server / Ringdom-Monorepo unten oder:

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

Vollständige inkrementelle Reihenfolge: [Datenbankmigrationen](/docs/getting-started/migrations.md).

## Manueller Weg

Für den Fall, dass du Env-Dateien oder den Paketmanager bereits selbst steuerst.

### Klonen und Abhängigkeiten installieren

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

  
    
{`npm install`}

  
  
    
{`pnpm install`}

  
  
    
{`yarn install`}

### Umgebung und Klon-Konfiguration anlegen

{`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`}

Bearbeite `ring-config.json`: `clone.displayName`, `domains.development` und `features` für deine White-Label-Instanz. Layer1 committet oft bereits ein Community-`ring-config.json`; überschreibe es nicht leichtfertig.

## PostgreSQL einrichten

Lokale Entwicklung im Produktionsstil nutzt die Datenbank **`ring_platform`** mit dem Benutzer **`ring_user`**. Referenz für das App-Schema: `data/schema.sql` (v4-Familie, siehe die Zeilen in `schema_versions` im Dump).

`DB_BACKEND_MODE` ist **verpflichtend** (`lib/database/backend-mode-config.ts`). Die Plattform erwartet PostgreSQL, wenn der Wert `k8s-postgres-fcm` ist (Standard der Vorlage). Zur Reihenfolge siehe [Datenbankmigrationen](/docs/getting-started/migrations.md).

Eigenständiger Klon, kein Ringdom-Monorepo nötig:

{`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`}

Basisschema anwenden, danach die Kingdom-Inkremente (gekürzt; die vollständige Matrix steht auf der Seite zu den Migrationen):

{`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` ist **veraltet**. Nutze **009 + 010** mit JSONB. Idempotente Inkremente, die bereits in `schema.sql` eingeflossen sind, behandelt die Seite [Migrationen](/docs/getting-started/migrations.md).

Richte `.env.local` auf PostgreSQL **14+** aus (18 empfohlen), lege `ring_platform` an und führe dann dieselben `psql`-Befehle mit deiner `DATABASE_URL` aus.

Aus dem Kingdom-Checkout von Ringdom (mehrere Ring-Klone):

{`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`}

Der Container **`ring-postgres-dev`** + das Volume **`ringdom_postgres_data`** werden über `infrastructure/postgres/init/` initialisiert. Siehe `infrastructure/postgres/init/README.md`.

## Umgebung konfigurieren

Setze diese Werte in `.env.local` (aus `env.local.template`). Die gezeigten Werte sind auf lokale Entwicklung ausgerichtet. `NEXT_PUBLIC_BASE_URL` in der Vorlage zeigt eventuell standardmäßig auf das öffentliche Portal; überschreibe den Wert für localhost.

### Backend-Modus und Datenbank

{`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`}

Anwendungsdaten in PostgreSQL; Firebase Admin wird **nur für FCM-Push** genutzt, wenn konfiguriert. Entspricht der Produktionsaufstellung von ring-platform.org.

{`DB_BACKEND_MODE=firebase-full`}

Schnellster Prototyp im Edge-Stil: Firestore hält die App-Daten. Nicht empfohlen für die Tiefe von PaymentConductor, News Kingdom oder ERP. Details: [Datenbankauswahl](/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`}

Verwaltetes PostgreSQL mit derselben SQL-Schema-Familie wie selbst gehostete Klone.

### Auth.js und URLs

{`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`}

Füge in der [Google Cloud Console](https://console.cloud.google.com/) die autorisierte Weiterleitungs-URI hinzu:
`http://localhost:3000/api/auth/callback/google`

### Tunnel, FCM, Sprachen

{`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` führt `node --import tsx server.ts` aus. Setze auf Vercel `RING_DEPLOY_TARGET=vercel` für reines SSE (ohne natives WSS).

FCM-Schlüssel (`AUTH_FIREBASE_*`, `NEXT_PUBLIC_FIREBASE_*`) stehen in `env.local.template` und sind für Startseite und Authentifizierung mit Postgres als Primärdatenbank **optional**. Setze `AUTH_FIREBASE_PRIVATE_KEY` in Anführungszeichen mit literalen `\\n`; committe `.env.local` niemals.

## Den Entwicklungsserver starten

### Die App starten

{`npm run dev`}

Erwartet werden Logzeilen wie diese:

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

Die erste Kompilierung kann einige Dutzend Sekunden dauern.

### Öffnen und Smoke-Test

Öffne [http://localhost:3000](http://localhost:3000): Die Startseite wird über `HomeWrapper` (`components/wrappers/home-wrapper.tsx`) und die Sprachdateien unter `locales/{en,uk,ru}/` gerendert.

Optional:

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

Struktur der Health-Antwort: `app/api/health/route.ts`. `status` ist `healthy` | `degraded` | `unhealthy`. Fehlendes `AUTH_SECRET` → `degraded` und HTTP **503**.

Wenn die Startseite ohne Fehler des Datenbankadapters lädt, mach weiter mit der [Validierung des ersten Erfolgs](/docs/getting-started/first-success.md).

### Modulübersicht (geprüfte Pfade)

| Thema | Pfad |
|---------|------|
| Installer | `install.sh` (Launcher im Root → `web/install.sh`) |
| Env-Vorlage | `env.local.template` |
| Backend-Modus | `lib/database/backend-mode-config.ts` |
| Schema-Referenz | `data/schema.sql` |
| Einstieg für die Entwicklung | `package.json` → `server.ts` |
| Tunnel-WSS | `server.ts` → `/api/tunnel/ws` |
| Health | `app/api/health/route.ts` |

## Häufige Fragen

### Auswirkungen

#### Funktioniert mein Klon ohne Firebase?

Ja für **Browsen + Auth.js + CRUD in Postgres**, wenn `DB_BACKEND_MODE=k8s-postgres-fcm` gesetzt ist. Client- und Admin-Schlüssel von Firebase werden für **FCM-Push** gebraucht, nicht für das erste Laden der Startseite.

#### Brauche ich am ersten Tag Zugangsdaten für Zahlungen?

Nein. WayForPay / Stripe kommen später: nach dem [Ersten Erfolg](/docs/getting-started/first-success.md) und vor Checkout-Demos.

### Migration

#### Nur das Schema oder alle Kingdom-Migrationen?

Frische Installationen: Wende **`data/schema.sql`** an und danach die Inkremente für News/Zahlungen/E-Mail, wie unter [Migrationen](/docs/getting-started/migrations.md) beschrieben. Wende das veraltete `001_email_crm_schema.sql` **nicht** an.

#### Ringdom-Monorepo oder eigenständiges Docker?

Gleicher Datenbankname der App (`ring_platform`) und gleicher `DB_*`-Vertrag. Das Compose des Monorepos nutzt das Volume `ringdom_postgres_data` und Init-Skripte unter `infrastructure/postgres/init/`.

### Betrieb

#### Port 3000 ist schon belegt?

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

#### Die Google-Anmeldung schlägt fehl?

Prüfe `AUTH_GOOGLE_*`, die Weiterleitungs-URI `http://localhost:3000/api/auth/callback/google` und ein nicht leeres `AUTH_SECRET`.

#### Tunnel-Fehler in der Konsole?

Prüfe `RING_DEPLOY_TARGET=self-hosted` (und das öffentliche Gegenstück) für lokales WSS. Auf Vercel nutzt du `vercel` / nur SSE.

Mehr: [Fehlerbehebung](/docs/getting-started/troubleshooting.md).

## Verwandte Dokumentation

  
- [getting-started/prerequisites](/docs/getting-started/prerequisites.md) — Voraussetzung: Node, Postgres und Ports vor dem Klonen prüfen.

  
- [getting-started/migrations](/docs/getting-started/migrations.md) — Nächster Schritt: data/schema.sql und die Reihenfolge der Kingdom-Migrationen nach dem Env-Gerüst anwenden.

  
- [getting-started/first-success](/docs/getting-started/first-success.md) — Nächster Schritt: Smoke-Test für Health, Authentifizierung und CRUD, sobald npm run dev läuft.

  
- [customization/database-selection](/docs/customization/database-selection.md) — Vertiefung: zwischen k8s-postgres-fcm, supabase-fcm und firebase-full wählen.

  
- [development/local-setup](/docs/development/local-setup.md) — Gleicher Ablauf: Projektstruktur und lokale Werkzeuge für den Alltag nach der Installation.