Come ospitare autonomamente SimplePDF Copilot

Benjamin André-Micolon

SimplePDF Copilot è un'implementazione di riferimento con licenza MIT per aggiungere una barra laterale di chat IA all'editor SimplePDF. Puoi forkare l'app Copilot, distribuirla nella tua infrastruttura, collegare il tuo fornitore di IA e instradare i documenti completati nel tuo storage.

L'editor SimplePDF in sé rimane un iframe ospitato. Ospitare autonomamente Copilot significa che possiedi l'app di chat, l'instradamento IA, i prompt, gli strumenti e il flusso di storage attorno all'editor.

Questa guida copre il percorso da localhost alla produzione.

Se usi Claude Code, Codex o un altro strumento di codifica agentico, puntalo alla skill fork-and-go. La skill guida l'agente attraverso il fork, la configurazione e il deploy, una domanda alla volta.

Cosa ospiti autonomamente

App di chat Copilot. Gira sulla tua infrastruttura. La controlli tu.
Prompt di sistema e registro degli strumenti. Vivono nel tuo deploy di Copilot. Li controlli tu.
Instradamento IA. Lato server, BYOK del browser o endpoint locale. Lo controlli tu.
Storage dei documenti completati. Storage SimplePDF per impostazione predefinita, o il tuo storage con BYOS. Lo controlli tu quando BYOS è attivo.
Iframe dell'editor SimplePDF. Resta ospitato da SimplePDF.

Prerequisiti

Un piano SimplePDF Pro o superiore. Eseguire Copilot sul tuo dominio richiede white-labeling, controllo programmatico dell'editor e un'origine consentita nella tua dashboard SimplePDF. Senza queste capacità, l'editor si carica solo sull'origine demo ospitata o su http://localhost:3001.
Una chiave di un fornitore di IA, un flusso BYOK o un endpoint locale compatibile con OpenAI. Anthropic, OpenAI, DeepSeek, Google Gemini e Mistral sono integrati di serie.
Un runtime Node 24. Il template di deploy attuale di Copilot usa Node 24 e l'app gira senza modifiche su DigitalOcean App Platform, Cloudflare Containers, Vercel, Render, fly.io, Railway o Docker auto-ospitato.

Passo 1: Esegui la demo in locale

Clona il repository ed esegui la demo contro lo spazio demo SimplePDF condiviso. Per questo passo non è richiesto alcun account SimplePDF.

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

Il dev server gira su http://localhost:3001. Apri la barra laterale della chat, incolla una chiave fornitore o punta a un endpoint locale compatibile con OpenAI come Ollama o LM Studio.

Lo spazio demo consente esattamente una sola origine locale: http://localhost:3001. Qualsiasi altra porta o host verrà rifiutato dall'iframe. Per eseguire sul tuo dominio, prosegui al Passo 2.

Passo 2: Configura il tuo account SimplePDF

Sottoscrivi il piano Pro o superiore. Dalla dashboard SimplePDF:

Copia il tuo companyIdentifier. Questo è il valore che metterai in VITE_SIMPLEPDF_COMPANY_IDENTIFIER.
Aggiungi alla whitelist la tua origine di servizio, ad esempio https://app.example.com. L'iframe si rifiuta di caricarsi su origini non in whitelist.
Facoltativamente, personalizza il tuo brand per rimuovere gli elementi SimplePDF dall'editor.

Passo 3: Distribuisci sul tuo host

Il percorso più rapido è il pulsante di deploy con un clic su DigitalOcean nel README di SimplePDF Copilot. DigitalOcean compila la cartella copilot/ con Node 24 e richiede le variabili d'ambiente.

VITE_SIMPLEPDF_COMPANY_IDENTIFIER (obbligatoria): l'identificatore della tua azienda SimplePDF.
SHARED_API_KEYS (facoltativa): permette di condividere una demo senza chiedere a ciascun visitatore di incollare una chiave fornitore.
REDIS_URL (facoltativa): persiste i contatori di rate limit tra i container.
IP_HASH_SALT (obbligatoria quando REDIS_URL è impostato): sale gli hash IP persistiti.

Per altri target di deploy, inclusi Cloudflare Containers, Vercel, Render, fly.io, Railway e Docker auto-ospitato, segui la sezione altri target di deploy del README.

Una volta distribuito, aggiungi l'origine distribuita, ad esempio https://copilot.example.com, alla whitelist della tua dashboard SimplePDF prima di aprire l'app.

