Como auto-alojar o SimplePDF Copilot

Benjamin André-Micolon

O SimplePDF Copilot é uma implementação de referência sob licença MIT para adicionar uma barra lateral de chat com IA ao editor SimplePDF. Pode fazer fork da aplicação Copilot, implementá-la na sua infraestrutura, ligar o seu próprio fornecedor de IA e encaminhar os documentos completos para o seu próprio armazenamento.

O editor SimplePDF em si continua a ser um iframe alojado. Auto-alojar o Copilot significa que é dono da aplicação de chat, do encaminhamento de IA, dos prompts, das ferramentas e do fluxo de armazenamento à volta do editor.

Este guia cobre o caminho de localhost até produção.

Se utiliza o Claude Code, o Codex ou outra ferramenta de codificação agêntica, aponte-a para a skill fork-and-go. A skill conduz o agente pelo fork, pela configuração e pela implementação, uma pergunta de cada vez.

O que auto-aloja

Aplicação de chat Copilot. Corre na sua infraestrutura. Você controla-a.
Prompt de sistema e registo de ferramentas. Vivem na sua implementação do Copilot. Você controla-os.
Encaminhamento de IA. Do lado do servidor, BYOK do navegador ou endpoint local. Você controla-o.
Armazenamento dos documentos completos. Armazenamento SimplePDF por defeito, ou o seu armazenamento com BYOS. Você controla-o quando o BYOS está ativo.
Iframe do editor SimplePDF. Continua alojado pela SimplePDF.

Pré-requisitos

Um plano SimplePDF Pro ou superior. Executar o Copilot no seu próprio domínio exige white-labeling, controlo programático do editor e uma origem permitida no seu painel SimplePDF. Sem essas capacidades, o editor só carrega na origem da demonstração alojada ou em http://localhost:3001.
Uma chave de fornecedor de IA, um fluxo BYOK ou um endpoint local compatível com OpenAI. Anthropic, OpenAI, DeepSeek, Google Gemini e Mistral estão integrados de origem.
Um runtime Node 24. O template atual de implementação do Copilot usa Node 24 e a aplicação corre sem alterações em DigitalOcean App Platform, Cloudflare Containers, Vercel, Render, fly.io, Railway ou Docker auto-alojado.

Passo 1: Executar a demonstração localmente

Clone o repositório e execute a demonstração contra o espaço de demonstração SimplePDF partilhado. Para este passo não é necessária qualquer conta 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

O servidor de desenvolvimento corre em http://localhost:3001. Abra a barra lateral de chat, cole uma chave de fornecedor ou aponte para um endpoint local compatível com OpenAI, como o Ollama ou o LM Studio.

O espaço de demonstração permite exatamente uma origem local: http://localhost:3001. Qualquer outra porta ou host será recusado pelo iframe. Para correr no seu próprio domínio, avance para o Passo 2.

Passo 2: Configurar a sua conta SimplePDF

Subscreva o plano Pro ou superior. A partir do painel do SimplePDF:

Copie o seu companyIdentifier. Este é o valor que vai colocar em VITE_SIMPLEPDF_COMPANY_IDENTIFIER.
Adicione à whitelist a sua origem de serviço, por exemplo https://app.example.com. O iframe recusa carregar em origens que não estejam na whitelist.
Opcionalmente, personalize a sua marca para remover os elementos do SimplePDF do editor.

Passo 3: Implementar no seu host

O caminho mais rápido é o botão de implementação com um clique do DigitalOcean no README do SimplePDF Copilot. O DigitalOcean compila a pasta copilot/ com Node 24 e pede as variáveis de ambiente.

VITE_SIMPLEPDF_COMPANY_IDENTIFIER (obrigatória): o identificador da sua empresa SimplePDF.
SHARED_API_KEYS (opcional): permite partilhar uma demonstração sem pedir a cada visitante para colar uma chave de fornecedor.
REDIS_URL (opcional): persiste os contadores de limite de taxa entre contentores.
IP_HASH_SALT (obrigatória quando REDIS_URL está definido): aplica salt aos hashes de IP persistidos.

Para outros destinos de implementação, incluindo Cloudflare Containers, Vercel, Render, fly.io, Railway e Docker auto-alojado, siga a secção outros destinos de implementação do README.

Depois de implementado, adicione a origem implementada, por exemplo https://copilot.example.com, à whitelist do seu painel SimplePDF antes de abrir a aplicação.

