Selbst-Hosting LightCMS
DeployLeitfaden zum Selbst-Host von LightCMS, die GitHub App, PostgreSQL, Umgebungsvariablen, optionale AI, CDN und E-Mail abdecken und in Kanten bereitstellen.
Möchten Sie LightCMS voll unter Ihrer Kontrolle? LightCMS ist eine SvelteKit Anwendung, so dass sie überall eingesetzt werden kann, unterstützt von einer PostgreSQL Datenbank und einer GitHub App (Octokit). Dein Inhalt hinterlässt niemals deine eigenen GitHub Repositories.
Diese Anleitung führt Sie durch alles, was Sie benötigen, um Ihre eigene Instanz auszuführen: Erstellen der GitHub App, Bereitstellung von PostgreSQL, Konfigurieren von Umgebungsvariablen und Bereitstellen.
Wie die Teile zusammen passen
| Komponente | Zweck | Benötigt |
|---|---|---|
| PostgreSQL | Speichert Benutzer, Sitzungen, Passkeys und GitHub Installationen | Ja |
| GitHub App | Liest und schreibt Inhalte in deinen Repositories und signiert Benutzer mit GitHub | Ja |
| SMTP-Anbieter | Sendet Magic-Link-Anmeldemails | Ja, für Magic-Link-Anmeldung |
| OpenAI-kompatible API | Macht den KI Copilot | Optional |
| Sprach-zu-Text API | Diktation der Mächte | Optional |
| Bild CDN | Hosts Bilder im Editor hochgeladen | Optional |
| PostHog | Produktanalytik und KI-Beobachtung | Nur in der Entwicklung erforderlich |
Voraussetzungen
- mise: Installiert und verwaltet Aufgabenabhängigkeiten. Diese Anleitung setzt voraus, dass Sie sie installiert haben.
- PostgreSQL: eine Datenbank, die TLS-Verbindungen akzeptiert. Cloud-Anbieter wie Neon, Supabase oder Nile funktionieren gut. Siehe awesome-free-postgres für kostenlose Optionen.
- GitHub Konto: erforderlich, um die GitHub App zu registrieren.
- SMTP-Provider (für magische Links): Wenn Sie eine Domain haben, Erneutes Senden ist eine gute Option. Andernfalls verwenden Sie Zoho Mail und erstellen Sie ein App-Passwort.
TLS ist obligatorisch. Die Anwendung verbindet sich mit PostgreSQL mit
ssl: "require". Eine lokale PostgreSQL-Instanz ohne TLS aktiviert wird abgelehnt, also verwenden Sie eine gehostete Datenbank oder konfigurieren Sie TLS auf Ihrem eigenen Server.
1. Fork das Repository und installiere Abhängigkeiten
Repository klonen und Abhängigkeiten installieren:
cd lightcms
mise trust
mise deps
mise run install2. Create the GitHub App
LightCMS verwendet eine GitHub App für zwei Dinge: die Anmeldung von Benutzern mit GitHub (OAuth) und das Handeln in deinem Namen durch Installationen. Sie können es mit dem eingebauten Probot Installationsassistenten oder von Hand erstellen.
Option A: Probot Einrichtungsassistent
starte den Bot mit:
mise run BotOhne Anmeldedaten in .envstartet Probot einen Setup-Server unter http://localhost:3000:
- Öffnen Sie
http://localhost:3000und klicken Sie auf GitHub App registrieren. - Wählen Sie Ihr persönliches Konto oder eine Organisation.
- Bestätigen. Probot erstellt die App und schreibt ihre Anmeldedaten in Ihre
.envDatei.
Der Assistent setzt die URL der App auf einen Smee Channel (oder http://localhost:3000/), nicht auf den Webhook von LightCMS Endpunkt. Aktualisieren Sie es in den GitHub App-Einstellungen bevor Sie live gehen (siehe Production deployment).
Option B: Manuelles Setup
Erstelle die App in GitHub Einstellungen → Entwicklereinstellungen → GitHub Apps → Neue GitHub App mit diesen Werten:
| Einstellung | Wert |
|---|---|
| Homepage URL | https://<your-domain> |
| Callback URL | https://<your-domain>/api/auth/callback/github |
| Setup URL | https://<your-domain>/github/setup |
| Webhook-URL | https://<your-domain>/api/github/webhook |
| Webhook Geheimnis | A random secret (see Generating secrets) |
Repository-Berechtigungen
| Berechtigung | Zugang | Verwendet für |
|---|---|---|
Inhalt |
Lesen und schreiben | Dateien lesen und übertragen |
Probleme |
Lesen und schreiben | Kommentare und Beschriftungen bei Pull-Requests überprüfen |
Pull-Request |
Nur lesen | Liste der geänderten Dateien in einem Pull-Request |
Commit-Status |
Lesen und schreiben | Inhaltsüberprüfung bei Pushes melden |
Metadaten |
Nur lesen | Pflichtfeld für jede GitHub App |
Veranstaltungen abonnieren: Push und Pull Request. Installationsereignisse werden automatisch an GitHub Apps ausgeliefert.
Nach dem Erstellen der App beachten Sie die App ID, erzeugen Sie ein Client-Geheimnis, und generieren und laden Sie einen privaten Schlüssel (. em).
3. Umgebungsvariablen konfigurieren
Erstellen Sie eine .env Datei im Projektstamm. Das Projektarchiv liefert keine verwendbare Beispieldatei. Verwenden Sie daher die nachfolgende Referenz .
Benötigt
# ---------------------------------------------------------------------------
# Authentifizierung (Better Auth)
# ---------------------------------------------------------------------------
BETTER_AUTH_SECRET="<output of: openssl rand -hex 32>"
# Public URL of this instance. Muss mit dem Besuch von URL-Benutzern übereinstimmen.
BETTER_AUTH_URL="http://localhost:5173"
# ---------------------------------------------------------------------------
# Datenbank (PostgreSQL, TLS erforderlich)
# ---------------------------------------------------------------------------
DATABASE_URL="postgresql://user:password@host:5432/lightcms? slmode=require"
# ---------------------------------------------------------------------------
# GitHub App
# -----------------------------------------------------------
GITHUB_APP_ID="123456"
GITHUB_CLIENT_ID="Iv1. xxxxxxxxx"
GITHUB_CLIENT_SECRET="<github-app-client-secret>"
GITHUB_WEBHOOK_SECRET="<webhook-secret>"
GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...
-----ENDE RSA PRIVATE KEY-----"GITHUB_PRIVATE_KEY ist der vollständige PEM-Inhalt. Behalte die Zeilenumbrüche und wickele den Wert in doppelte Anführungszeichen. So schreibt der Probot-Assistent.
Für die Entwicklung erforderlich
LightCMS meldet Analysen und Fehler an PostHog. Wenn die Schlüssel fehlen, wird die App in der Entwicklung geworfen um zu verhindern, dass Ereignisse stillschweigend gelöscht werden. In der Produktion sind sie optional, und die Telemetrie wird übersprungen, wenn sie nicht gesetzt sind.
VITE_POSTHOG_PROJECT_TOKEN="phc_xxxxxxxx"
VITE_POSTHOG_HOST="https://us.i.posthog.com"E-Mail: erforderlich für Magic-Link-Anmeldung
Magic Links werden über SMTP mit Nodemailer versendet. Senden fehlgeschlagen mit einem Konfigurationsfehler, wenn MAIL_HOST, MAIL_USER, MAIL_PASS oder MAIL_FROM fehlt.
MAIL_HOST="smtp.resend.com"
# Standardwerte 587, wenn
MAIL_PORT="465"
# "true", "1", "yes" oder "on" aktiviert implizites TLS. Wird TLS weggelassen, ist nur für Port 465 aktiviert.
MAIL_SECURE="1"
MAIL_USER="Weitersenden"
MAIL_PASS="<smtp-password-or-api-key>"
MAIL_FROM="LightCMS <[email protected]>"Optional: KI Copilot
Das Copilot verwendet jede OpenAI-kompatible Chat-Vervollständigungs-API. Alle drei Variablen werden benötigt, damit es funktioniert.
OPEN_AI_ENDPOINT="https://api.openai.com/v1"
OPEN_AI_APIKEY="sk-..."
Öffne AI_MODEL="gpt-4o-mini"Jeder Provider, der eine OpenAI-kompatible API aufdeckt, arbeitet zum Beispiel OpenAI, OpenRouter (https://openrouter. i/api/v1) oder NVIDIA NIM.
Optional: Sprach-zu-Text Diktation
LightCMS unterstützt zwei Transkriptions-Backends. Wenn beide konfiguriert sind, wird das OpenAI-kompatible Backend verwendet.
OpenAI-kompatible Transkription. Wird ausgewählt, wenn SPEECH_API_KEY gesetzt ist und benötigt auch SPEECH_MODEL:
SPEECH_API_KEY="<api-key>"
SPEECH_MODEL="Whisper-1"
# Basis-URL des Anbieters. Erlaube es den OpenAI Standard zu verwenden.
SPEECH_ENDPOINT="https://api.openai.com/v1"Punkt SPEECH_ENDPOINT auf jeden Provider, der die /Audio/Transkriptionen API implementiert und setzen Sie SPEECH_MODEL auf ein -Modell, das der Anbieter anbietet. Ein / Audio/Transkriptionen am Endpunkt wird automatisch entfernt.
Wit.ai wird verwendet, wenn SPEECH_API_KEY nicht gesetzt ist:
Mit AI_TOKEN="<wit-ai-server-access-token>"Wenn keiner der beiden konfiguriert ist, ist Diktation nicht verfügbar.
Optional: Bild-Uploads (CDN)
Im Editor eingefügte oder hochgeladene Bilder werden an eine Chevereto-kompatible Upload-API gesendet. Die Hosted-Optionen beinhalten FreeImage.host und ImgBBoder Sie können Ihre eigene Chevereto-Instanz ausführen.
CDN_URL="https://freeimage.host/api/1/upload"
CDN_KEY="<cdn-api-key>"CDN_KEY wird als Schlüssel Abfrageparameter gesendet, es sei denn, CDN_URL enthält bereits einen. Wenn der Upload fehlgeschlagen ist oder die Variablen nicht gesetzt sind LightCMS fällt zurück auf die Einbettung des Bildes in das Dokument als Base64 Daten: URL. Dies funktioniert, , aber es macht Ihre Markdown-Dateien viel größer, so konfigurieren Sie eine CDN für den echten Gebrauch.
Lokale Webhook-Weiterleitung (nur Entwicklung)
WEBHOOK_PROXY_URL="https://smee.io/<your-channel>"Dies wird von Probot gelesen und nicht von der SvelteKit App. Siehe Webhooks lokal testen.
Generiere Geheimnisse
Verwenden Sie eine dieser Funktionen, um BETTER_AUTH_SECRET und GITHUB_WEBHOOK_SECRET zu generieren:
openssl rand -hex 32
# oder
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"4. Datenbank einrichten
LightCMS verwendet Drizzle ORM. Das Schema lebt in src/lib/server/db/schema.tsund Migrationen werden in das Verzeichnis drizzle generiert. Mit DATABASE_URL setzen Sie die Migrationen:
bun run db:migrateWährend der lokalen Entwicklung können Sie stattdessen das Schema direkt in die Datenbank schieben, ohne Migrationsdateien:
bun ausführen db:pushAndere Datenbank-Skripte:
| Befehl | Beschreibung |
|---|---|
bun ausführen db:generate |
Eine Migration nach dem Bearbeiten des Schemas generieren |
bun ausführen db:studio |
Durchsuchen und bearbeiten Sie Ihre Daten in Drizzle Studio |
5. Lokal ausführen
bun run dev

LightCMS ist ab sofort unter http://localhost:5173 verfügbar. Setze BETTER_AUTH_URL auf diese Adresse und melde dich zum ersten Mal mit GitHub an.
Webhooks lokal testen
GitHub kann Webhooks nicht an localhostübergeben, also leiten Sie sie über smee.io weiter:
Erstelle einen Kanal unter smee.io und kopiere seine URL.
Setze
WEBHOOK_PROXY_URLin.envauf diese URL.Legen Sie die Webhook URL in den GitHub App-Einstellungen auf die gleiche URL.
Den Bot in einem zweiten Terminal ausführen:
bun run bot:start
Der Bot registriert die gleichen Handler wie der Produktionsendpunkt: Inhaltsvalidierung auf Push, überprüfen Sie die Kommentare und Beschriftungen auf pull_requestund Installation Protokollierung.
6. Produktionseinsatz
Das Projekt wird mit SvelteKit konfiguriert, einem Verkäufer, der agnostisch ist. Vercel, Netlify und Cloudflare Arbeiter werden alle mit Bereitstellungsziele außerhalb der Box unterstützt.
- Importieren Sie Ihr Git-Repository in die Bereitstellungsplattform.
- Fügen Sie jede Umgebungsvariable aus Schritt 3 in Projekteinstellungen → Umwelt Variablen hinzu. Setze
BETTER_AUTH_URLauf deine Produktions-URL. - Deploy.
Um die Produktion lokal zu überprüfen:
bun run build
bun run VorschauFehlerbehebung
Erstellen Sie ein Konto mit Wit.ai es ist ein kostenloser Service durch die Meta | und jede Openai-kompatible API für die Transkription. | Man kann groq oder Assemblyai oder | elvenlabs oder deepgram oder sarvam verwenden. |
PostHog Zugangsdaten
Verwenden Sie das Projekt-Token von Ihrem eigenen PostHog Projekt (Projekteinstellungen → Project API Key). Verwenden Sie kein Token aus dieser Dokumentation: Ereignisse, die mit einem freigegebenen Token Land in einem anderen Projekt gesendet werden damit seine Einsichten, Warnungen und Benachrichtigungen nicht zu lesen sind.
VITE_POSTHOG_PROJECT_TOKEN=phc_your_project_token
VITE_POSTHOG_HOST=https://us.i.posthog.com
WIT_AI_TOKEN="Server-Zugangs-Token"
WIT_AI_CLIENT_TOKEN="Client Zugangs-Token"APP_ID=
BETTER_AUTH_SECRET=
BETTER_AUTH_URL=
CDN_KEY=
CDN_URL=
DATABASE_URL=
GITHUB_APP_ID=
GITHUB_APP_NAME=
GITHUB_CLIENT_ID=
GITHUB_CLIENT_SECRET=
GITHUB_PRIVATE_KEY=
GITHUB_WEBHOOK_SECRET=
MAIL_FROM=
MAIL_HOST=
MAIL_PASS=
MAIL_PORT=
MAIL_SECURE=
MAIL_USER=
OPEN_AI_ENDPOINT=
OPEN_AI_MODEL=
OPEN_AI_APIKEY=
ORIGIN=
PRIVATE_KEY=
VITE_POSTHOG_HOST=
VITE_POSTHOG_PROJECT_TOKEN=
SPEECH_API_KEY=
SPEECH_ENDPOINT=
SPEECH_MODEL=
WEBHOOK_SECRET=
WIT_AI_CLIENT_TOKEN=
WIT_AI_TOKEN=