Perché self-hostare un toolkit PDF invece di un altro convertitore web gratuito

I convertitori PDF che funzionano solo nel browser sono ottimizzati per il caricamento, il clic e il download. Spesso sono gli annunci a finanziare la pagina, e di solito non esiste un'interfaccia stabile per gli sviluppatori oltre al modulo. Questa forma di prodotto è corretta per un'attività umana una tantum. È la forma sbagliata quando ti servono automazione, una politica di conservazione o file che devono restare sulla tua rete.

Per cosa sono ottimizzati i convertitori nel browser

Un convertitore pubblico vende comodità: apri una scheda, trascini un file, ottieni un risultato, esci. L'interfaccia è il prodotto. Gli script o estraggono HTML oppure chiamano endpoint non documentati che cambiano senza preavviso. La conservazione dei dati dipende da chi gestisce l'archivio temporaneo. Per un singolo merge di due PDF personali, questo compromesso va bene.

Nel momento in cui ti serve la stessa elaborazione dalla CI, da un agente o da una rete isolata, i pezzi mancanti compaiono tutti insieme: autenticazione, OpenAPI, nuovi tentativi idempotenti e un catalogo che non diverge in silenzio dal modulo su cui hai cliccato la settimana scorsa.

Cosa ottieni eseguendo tu stesso questo catalogo

Il sito ospitato e un'istanza self-hosted condividono le stesse operazioni. Comprimi e Unisci sono le stesse operazioni sia che la richiesta arrivi dal portale sia che arrivi da POST /api/v1/…. Il self-hosting aggiunge il controllo intorno a quel catalogo condiviso:

• REST + OpenAPI su /v1/openapi.json: ogni strumento del catalogo è un endpoint stabile, non solo un modulo.
• MCP su /mcp: gli agenti scoprono e chiamano le stesse operazioni senza inventare scraper.
• CLI (pdfx): pdf-core in locale oppure --cloud contro una API key sul tuo URL di base.
• Nessun client desktop: Docker Compose è la soluzione offline; plugin e installer Windows restano fuori ambito di proposito.
• Gli annunci restano fuori dalla tua infrastruttura: AdSense sul sito pubblico non fa parte di un deploy self-hosted. I file caricati non lasciano mai le macchine che gestisci.

Compose avvia insieme il backend Rust pdfx-server e il portale Next.js, così persone e script condividono un unico catalogo. Lo sviluppo nativo (task pdfx:dev più il portale) usa lo stesso percorso di operazioni. I dettagli sono su Self-host.

L'OCR su entrambi i deployment restituisce comunque Markdown (text/markdown) da /api/v1/misc/ocr-pdf, non un PDF ricercabile con un nuovo strato di testo. Spostare il server cambia dove finiscono i byte, non inventa un contratto di operazioni diverso.

Cosa scegliamo deliberatamente di non copiare

Le canvas online per «modificare PDF», il confronto visivo, la creazione di PDF vuoti e le interfacce di firma per consumatori richiedono un lavoro di prodotto diverso. Preferiamo mantenere la matrice di strumenti basata su modulo e l'API. Il self-hosting non sblocca un secondo albero di interfacce: sposta lo stesso albero dietro il tuo firewall.

Saltare quelle superfici per consumatori è una scelta deliberata. Un editor a canvas sarebbe una seconda base di codice con il suo ritardo sulle funzionalità rispetto a OpenAPI. Il vincolo che conta per l'uso privato è «i byte restano qui», non «esiste un .exe». Sul perché non esista un fork desktop, vedi Perché abbiamo evitato l'app desktop.

Quando l'hosting gestito basta e quando no

Usa il sito pubblico quando vuoi zero configurazione e un'attività anonima una tantum. Gli strumenti del catalogo e le chiamate anonime a /api/v1/ non richiedono account; le risposte ospitate espongono le intestazioni di limite di frequenza, e i tetti esistono perché il servizio gratuito non diventi la fattoria di batch di qualcun altro (limite di frequenza anonimo).

Scegli il self-host quando lo richiedono regole di conservazione, reti private o automazione privata. Allora possiedi disponibilità, aggiornamenti delle immagini, spazio su disco per i file temporanei, TLS e rotazione delle chiavi (SECURITY_CUSTOMGLOBALAPIKEY per un controllo fisso sulla tua macchina). Le operazioni restano le stesse; ciò che cambia è dove finiscono i byte.

Provalo

Parti da Self-host e Developers. Per l'API rivolta agli agenti su qualsiasi URL di base, leggi Costruito per gli agenti AI, non solo per il browser. Per un confronto più ampio tra costi e benefici, vedi Cosa ti dà davvero il self-hosting.