Self Hosting LightCMS
DispiegaGuida all'autohost LightCMS, che copre l'app GitHub, PostgreSQL, le variabili d'ambiente, l'API opzionale, il CDN e l'e-mail e la distribuzione sul bordo.
Vuoi LightCMS completamente sotto il tuo controllo? LightCMS è un'applicazione SvelteKit , quindi può essere distribuita ovunque, supportata da un database PostgreSQL e da un'App GitHub (Octokit). Il tuo contenuto non lascia mai i tuoi repository GitHub.
Questa guida ti guida attraverso tutto ciò che ti serve per eseguire la tua istanza: creare l'app GitHub, il provisioning PostgreSQL, la configurazione delle variabili di ambiente e la distribuzione.
Come i Pezzi si adattano insieme
| Componente | Scopo | Richiesto |
|---|---|---|
| PostgreSQL | Memorizza installazioni di utenti, sessioni, passkey e GitHub | Sì |
| GitHub App | Legge e scrive contenuti nei tuoi repository e firma gli utenti con GitHub | Sì |
| Provider SMTP | Invia email di accesso al link magico | Sì, per l'accesso al link magico |
| API OpenAI-compatible | Potenzia il Copilot AI | Facoltativo |
| Api Speech-to-Text | Potenzia dettatura vocale | Facoltativo |
| Immagine CDN | Immagini host caricate nell'editor | Facoltativo |
| PostHog | Analisi del prodotto e osservabilità dell'IA | Richiesto solo in sviluppo |
Prerequisiti
- mise: installa e gestisce le dipendenze delle attività. Questa guida presuppone che l'hai installata.
- PostgreSQL: un database che accetta connessioni TLS. I provider cloud come Neon, Supabase o Nile funzionano bene. Vedi awesome-free-postgres per le opzioni gratuite.
- account GitHub: necessario per registrare l'app GitHub.
- SMTP provider (per link magici): Se hai un dominio, Reinvia è una buona opzione. Altrimenti, usa Zoho Mail e crea una password per l'app.
TLS è obbligatorio. L'applicazione si collega a PostgreSQL con
ssl: "require". Un'istanza locale PostgreSQL senza TLS abilitata sarà rifiutata, quindi usa un database ospitato o configura TLS sul tuo server.
1. Fork the Repository and Install Dependencies
Clona il repository e installa le dipendenze:
cd lightcms
mise trust
mise deps
mise run install2. Create the GitHub App
LightCMS utilizza un'applicazione GitHub per due cose: firma gli utenti con GitHub (OAuth) e agisce per tuo conto attraverso le installazioni. È possibile crearlo con la procedura guidata di configurazione del robot, o a mano.
Opzione A: Configurazione guidata del robot,
avviare il bot con:
dise run botSenza credenziali in .env, Probot avvia un server di configurazione su http://localhost:3000:
- Apri
http://localhost:3000e clicca Registra GitHub App. - Scegli il tuo account personale o un'organizzazione.
- Conferma. Probot crea l'app e scrive le sue credenziali sul tuo file
.env.
La procedura guidata imposta l'URL del webhook dell'app a un canale Smee (o http://localhost:3000/), non all'endpoint del webhook di LightCMS. Aggiornarlo nelle impostazioni dell'app GitHub prima di andare in diretta (vedi distribuzione produzione).
Opzione B: Configurazione manuale
Crea l'app in Impostazioni GitHub → Impostazioni sviluppatore → App GitHub → Nuova App GitHub con questi valori:
| Impostazione | Valore |
|---|---|
| Url Della Homepage | ● ://<your-domain> |
| Callback URL | https://<your-domain>/api/auth/callback/github |
| Setup URL | ● ://<your-domain>/github/setup |
| Url Webhook | ● ://<your-domain>/api/github/webhook |
| Webhook segreto | Un segreto casuale (vedi Generare segreti) |
Autorizzazioni repository
| Permesso | Accesso | Utilizzato per |
|---|---|---|
Contenuti |
Leggi e scrivi | Lettura e commit di file di contenuto |
Problemi |
Leggi e scrivi | Rivedere commenti ed etichette sulle richieste pull |
Richieste di prelievo |
Sola Lettura | Elencando i file modificati in una pull request |
Stato di commit |
Leggi e scrivi | Validazione del contenuto di segnalazione su pushes |
Metadati |
Sola Lettura | Obbligatorio per ogni app GitHub |
Iscriviti agli eventi: Push e Pull request. Gli eventi di installazione vengono consegnati automaticamente alle app GitHub.
Dopo aver creato l'app, nota l' App ID, genera un client secret, e genera e scarica una chiave privata **** (. em).
3. Configura le variabili d'ambiente
Crea un file .env nella radice del progetto. Il repository non fornisce un file di esempio utilizzabile, quindi usa il riferimento qui sotto.
Richiesto
# ---------------------------------------------------------------------------
# Authentication (Better Auth)
# -------------------------------------------------------------------
BETTER_AUTH_SECRET="<output of: openssl rand -hex 32>"
# Public URL di questa istanza. Deve corrispondere alla visita degli utenti URL.
BETTER_AUTH_URL="http://localhost:5173"
# -----------------------------------------------------------
# Database (PostgreSQL, TLS richiesto)
# -----------------------------------------------------------------------------------
DATABASE_URL="postgresql://user:password@host:5432/lightcms? slmode=require"
# -------------------------------------------------------------------
# GitHub App
# -----------------------------------------------------------------------------------
GITHUB_APP_ID="123456"
GITHUB_CLIENT_ID="Iv1. xxxxxxxxxxx"
GITHUB_CLIENT_SECRET="<github-app-client-secret>"
GITHUB_WEBHOOK_SECRET="<webhook-secret>"
GITHUB_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
...
-----END RSA PRIVATE KEY-----"GITHUB_PRIVATE_KEY è il contenuto completo di PEM. Mantieni le interruzioni di riga e avvolgi il valore in virgolette doppie, che è come la procedura guidata del Probot lo scrive.
Richiesto per lo sviluppo
LightCMS segnala analisi ed errori a PostHog. Quando i tasti sono mancanti, l'app lancia nello sviluppo per fermare gli eventi in silenzio. In produzione sono facoltativi, e la telemetria viene saltata quando vengono disattivati.
VITE_POSTHOG_PROJECT_TOKEN="phc_xxxxxxxxxxxx"
VITE_POSTHOG_HOST="https://us.i.posthog.com"Email: richiesto per l'accesso al link magico
I link magici vengono inviati tramite SMTP con Nodemailer. L'invio fallisce con un errore di configurazione quando MAIL_HOST, MAIL_USER, MAIL_PASS o MAIL_FROM è mancante.
MAIL_HOST="smtp.resend.com"
# Predefinito a 587 quando omesso
MAIL_PORT="465"
# "true", "1", "sì" o "on" abilita TLS implicito. Quando omesso, TLS è abilitato solo per la porta 465.
MAIL_SECURE="1"
MAIL_USER="resend"
MAIL_PASS="<smtp-password-or-api-key>"
MAIL_FROM="LightCMS <[email protected]>"Facoltativo: Ai Copilot
Copilot utilizza qualsiasi API di chat compatibile con OpenAI. Tutte e tre le variabili sono necessarie per funzionare.
OPEN_AI_ENDPOINT="https://api.openai.com/v1"
OPEN_AI_APIKEY="sk-..."
OPEN_AI_MODEL="gpt-4o-mini"Qualsiasi provider che espone un API compatibile con OpenAI, funziona, ad esempio OpenAI, OpenRouter (https://openrouter. i/api/v1o NVIDIA NIM.
Facoltativo: dettatura vocale al testo
LightCMS supporta due backend di trascrizione. Quando entrambi sono configurati, viene utilizzato il backend compatibile con OpenAI.
Trascrizione compatibile con OpenAI. È selezionata quando SPEECH_API_KEY è impostata e necessita anche di SPEECH_MODEL:
SPEECH_API_KEY="<api-key>"
SPEECH_MODEL="whisper-1"
# URL di base del provider. Omettere di utilizzare il valore predefinito di OpenAI.
SPEECH_ENDPOINT="https://api.openai.com/v1"Punto SPEECH_ENDPOINT presso qualsiasi provider che implementa l'API /audio/trascrizioni , e imposta SPEECH_MODEL a un modello che il provider offre. Un trailing /audio/trascrizioni nell'endpoint viene spogliato automaticamente.
Wit.ai viene utilizzato quando SPEECH_API_KEY non è impostato:
WIT_AI_TOKEN="<wit-ai-server-access-token>"Se nessuno è configurato, la dettatura non è disponibile.
Opzionale: upload di immagini (CDN)
Le immagini incollate o caricate nell'editor vengono inviate a un'API di caricamento compatibile con Chevereto. Le opzioni ospitate includono FreeImage.host e ImgBB, oppure puoi eseguire la tua istanza Chevereto.
CDN_URL="https://freeimage.host/api/1/upload"
CDN_KEY="<cdn-api-key>"CDN_KEY viene inviato come parametro di query key a meno che CDN_URL non ne contenga già uno. Se il caricamento fallisce o le variabili sono disattivate, LightCMS torna a incorporare l'immagine nel documento come base64 dati: URL. Questo funziona, ma rende i tuoi file Markdown molto più grandi, quindi configurare un CDN per un uso reale.
Inoltro Webhook Locale (Solo Sviluppo)
WEBHOOK_PROXY_URL="https://smee.io/<your-channel>"Questo è letto da Probot, non dall'app SvelteKit. Vedi Testing webhooks localmente.
Generazione di segreti
Utilizzare uno di questi per generare BETTER_AUTH_SECRET e GITHUB_WEBHOOK_SECRET:
openssl rand -hex 32
# o
node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"4. Configura il database
LightCMS utilizza Drizzle ORM. Lo schema vive in src/lib/server/db/schema.tse le migrazioni sono generate nella directory drizzle. Con DATABASE_URL impostato, applicare le migrazioni:
bun run db:migrateDurante lo sviluppo locale è possibile invece premere lo schema diritto al database, senza file di migrazione:
bun run db:pushAltri script del database:
| Comando | Descrizione |
|---|---|
bun run db:generate |
Genera una migrazione dopo aver modificato lo schema |
bun run db:studio |
Sfoglia e modifica i tuoi dati in Drizzle Studio |
5. Esegui localmente
bun run dev

LightCMS è ora disponibile su http://localhost:5173. Imposta BETTER_AUTH_URL a questo indirizzo e accedi con GitHub per la prima volta.
Testare webhooks localmente
GitHub non può consegnare webhooks a localhost, quindi inoltrarli attraverso smee.io:
Crea un canale su smee.io e copia il suo URL.
Imposta
WEBHOOK_PROXY_URLin.enva quell'URL.Impostare l'URL Webhook nelle impostazioni dell'app GitHub sullo stesso URL.
Esegui il bot in un secondo terminale:
bun run bot:start
Il bot registra gli stessi gestori dell'endpoint di produzione: convalida del contenuto su push, recensione commenti e etichette su pull_request, e installazione di registrazione.
6. Dispiegamento della produzione
Il progetto è configurato con SvelteKit, che è fornitore agnostico. Vercel, Netlify e Cloudflare Workers sono tutti obiettivi di distribuzione supportati fuori dalla casella.
- Importa il tuo repository Git nella piattaforma di distribuzione.
- Aggiungi ogni variabile d'ambiente dalla fase 3 nelle impostazioni del progetto → Ambiente Variabili. Imposta
BETTER_AUTH_URLal tuo URL di produzione. - Deploy.
Per verificare la produzione costruire localmente:
bun run build
bun run previewRisoluzione Dei Problemi
Crea un account con Wit.ai è un servizio gratuito di meta <unk> E qualsiasi API openai compatibile per la trascrizione. <unk> Si può utilizzare groq o assemblyai o <unk> elevenlabs o deepgram o sarvam. |
Credenziali PostHog
Usa il token del progetto il tuo progetto PostHog (Impostazioni del progetto → Chiave API del progetto). Non riutilizzare un token da questa documentazione: eventi inviati con un token land condiviso nel progetto di qualcun altro, così le sue intuizioni, avvisi e le notifiche non sono le tue da leggere.
VITE_POSTHOG_PROJECT_TOKEN=phc_your_project_token
VITE_POSTHOG_HOST=https://us.i.posthog.com
WIT_AI_TOKEN="Token di accesso al server"
WIT_AI_CLIENT_TOKEN="Token di accesso al cliente"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=