Comment auto-héberger SimplePDF Copilot

Benjamin André-Micolon

SimplePDF Copilot est une implémentation de référence sous licence MIT pour ajouter une barre latérale de chat IA à l'éditeur SimplePDF. Vous pouvez forker l'application Copilot, la déployer sur votre propre infrastructure, brancher votre propre fournisseur d'IA et router les documents complétés vers votre propre stockage.

L'éditeur SimplePDF lui-même reste une iframe hébergée. Auto-héberger Copilot signifie que vous possédez l'application de chat, le routage IA, les prompts, les outils et le flux de stockage autour de l'éditeur.

Ce guide couvre le chemin de localhost à la production.

Si vous utilisez Claude Code, Codex ou un autre outil de codage agentique, pointez-le vers la compétence fork-and-go. La compétence guide l'agent à travers le fork, la configuration et le déploiement, une question à la fois.

Ce que vous auto-hébergez

Application de chat Copilot. Tourne sur votre infrastructure. Vous la contrôlez.
Prompt système et registre d'outils. Vivent dans votre déploiement Copilot. Vous les contrôlez.
Routage IA. Côté serveur, BYOK navigateur ou endpoint local. Vous le contrôlez.
Stockage des documents complétés. Stockage SimplePDF par défaut, ou votre stockage avec BYOS. Vous le contrôlez quand BYOS est activé.
Iframe de l'éditeur SimplePDF. Reste hébergée par SimplePDF.

Prérequis

Un forfait SimplePDF Pro ou supérieur. Faire tourner Copilot sur votre propre domaine nécessite le white-labeling, le contrôle programmatique de l'éditeur et une origine autorisée dans votre tableau de bord SimplePDF. Sans ces capacités, l'éditeur ne se charge que sur l'origine de démo hébergée ou sur http://localhost:3001.
Une clé de fournisseur d'IA, un flux BYOK ou un endpoint local compatible OpenAI. Anthropic, OpenAI, DeepSeek, Google Gemini et Mistral sont prêts à l'emploi.
Un runtime Node 24. Le template de déploiement actuel de Copilot utilise Node 24 et l'application tourne sans modification sur DigitalOcean App Platform, Cloudflare Containers, Vercel, Render, fly.io, Railway ou Docker auto-hébergé.

Étape 1 : Lancer la démo en local

Clonez le dépôt et lancez la démo contre l'espace de démo SimplePDF partagé. Aucun compte SimplePDF n'est requis pour cette étape.

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

Le serveur de développement tourne sur http://localhost:3001. Ouvrez la barre latérale de chat, collez une clé de fournisseur ou pointez vers un endpoint local compatible OpenAI tel qu'Ollama ou LM Studio.

L'espace de démo accepte exactement une seule origine locale : http://localhost:3001. Tout autre port ou hôte sera refusé par l'iframe. Pour fonctionner sur votre propre domaine, passez à l'étape 2.

Étape 2 : Configurer votre compte SimplePDF

Souscrivez au forfait Pro ou supérieur. Depuis le tableau de bord SimplePDF :

Copiez votre companyIdentifier. C'est la valeur que vous mettrez dans VITE_SIMPLEPDF_COMPANY_IDENTIFIER.
Ajoutez votre origine de service à la liste blanche, par exemple https://app.example.com. L'iframe refuse de se charger sur des origines qui ne sont pas en liste blanche.
Optionnellement, personnalisez votre marque pour retirer l'habillage SimplePDF de l'éditeur.

Étape 3 : Déployer sur votre hôte

Le chemin le plus rapide est le bouton de déploiement DigitalOcean en un clic dans le README de SimplePDF Copilot. DigitalOcean construit le dossier copilot/ avec Node 24 et demande les variables d'environnement.

VITE_SIMPLEPDF_COMPANY_IDENTIFIER (obligatoire) : votre identifiant d'entreprise SimplePDF.
SHARED_API_KEYS (facultatif) : permet de partager une démo sans demander à chaque visiteur de coller une clé fournisseur.
REDIS_URL (facultatif) : persiste les compteurs de limitation de débit entre les conteneurs.
IP_HASH_SALT (obligatoire quand REDIS_URL est défini) : sale les hachages d'IP persistés.

Pour les autres cibles de déploiement, y compris Cloudflare Containers, Vercel, Render, fly.io, Railway et Docker auto-hébergé, suivez la section autres cibles de déploiement du README.

Une fois déployé, ajoutez l'origine déployée, par exemple https://copilot.example.com, à la liste blanche de votre tableau de bord SimplePDF avant d'ouvrir l'application.

