Hoe SimplePDF Copilot zelf hosten

Benjamin André-Micolon

SimplePDF Copilot is een MIT-gelicentieerde referentie-implementatie om een AI-chatzijbalk toe te voegen aan de SimplePDF-editor. U kunt de Copilot-app forken, deze in uw eigen infrastructuur uitrollen, uw eigen AI-aanbieder aansluiten en voltooide documenten naar uw eigen opslag routeren.

De SimplePDF-editor zelf blijft een gehoste iframe. Copilot zelf hosten betekent dat u eigenaar bent van de chat-app, het AI-routing, de prompts, de tools en de opslagflow rond de editor.

Deze gids beschrijft het pad van localhost naar productie.

Als u Claude Code, Codex of een andere agentische codeertool gebruikt, wijs deze dan naar de fork-and-go skill. De skill begeleidt de agent door de fork, de configuratie en de uitrol, vraag voor vraag.

Wat u zelf host

Copilot-chat-app. Draait op uw infrastructuur. U beheert deze.
Systeem-prompt en tool-register. Bevinden zich in uw Copilot-uitrol. U beheert ze.
AI-routing. Server-side, BYOK in de browser of lokaal eindpunt. U beheert deze.
Opslag van voltooide documenten. Standaard SimplePDF-opslag, of uw opslag met BYOS. U beheert deze wanneer BYOS is ingeschakeld.
SimplePDF-editor-iframe. Blijft gehost door SimplePDF.

Vereisten

Een SimplePDF Pro-abonnement of hoger. Copilot op uw eigen domein draaien vereist white-labeling, programmatische besturing van de editor en een toegestane origin in uw SimplePDF-dashboard. Zonder die mogelijkheden laadt de editor alleen op de gehoste demo-origin of op http://localhost:3001.
Een sleutel van een AI-aanbieder, een BYOK-flow of een lokaal OpenAI-compatibel eindpunt. Anthropic, OpenAI, DeepSeek, Google Gemini en Mistral zijn standaard ingebouwd.
Een Node 24-runtime. De huidige Copilot-uitroltemplate gebruikt Node 24 en de app draait ongewijzigd op DigitalOcean App Platform, Cloudflare Containers, Vercel, Render, fly.io, Railway of zelf gehoste Docker.

Stap 1: Voer de demo lokaal uit

Kloon de repository en voer de demo uit tegen de gedeelde SimplePDF-demoworkspace. Voor deze stap is geen SimplePDF-account vereist.

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

De dev server draait op http://localhost:3001. Open de chatzijbalk, plak een aanbiedersleutel of wijs naar een lokaal OpenAI-compatibel eindpunt zoals Ollama of LM Studio.

De demoworkspace staat precies één lokale origin toe: http://localhost:3001. Elke andere poort of host wordt door de iframe geweigerd. Om op uw eigen domein te draaien, gaat u verder naar Stap 2.

Stap 2: Stel uw SimplePDF-account in

Schrijf u in voor het Pro-abonnement of hoger. Vanuit het SimplePDF-dashboard:

Kopieer uw companyIdentifier. Dit is de waarde die u in VITE_SIMPLEPDF_COMPANY_IDENTIFIER zet.
Plaats uw serveer-origin op de whitelist, bijvoorbeeld https://app.example.com. De iframe weigert te laden op origins die niet op de whitelist staan.
Optioneel: pas uw huisstijl aan om SimplePDF-elementen uit de editor te verwijderen.

Stap 3: Implementeer op uw host

Het snelste pad is de DigitalOcean een-klik-implementatieknop in de SimplePDF Copilot README. DigitalOcean bouwt de map copilot/ met Node 24 en vraagt om de omgevingsvariabelen.

VITE_SIMPLEPDF_COMPANY_IDENTIFIER (vereist): uw SimplePDF-bedrijfsidentificatie.
SHARED_API_KEYS (optioneel): maakt het mogelijk een demo te delen zonder elke bezoeker een aanbiedersleutel te laten plakken.
REDIS_URL (optioneel): persisteert rate-limit-tellers tussen containers.
IP_HASH_SALT (vereist wanneer REDIS_URL is ingesteld): salt voor gepersisteerde IP-hashes.

Voor andere implementatiedoelen, waaronder Cloudflare Containers, Vercel, Render, fly.io, Railway en zelf gehoste Docker, volgt u de sectie andere implementatiedoelen van de README.

Zodra de app is geïmplementeerd, voegt u de geïmplementeerde origin, bijvoorbeeld https://copilot.example.com, toe aan de whitelist van uw SimplePDF-dashboard voordat u de app opent.

Stap 4: Sluit uw AI-aanbieder aan