Passo 4: Ligar o seu fornecedor de IA

O streaming do lado do servidor encontra-se em src/routes/api/chat.ts. A seleção do fornecedor encontra-se em src/server/language_model.ts. Use este caminho quando a sua aplicação for dona da chave do fornecedor, dos limites de taxa, dos logs e da configuração por inquilino.

Para chaves fornecidas pelo utilizador, o caminho BYOK direto a partir do navegador em src/lib/byok/ chama o fornecedor a partir do navegador e contorna o seu servidor. Esta é também a forma certa para endpoints locais compatíveis com OpenAI, como o Ollama ou o LM Studio.

Três rotas, três fronteiras de confiança:

Chave de fornecedor do lado do servidor. A sua aplicação é dona da conta do fornecedor e da política por inquilino. O tráfego de IA flui através do seu servidor até ao fornecedor de IA.
BYOK no navegador. Os utilizadores trazem a sua própria chave de fornecedor. O tráfego de IA flui do navegador diretamente para o fornecedor selecionado, contornando o seu servidor.
Endpoint local compatível com OpenAI. O tráfego de IA permanece no dispositivo ou na rede do utilizador. O navegador comunica com o endpoint local; nada vai para um fornecedor de IA terceiro.

Passo 5: Encaminhar as submissões para o seu armazenamento

Por defeito, os documentos completos chegam ao armazenamento do SimplePDF. Com Bring Your Own Storage a partir do plano Pro, os documentos completos são carregados diretamente do navegador para o seu armazenamento configurado, usando URLs pré-assinados.

Isto altera o caminho de armazenamento dos documentos completos. Por si só, não controla qual o contexto do documento que é enviado para o fornecedor de IA configurado. Configure a rota de IA em separado no Passo 4.

Configurar o armazenamento:

Passo 6: Verificar a configuração de produção

Antes de partilhar a aplicação com utilizadores, verifique o caminho completo de ponta a ponta:

Abra o URL do Copilot implementado a partir da origem em whitelist.
Confirme que o iframe do editor SimplePDF carrega sem erros de origem.
Envie um prompt de teste e confirme que a rota de IA selecionada é utilizada.
Preencha um campo e confirme que o valor aparece no editor PDF.
Submeta ou descarregue um documento de teste.
Se o BYOS estiver ativo, confirme que o PDF completo chega ao seu armazenamento e não ao armazenamento do SimplePDF.
Reveja os logs em busca de segredos, texto do documento, PHI, PII ou outros dados sensíveis que não queira persistir.

Personalizar o prompt do sistema e as ferramentas

Assim que o Copilot funcionar de ponta a ponta na sua infraestrutura, a próxima camada de personalização é o prompt do sistema e o registo de ferramentas exposto ao modelo. Ambos vivem em src/server/tools.ts. A interface de chat em si é src/components/chat_pane.tsx. As localizações estão em src/locales/.

Para tudo o resto, incluindo fazer fork, configurar e adaptar o Copilot a uma superfície de produto não trivial, a skill fork-and-go conduz um assistente de codificação com IA pelo trabalho, uma decisão de cada vez.

Resolução de problemas

O iframe do editor recusa carregar

Verifique se a origem da aplicação principal está na whitelist do painel SimplePDF. O espaço de demonstração local apenas permite http://localhost:3001.

A demonstração local funciona mas a produção não

Confirme que VITE_SIMPLEPDF_COMPANY_IDENTIFIER usa o seu próprio identificador de empresa SimplePDF e que o seu domínio de produção consta da lista de origens permitidas.

Os utilizadores são convidados a colar uma chave de IA

Isso é o esperado em modo BYOK. Para partilhar uma demonstração pré-configurada, defina SHARED_API_KEYS e use o fluxo de URL ?share=<id>.

Os limites de taxa repõem-se a cada implementação

Os limites de taxa em memória repõem-se quando a aplicação reinicia. Use REDIS_URL e IP_HASH_SALT se os contadores tiverem de persistir entre contentores ou reinícios.

Os PDF completos não chegam ao seu armazenamento

Confirme que o Bring Your Own Storage está configurado no SimplePDF e teste com um PDF pequeno antes de utilizar formulários em produção.

E pronto! A sua aplicação Copilot corre agora na sua infraestrutura, usa a rota de IA que configurou e pode enviar os documentos completos para o seu armazenamento quando o BYOS está ativo.

Se tiver alguma questão, não hesite em contactar support@simplepdf.com