Étape 4 : Brancher votre fournisseur d'IA

Le streaming côté serveur se trouve dans src/routes/api/chat.ts. La sélection du fournisseur se trouve dans src/server/language_model.ts. Utilisez ce chemin lorsque votre application possède la clé fournisseur, les limites de débit, les logs et la configuration par locataire.

Pour les clés fournies par les utilisateurs, le chemin BYOK direct depuis le navigateur dans src/lib/byok/ appelle le fournisseur depuis le navigateur et contourne votre serveur. C'est aussi la bonne forme pour les endpoints locaux compatibles OpenAI tels qu'Ollama ou LM Studio.

Trois chemins, trois frontières de confiance :

Clé fournisseur côté serveur. Votre application possède le compte fournisseur et la politique par locataire. Le trafic IA passe par votre serveur jusqu'au fournisseur d'IA.
BYOK navigateur. Les utilisateurs apportent leur propre clé fournisseur. Le trafic IA part du navigateur directement vers le fournisseur sélectionné, en contournant votre serveur.
Endpoint local compatible OpenAI. Le trafic IA reste sur l'appareil ou le réseau de l'utilisateur. Le navigateur dialogue avec l'endpoint local ; rien ne va vers un fournisseur d'IA tiers.

Étape 5 : Router les soumissions vers votre propre stockage

Par défaut, les documents complétés atterrissent dans le stockage SimplePDF. Avec Bring Your Own Storage à partir de Pro, les documents complétés sont téléversés directement du navigateur vers le stockage que vous avez configuré, via des URL pré-signées.

Cela modifie le chemin de stockage des documents complétés. Cela ne contrôle pas, à soi seul, ce que le contexte du document envoie au fournisseur d'IA que vous avez configuré. Configurez le chemin IA séparément à l'étape 4.

Configurer le stockage :

Étape 6 : Vérifier la mise en place en production

Avant de partager l'application avec des utilisateurs, vérifiez le chemin complet de bout en bout :

Ouvrez l'URL de Copilot déployée depuis l'origine en liste blanche.
Confirmez que l'iframe de l'éditeur SimplePDF se charge sans erreur d'origine.
Envoyez un prompt de test et confirmez que le chemin IA sélectionné est utilisé.
Remplissez un champ et confirmez que la valeur apparaît dans l'éditeur PDF.
Soumettez ou téléchargez un document de test.
Si BYOS est activé, confirmez que le PDF complété atterrit dans votre stockage, pas dans le stockage SimplePDF.
Examinez les logs à la recherche de secrets, de texte de document, de PHI, de PII ou d'autres données sensibles que vous ne souhaitez pas conserver.

Personnaliser le prompt système et les outils

Une fois que Copilot tourne de bout en bout sur votre infrastructure, la couche suivante de personnalisation est le prompt système et le registre d'outils exposés au modèle. Les deux se trouvent dans src/server/tools.ts. L'interface de chat elle-même est src/components/chat_pane.tsx. Les locales sont dans src/locales/.

Pour tout le reste, y compris forker, configurer et adapter Copilot à une surface produit non triviale, la compétence fork-and-go pilote un assistant de codage IA à travers le travail, une décision à la fois.

Dépannage

L'iframe de l'éditeur refuse de se charger

Vérifiez que l'origine de l'application parente figure bien dans la liste blanche du tableau de bord SimplePDF. L'espace de démo local n'autorise que http://localhost:3001.

La démo locale fonctionne mais pas la production

Confirmez que VITE_SIMPLEPDF_COMPANY_IDENTIFIER utilise votre propre identifiant d'entreprise SimplePDF et que votre domaine de production figure dans la liste des origines autorisées.

Les utilisateurs sont invités à coller une clé d'IA

C'est attendu en mode BYOK. Pour partager une démo préconfigurée, configurez SHARED_API_KEYS et utilisez le flux d'URL ?share=<id>.

Les limites de débit se réinitialisent à chaque déploiement

Les limites de débit en mémoire se réinitialisent au redémarrage de l'application. Utilisez REDIS_URL et IP_HASH_SALT si les compteurs doivent persister entre les conteneurs ou les redémarrages.

Les PDF complétés n'atterrissent pas dans votre stockage

Confirmez que Bring Your Own Storage est configuré dans SimplePDF et testez avec un petit PDF avant d'utiliser des formulaires en production.

Voilà ! Votre application Copilot tourne maintenant sur votre infrastructure, utilise le chemin IA que vous avez configuré et peut envoyer les documents complétés vers votre stockage lorsque BYOS est activé.

Si vous avez des questions, n'hésitez pas à contacter support@simplepdf.com