Multi-Mode: ein Admin, viele Websites

Multi-Mode ist die Variante für Agenturen und Multi-Tenant-Setups: ein Setzkasten-Admin verwaltet mehrere Website-Repos über ein zentrales Config-Repo. Pro Website gilt ein eigener Branch, eigene App-Installation und eigene Editoren-Liste.

Voraussetzungen

• Pro- oder Enterprise-Lizenz (Free unterstützt nur Single-Mode)
• GitHub App mit Lese-/Schreibrechten auf contents für alle verwalteten Repos und das Config-Repo
• Eigenes Hosting für den Standalone-Admin (siehe Standalone-Deployment)

Konfiguration

Multi-Mode wird durch storage.kind: 'multi' aktiviert. Der Admin liest anschließend die Liste der verwalteten Websites aus dem Config-Repo.

// setzkasten.config.ts
import { defineConfig } from '@setzkasten-cms/core'

export default defineConfig({
  storage: {
    kind: 'multi',
    configRepo: 'meine-agentur/setzkasten-config',
    configBranch: 'main',
    appId: process.env.GITHUB_APP_ID!,
    installationId: process.env.GITHUB_APP_INSTALLATION_ID!,
  },
  auth: {
    providers: ['github'],
  },
})

websites.json im Config-Repo

Diese Datei steuert, welche Websites im Admin auswählbar sind. Sie kann per Hand gepflegt werden — oder Admins legen Einträge im Admin selbst über Settings → Websites an.

// websites.json (im Config-Repo)
{
  "websites": [
    {
      "id": "kunde-a",
      "name": "Kunde A — Website",
      "repo": "kunde-a/website",
      "branch": "main",
      "previewOrigin": "https://kunde-a.de",
      "githubApp": {
        "appId": "123456",
        "installationId": "111"
      },
      "allowedEmails": ["redakteur-a@example.com"]
    },
    {
      "id": "kunde-b",
      "name": "Kunde B — Landingpage",
      "repo": "kunde-b/landing",
      "branch": "main",
      "previewOrigin": "https://kunde-b.com",
      "githubApp": {
        "appId": "123456",
        "installationId": "222"
      },
      "allowedEmails": ["redakteur-b@example.com"]
    }
  ]
}

Lizenz-Limits

• Pro: bis zu 5 Websites in websites.json
• Enterprise: bis zu 20 Websites
• Free: Multi-Mode nicht verfügbar

Der Admin lehnt POSTs auf /websites/add mit 402 ab, sobald das Limit erreicht ist. Siehe Lizenz & Updates für Details.

Environment-Variablen

Die App-Credentials liegen ausschließlich in den Server-ENVs des Admin-Deployments — nicht in setzkasten.config.ts.

# Standalone-Admin Deployment (.env / Vercel / Netlify)
GITHUB_APP_ID=123456
GITHUB_APP_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n…"
GITHUB_APP_INSTALLATION_ID=111   # Installation für das Config-Repo
SETZKASTEN_LICENSE_EMAIL=du@example.com
SETZKASTEN_LICENSE_KEY=SK-PRO-XXXXXXXX-XXXXXXXX-XXXXXXXX

Migration aus Single-Mode

Wer schon im Single-Mode läuft, kann mit dem Migrations-Wizard ohne Downtime auf Multi-Mode wechseln. Der bestehende Single-Mode-Admin bleibt funktionsfähig, bis der Wizard final committet.