Passo 4: Collega il tuo fornitore di IA

Lo streaming lato server vive in src/routes/api/chat.ts. La selezione del fornitore vive in src/server/language_model.ts. Usa questo percorso quando la tua applicazione possiede la chiave fornitore, i rate limit, i log e la configurazione per tenant.

Per le chiavi fornite dagli utenti, il percorso BYOK diretto dal browser in src/lib/byok/ chiama il fornitore dal browser e bypassa il tuo server. Questa è anche la forma giusta per gli endpoint locali compatibili con OpenAI come Ollama o LM Studio.

Tre percorsi, tre confini di fiducia:

Chiave fornitore lato server. La tua app possiede l'account del fornitore e la policy per tenant. Il traffico IA fluisce attraverso il tuo server fino al fornitore di IA.
BYOK browser. Gli utenti portano la propria chiave fornitore. Il traffico IA fluisce dal browser direttamente al fornitore selezionato, bypassando il tuo server.
Endpoint locale compatibile con OpenAI. Il traffico IA resta sul dispositivo o sulla rete dell'utente. Il browser dialoga con l'endpoint locale; nulla viene inviato a un fornitore di IA terzo.

Passo 5: Instrada le sottomissioni nel tuo storage

Per impostazione predefinita, i documenti completati atterrano nello storage SimplePDF. Con Bring Your Own Storage da Pro in su, i documenti completati vengono caricati direttamente dal browser allo storage che hai configurato usando URL pre-firmati.

Questo cambia il percorso di storage dei documenti completati. Da solo, non controlla quale contesto del documento viene inviato al fornitore di IA configurato. Configura il percorso IA separatamente al Passo 4.

Configurare lo storage:

Passo 6: Verifica la configurazione di produzione

Prima di condividere l'app con gli utenti, verifica l'intero percorso end-to-end:

Apri l'URL di Copilot distribuito dall'origine in whitelist.
Conferma che l'iframe dell'editor SimplePDF si carica senza errori di origine.
Invia un prompt di prova e conferma che venga usato il percorso IA selezionato.
Compila un campo e conferma che il valore appaia nell'editor PDF.
Invia o scarica un documento di prova.
Se BYOS è attivo, conferma che il PDF completato atterri nel tuo storage, non in quello SimplePDF.
Esamina i log per cercare segreti, testo del documento, PHI, PII o altri dati sensibili che non vuoi conservare.

Personalizza il prompt di sistema e gli strumenti

Una volta che Copilot funziona end-to-end sulla tua infrastruttura, il successivo livello di personalizzazione è il prompt di sistema e il registro degli strumenti esposti al modello. Entrambi vivono in src/server/tools.ts. L'interfaccia di chat stessa è src/components/chat_pane.tsx. Le locale sono in src/locales/.

Per tutto il resto, inclusi il fork, la configurazione e l'adattamento di Copilot a una superficie di prodotto non banale, la skill fork-and-go guida un assistente di codifica IA attraverso il lavoro, una decisione alla volta.

Risoluzione dei problemi

L'iframe dell'editor si rifiuta di caricarsi

Verifica che l'origine dell'app genitore sia in whitelist nella dashboard SimplePDF. Lo spazio demo locale consente solo http://localhost:3001.

La demo locale funziona ma la produzione no

Conferma che VITE_SIMPLEPDF_COMPANY_IDENTIFIER usi il tuo identificatore aziendale SimplePDF e che il tuo dominio di produzione sia nell'elenco delle origini consentite.

Agli utenti viene chiesto di incollare una chiave IA

È previsto in modalità BYOK. Per condividere una demo preconfigurata, configura SHARED_API_KEYS e usa il flusso URL ?share=<id>.

I rate limit si reimpostano a ogni deploy

I rate limit in memoria si reimpostano al riavvio dell'app. Usa REDIS_URL e IP_HASH_SALT se i contatori devono persistere tra container o riavvii.

I PDF completati non atterrano nel tuo storage

Conferma che Bring Your Own Storage sia configurato in SimplePDF e prova con un PDF piccolo prima di usare moduli in produzione.

Ecco fatto! La tua app Copilot ora gira sulla tua infrastruttura, usa il percorso IA che hai configurato e può inviare i documenti completati al tuo storage quando BYOS è attivo.

Se hai domande, non esitare a contattarci all'indirizzo support@simplepdf.com