Wie man SimplePDF Copilot selbst hostet

Benjamin André-Micolon

SimplePDF Copilot ist eine MIT-lizenzierte Referenzimplementierung, um eine KI-Chat-Seitenleiste zum SimplePDF-Editor hinzuzufügen. Sie können die Copilot-App forken, in Ihrer eigenen Infrastruktur bereitstellen, Ihren eigenen KI-Anbieter anschließen und fertige Dokumente an Ihren eigenen Speicher leiten.

Der SimplePDF-Editor selbst bleibt eine gehostete iframe. Copilot selbst zu hosten bedeutet, dass Sie die Chat-App, das KI-Routing, die Prompts, die Tools und den Speicherfluss rund um den Editor besitzen.

Diese Anleitung deckt den Weg von localhost bis zur Produktion ab.

Wenn Sie Claude Code, Codex oder ein anderes agentisches Coding-Tool verwenden, richten Sie es auf die Fork-and-Go-Skill aus. Die Skill führt den Agenten Frage für Frage durch Fork, Konfiguration und Bereitstellung.

Was Sie selbst hosten

Copilot-Chat-App. Läuft auf Ihrer Infrastruktur. Sie kontrollieren sie.
System-Prompt und Tool-Registry. Liegen in Ihrer Copilot-Bereitstellung. Sie kontrollieren sie.
KI-Routing. Serverseitig, BYOK im Browser oder lokaler Endpunkt. Sie kontrollieren es.
Speicher fertiger Dokumente. Standardmäßig SimplePDF-Speicher, oder Ihr Speicher mit BYOS. Sie kontrollieren ihn, wenn BYOS aktiviert ist.
SimplePDF-Editor-iframe. Bleibt von SimplePDF gehostet.

Voraussetzungen

Ein SimplePDF Pro-Plan oder höher. Copilot auf Ihrer eigenen Domain zu betreiben erfordert White-Labeling, programmatische Editor-Steuerung und eine zugelassene Origin in Ihrem SimplePDF-Dashboard. Ohne diese Funktionen lädt der Editor nur auf der gehosteten Demo-Origin oder auf http://localhost:3001.
Ein KI-Anbieter-Schlüssel, ein BYOK-Flow oder ein lokaler OpenAI-kompatibler Endpunkt. Anthropic, OpenAI, DeepSeek, Google Gemini und Mistral sind ab Werk eingebunden.
Eine Node 24-Laufzeitumgebung. Das aktuelle Copilot-Bereitstellungstemplate verwendet Node 24, und die App läuft unverändert auf DigitalOcean App Platform, Cloudflare Containers, Vercel, Render, fly.io, Railway oder selbst gehostetem Docker.

Schritt 1: Die Demo lokal starten

Klonen Sie das Repository und führen Sie die Demo gegen den geteilten SimplePDF-Demo-Workspace aus. Für diesen Schritt ist kein SimplePDF-Konto erforderlich.

git clone https://github.com/SimplePDF/simplepdf-embed.git
cd simplepdf-embed/copilot
npm install
cp .env.example .env
printf "\nVITE_SIMPLEPDF_COMPANY_IDENTIFIER=spdf-copilot\n" >> .env
npm run dev

Der Dev-Server läuft auf http://localhost:3001. Öffnen Sie die Chat-Seitenleiste, fügen Sie einen Anbieter-Schlüssel ein oder zeigen Sie auf einen lokalen OpenAI-kompatiblen Endpunkt wie Ollama oder LM Studio.

Der Demo-Workspace lässt genau eine lokale Origin zu: http://localhost:3001. Jeder andere Port oder Host wird vom iframe abgelehnt. Um auf Ihrer eigenen Domain zu laufen, fahren Sie mit Schritt 2 fort.

Schritt 2: Ihr SimplePDF-Konto einrichten

Schließen Sie ein Pro-Abonnement oder höher ab. Vom SimplePDF-Dashboard aus:

Kopieren Sie Ihren companyIdentifier. Dies ist der Wert, den Sie in VITE_SIMPLEPDF_COMPANY_IDENTIFIER eintragen.
Setzen Sie Ihre Servier-Origin auf die Whitelist, zum Beispiel https://app.example.com. Der iframe weigert sich, auf Origins zu laden, die nicht auf der Whitelist stehen.
Optional: passen Sie Ihre Marke an, um SimplePDF-Elemente aus dem Editor zu entfernen.

Schritt 3: Auf Ihrem Host bereitstellen

Der schnellste Weg ist die Ein-Klick-DigitalOcean-Deploy-Schaltfläche im SimplePDF Copilot-README. DigitalOcean baut den Ordner copilot/ mit Node 24 und fragt nach den Umgebungsvariablen.

VITE_SIMPLEPDF_COMPANY_IDENTIFIER (erforderlich): Ihr SimplePDF-Unternehmens-Identifier.
SHARED_API_KEYS (optional): erlaubt das Teilen einer Demo, ohne dass jeder Besucher einen Anbieter-Schlüssel einfügen muss.
REDIS_URL (optional): speichert Rate-Limit-Zähler containerübergreifend.
IP_HASH_SALT (erforderlich, wenn REDIS_URL gesetzt ist): Salt für persistierte IP-Hashes.

Für andere Bereitstellungsziele, einschließlich Cloudflare Containers, Vercel, Render, fly.io, Railway und selbst gehostetes Docker, folgen Sie dem Abschnitt Andere Bereitstellungsziele der README.

Sobald die App bereitgestellt ist, fügen Sie die bereitgestellte Origin, zum Beispiel https://copilot.example.com, zur Whitelist Ihres SimplePDF-Dashboards hinzu, bevor Sie die App öffnen.