Server-side streaming bevindt zich in src/routes/api/chat.ts. De aanbiederselectie bevindt zich in src/server/language_model.ts. Gebruik dit pad wanneer uw applicatie de aanbiedersleutel, rate limits, logs en tenantconfiguratie bezit.

Voor door de gebruiker aangeleverde sleutels roept het direct-vanuit-de-browser BYOK-pad in src/lib/byok/ de aanbieder vanuit de browser aan en omzeilt het uw server. Dit is ook de juiste vorm voor lokale OpenAI-compatibele eindpunten zoals Ollama of LM Studio.

Drie routes, drie vertrouwensgrenzen:

Serverzijdige aanbiedersleutel. Uw app bezit het aanbiederaccount en het tenantbeleid. AI-verkeer loopt via uw server naar de AI-aanbieder.
BYOK in de browser. Gebruikers nemen hun eigen aanbiedersleutel mee. AI-verkeer loopt vanuit de browser rechtstreeks naar de geselecteerde aanbieder en omzeilt uw server.
Lokaal OpenAI-compatibel eindpunt. AI-verkeer blijft op het apparaat of netwerk van de gebruiker. De browser communiceert met het lokale eindpunt; er gaat niets naar een externe AI-aanbieder.

Stap 5: Routeer inzendingen naar uw eigen opslag

Standaard belanden voltooide documenten in de SimplePDF-opslag. Met Bring Your Own Storage vanaf Pro worden voltooide documenten rechtstreeks vanuit de browser geüpload naar uw geconfigureerde opslag via vooraf ondertekende URL's.

Dit verandert het opslagpad voor voltooide documenten. Het bepaalt op zichzelf niet welke documentcontext naar uw geconfigureerde AI-aanbieder wordt gestuurd. Configureer de AI-route apart in Stap 4.

Opslag configureren:

Stap 6: Verifieer de productie-opzet

Voordat u de app met gebruikers deelt, verifieert u het volledige pad van begin tot eind:

Open de uitgerolde Copilot-URL vanuit de origin op de whitelist.
Bevestig dat de SimplePDF-editor-iframe laadt zonder origin-fouten.
Stuur een testprompt en bevestig dat de geselecteerde AI-route wordt gebruikt.
Vul een veld in en bevestig dat de waarde in de PDF-editor verschijnt.
Dien een testdocument in of download het.
Als BYOS is ingeschakeld, bevestig dan dat de voltooide PDF in uw opslag belandt en niet in de SimplePDF-opslag.
Controleer de logs op geheimen, documenttekst, PHI, PII of andere gevoelige gegevens die u niet wilt persisteren.

Pas de systeem-prompt en tools aan

Zodra Copilot end-to-end op uw infrastructuur draait, is de volgende laag van aanpassing de systeem-prompt en het toolregister dat aan het model wordt blootgesteld. Beide bevinden zich in src/server/tools.ts. De chat-UI zelf is src/components/chat_pane.tsx. Locales staan in src/locales/.

Voor al het andere, waaronder forken, configureren en Copilot aanpassen aan een niet-triviaal productoppervlak, leidt de fork-and-go skill een AI-codeerassistent door het werk, één beslissing tegelijk.

Probleemoplossing

De editor-iframe weigert te laden

Controleer of de origin van de bovenliggende app op de whitelist staat in het SimplePDF-dashboard. De lokale demoworkspace staat alleen http://localhost:3001 toe.

De lokale demo werkt maar productie niet

Bevestig dat VITE_SIMPLEPDF_COMPANY_IDENTIFIER uw eigen SimplePDF-bedrijfsidentificatie gebruikt en dat uw productiedomein in de lijst met toegestane origins staat.

Gebruikers wordt gevraagd een AI-sleutel te plakken

Dat is verwacht in BYOK-modus. Om een vooraf geconfigureerde demo te delen, configureer SHARED_API_KEYS en gebruik de URL-flow ?share=<id>.

Rate limits worden bij elke uitrol gereset

In-memory rate limits worden gereset wanneer de app opnieuw start. Gebruik REDIS_URL en IP_HASH_SALT als tellers tussen containers of herstarts moeten persisteren.

Voltooide PDF's belanden niet in uw opslag

Bevestig dat Bring Your Own Storage is geconfigureerd in SimplePDF en test met een kleine PDF voordat u productieformulieren gebruikt.

Dat is het! Uw Copilot-app draait nu op uw infrastructuur, gebruikt de door u geconfigureerde AI-route en kan voltooide documenten naar uw opslag sturen wanneer BYOS is ingeschakeld.

Als u vragen heeft, neem dan gerust contact op via support@simplepdf.com