Schritt 4: Ihren KI-Anbieter verdrahten

Das serverseitige Streaming liegt in src/routes/api/chat.ts. Die Anbieterauswahl liegt in src/server/language_model.ts. Verwenden Sie diesen Pfad, wenn Ihre Anwendung den Anbieter-Schlüssel, Rate-Limits, Logs und die Mandantenkonfiguration besitzt.

Für vom Nutzer bereitgestellte Schlüssel ruft der Browser-direkte BYOK-Pfad in src/lib/byok/ den Anbieter aus dem Browser auf und umgeht Ihren Server. Dies ist auch die richtige Form für lokale OpenAI-kompatible Endpunkte wie Ollama oder LM Studio.

Drei Pfade, drei Vertrauensgrenzen:

Serverseitiger Anbieter-Schlüssel. Ihre App besitzt das Anbieter-Konto und die Mandantenrichtlinie. Der KI-Verkehr fließt über Ihren Server zum KI-Anbieter.
Browser-BYOK. Nutzer bringen ihren eigenen Anbieter-Schlüssel mit. Der KI-Verkehr fließt vom Browser direkt an den ausgewählten Anbieter und umgeht Ihren Server.
Lokaler OpenAI-kompatibler Endpunkt. Der KI-Verkehr bleibt auf dem Gerät oder im Netzwerk des Nutzers. Der Browser kommuniziert mit dem lokalen Endpunkt; nichts geht an einen Drittanbieter-KI.

Schritt 5: Einreichungen an Ihren eigenen Speicher leiten

Standardmäßig landen fertige Dokumente im SimplePDF-Speicher. Mit Bring Your Own Storage ab Pro werden fertige Dokumente direkt vom Browser über vorsignierte URLs in Ihren konfigurierten Speicher hochgeladen.

Dies ändert den Speicherpfad für fertige Dokumente. Es kontrolliert für sich genommen nicht, welcher Dokumentkontext an Ihren konfigurierten KI-Anbieter gesendet wird. Konfigurieren Sie den KI-Pfad separat in Schritt 4.

Speicher konfigurieren:

Schritt 6: Die Produktionseinrichtung verifizieren

Bevor Sie die App mit Nutzern teilen, verifizieren Sie den vollständigen Pfad von Anfang bis Ende:

Öffnen Sie die bereitgestellte Copilot-URL von der Origin auf der Whitelist aus.
Bestätigen Sie, dass die SimplePDF-Editor-iframe ohne Origin-Fehler lädt.
Senden Sie einen Test-Prompt und bestätigen Sie, dass der ausgewählte KI-Pfad verwendet wird.
Füllen Sie ein Feld aus und bestätigen Sie, dass der Wert im PDF-Editor erscheint.
Reichen Sie ein Testdokument ein oder laden Sie es herunter.
Wenn BYOS aktiviert ist, bestätigen Sie, dass das fertige PDF in Ihrem Speicher und nicht im SimplePDF-Speicher landet.
Prüfen Sie die Logs auf Geheimnisse, Dokumenttext, PHI, PII oder andere sensible Daten, die Sie nicht persistieren möchten.

System-Prompt und Tools anpassen

Sobald Copilot durchgehend auf Ihrer Infrastruktur läuft, ist die nächste Anpassungsschicht der System-Prompt und die Tool-Registry, die dem Modell zur Verfügung steht. Beide liegen in src/server/tools.ts. Die Chat-Oberfläche selbst ist src/components/chat_pane.tsx. Locales liegen in src/locales/.

Für alles andere, einschließlich Forken, Konfigurieren und Anpassen von Copilot an eine nicht-triviale Produktoberfläche, führt die Fork-and-Go-Skill einen KI-Coding-Assistenten durch die Arbeit, eine Entscheidung nach der anderen.

Fehlerbehebung

Die Editor-iframe weigert sich zu laden

Prüfen Sie, ob die Origin der übergeordneten App im SimplePDF-Dashboard auf der Whitelist steht. Der lokale Demo-Workspace erlaubt nur http://localhost:3001.

Die lokale Demo funktioniert, die Produktion aber nicht

Bestätigen Sie, dass VITE_SIMPLEPDF_COMPANY_IDENTIFIER Ihren eigenen SimplePDF-Unternehmens-Identifier verwendet und dass Ihre Produktionsdomain in der Liste der erlaubten Origins steht.

Nutzer werden aufgefordert, einen KI-Schlüssel einzufügen

Das ist im BYOK-Modus erwartet. Um eine vorkonfigurierte Demo zu teilen, konfigurieren Sie SHARED_API_KEYS und verwenden Sie den URL-Flow ?share=<id>.

Rate-Limits werden bei jedem Deployment zurückgesetzt

In-Memory-Rate-Limits werden beim Neustart der App zurückgesetzt. Verwenden Sie REDIS_URL und IP_HASH_SALT, wenn die Zähler containerübergreifend oder über Neustarts hinweg persistieren sollen.

Fertige PDFs landen nicht in Ihrem Speicher

Bestätigen Sie, dass Bring Your Own Storage in SimplePDF konfiguriert ist, und testen Sie mit einem kleinen PDF, bevor Sie produktive Formulare verwenden.

Das war's! Ihre Copilot-App läuft jetzt auf Ihrer Infrastruktur, nutzt den von Ihnen konfigurierten KI-Pfad und kann fertige Dokumente an Ihren Speicher senden, sobald BYOS aktiviert ist.

Wenn Sie Fragen haben, wenden Sie sich gerne an support@simplepdf.com