Se usi spesso strumenti online per unire PDF, dividere pagine, comprimere documenti o convertire file, probabilmente avrai provato a vedere almeno una volta se esista un’alternativa self-hosted da installare sul tuo server. La risposta è sì, e una delle soluzioni più interessanti oggi è Stirling-PDF.
Stirling-PDF è un software open source pensato per la gestione dei PDF in locale, con interfaccia web e supporto self-hosted. La documentazione ufficiale include una guida Docker molto semplice e il progetto offre oltre 50 strumenti PDF, comprese funzioni di merge, split, conversione, watermark, redact, OCR, firma e API.
In questa guida vedremo come installare Stirling-PDF in locale con Docker, come accedere all’interfaccia web e quali sono le funzioni più utili da conoscere subito.
Cos’è Stirling-PDF
Stirling-PDF è una piattaforma self-hosted per lavorare con file PDF tramite browser. Il repository ufficiale lo descrive come una soluzione con più di 50 operazioni sui PDF, supporto a interfaccia web, API privata, pipeline personalizzate e varie funzioni avanzate per modifica, conversione e automazione.
In pratica, invece di caricare i tuoi documenti su siti esterni, puoi gestire tutto nel tuo ambiente locale o sul tuo VPS.
Perché usarlo in locale
Installare Stirling-PDF in locale ha diversi vantaggi:
- eviti di caricare documenti sensibili su servizi web di terze parti;
- hai una piattaforma sempre disponibile nel tuo ambiente;
- puoi integrare le sue funzioni in workflow interni grazie alle API;
- puoi usare molti strumenti PDF da un’unica interfaccia.
Questa è una soluzione particolarmente interessante se lavori con documenti tecnici, scansioni, file aziendali o materiale che preferisci non inviare a servizi cloud esterni.
Funzioni principali
Una delle ragioni per cui Stirling-PDF è così interessante è che non si limita a una o due operazioni di base. Ha infatti un numero molto ampio di strumenti disponibili.
Tra le funzioni più utili trovi:
- unione di più PDF in un unico file;
- divisione di PDF per pagine o sezioni;
- rotazione, riordino ed estrazione pagine;
- conversione tra PDF e immagini;
- conversione di file comuni verso PDF tramite LibreOffice;
- OCR e strumenti per scansioni;
- watermark, sanitizzazione e auto-redact;
- firma, modifica metadata e gestione annotazioni.
Requisiti minimi
Per seguire questa guida ti basta avere:
- un sistema Linux, mini server o VPS;
- Docker installato e funzionante;
- un browser moderno;
- facoltativamente docker compose, se preferisci una gestione più ordinata del servizio.
La documentazione ufficiale mostra sia l’avvio diretto con docker run sia l’uso di Docker Compose.
Installare Stirling-PDF con Docker
Il modo più rapido per iniziare è usare il comando di avvio Docker indicato nella documentazione ufficiale. La guida Docker di Stirling-PDF usa la porta 8080 e monta almeno la directory /configs per la persistenza di configurazione.
Per prima cosa crea una cartella dedicata:
mkdir -p ~/stirling-pdf
cd ~/stirling-pdfOra avvia il container con una configurazione minima:
docker run -d \
--name stirling-pdf \
-p 8080:8080 \
-v ./stirling-data:/configs \
stirlingtools/stirling-pdf:latestQuesto esempio segue il quick start ufficiale della documentazione Docker.
Accesso all’interfaccia web
Dopo l’avvio del container, apri il browser e visita:
http://localhost:8080Se hai installato il servizio su un VPS o su un server di rete, sostituisci localhost con l’indirizzo IP o il nome host corretto. Al primo accesso, potrai accedere utilizzando l’utente “admin” e la password “stirling” che ti invitiamo a sostituire subito, soprattutto se stai esponendo il servizio all’esterno, tant’è vero che sarà la prima operazione che StirlingPDF stesso ti farà fare.
Dopo il cambio password, verrai accolto da un tour che mostra le varie funzionalità del software e dopodiché potrai accedere alla dashboard con tutti i vari strumenti per operare sui file PDF:
Configurazione Docker più completa
Se vuoi una configurazione più ordinata, soprattutto per uso continuativo, puoi usare anche una struttura con più volumi. Un esempio di docker-compose.yml semplice può essere questo:
services:
stirling-pdf:
image: stirlingtools/stirling-pdf:latest
container_name: stirling-pdf
ports:
- "8080:8080"
volumes:
- ./stirling-data/configs:/configs
- ./stirling-data/logs:/logs
- ./stirling-data/pipeline:/pipeline
- ./stirling-data/customFiles:/customFiles
restart: unless-stoppedAvvio:
docker compose up -dQuesta impostazione è comoda se vuoi mantenere meglio file e configurazioni nel tempo, soprattutto per effettuare self-hosting su un server.
OCR e componenti aggiuntivi
Stirling-PDF supporta funzioni OCR e strumenti più avanzati, ma in alcune configurazioni possono servire directory o lingue aggiuntive per Tesseract. La documentazione Docker mostra, per esempio, il mount della cartella trainingData verso la directory di tessdata e la variabile LANGS per le lingue OCR abilitate.
Se il tuo obiettivo iniziale è solo unire, dividere, convertire e comprimere PDF, puoi tranquillamente partire dalla configurazione minima e aggiungere l’OCR in un secondo momento.
Funzioni utili da provare subito
Una volta dentro l’interfaccia, ti consiglio di testare subito alcune operazioni pratiche. Il progetto include strumenti per merge, split, conversione, watermark e compressione, quindi hai già tutto il necessario per verificare rapidamente se fa al caso tuo.
Le prime prove che farei sono:
- unire due o tre PDF in un unico documento;
- estrarre una singola pagina da un file lungo;
- convertire un documento in PDF;
- aggiungere un watermark di test;
- ridurre il peso di un PDF troppo grande.
API e automazione
Un altro aspetto interessante è la presenza di un’API privata, citata nel repository ufficiale. Questo rende Stirling-PDF adatto non solo all’uso manuale via browser, ma anche a integrazioni con script o workflow automatizzati.
Se in futuro vorrai automatizzare certe operazioni documentali, questa caratteristica può diventare molto utile in contesti interni o self-hosted più strutturati.
Sicurezza e privacy
Usare Stirling-PDF in locale significa mantenere i documenti nel tuo ambiente invece di inviarli a servizi online. Per file sensibili, scansioni con dati personali o documenti di lavoro, questo è spesso uno dei motivi principali per scegliere una soluzione self-hosted.
Se il servizio viene esposto su Internet, però, conviene proteggerlo dietro reverse proxy, HTTPS e, se necessario, autenticazione a livello applicativo o di rete, banalmente, potrebbe essere messo online esponendolo tramite nginx con certificato HTTPS gratuito rilasciato da Let’s Encrypt o al più, ancora più semplicemente, con Caddy.
Problemi comuni
La porta 8080 non risponde
Controlla che il container sia realmente attivo con:
docker psVerifica anche che un altro servizio non stia già usando la porta 8080. La guida ufficiale usa proprio questa porta come default, eventualmente, puoi sostituire la porta con una a tua scelta variandola sull’host docker, ma lasciando la porta 8080 all’interno del container, es: -p 8081:8080.
Le configurazioni non restano salvate
In quel caso il problema più probabile è l’assenza di un volume persistente montato su /configs. La documentazione mostra proprio quel mount nella configurazione minima.
OCR o funzioni avanzate non lavorano come previsto
Se usi OCR o lingue aggiuntive, controlla se hai configurato correttamente le directory di tessdata e le variabili dedicate, come negli esempi più completi della documentazione.
FAQ
Stirling-PDF è open source?
Sì. Il progetto è pubblicato pubblicamente su GitHub come software open source e la documentazione ufficiale ne supporta l’uso self-hosted.
Si può installare con Docker?
Sì. La guida ufficiale mostra sia l’avvio con docker run sia l’uso di Docker Compose.
Quali operazioni posso fare?
Stirling-PDF offre oltre 50 strumenti PDF, incluse funzioni di merge, split, conversione, OCR, watermark, redact, firma e gestione metadata.
Esiste una versione senza Docker, solo come app desktop?
Sì, Stiriling-PDF permette di avere anche un’applicazione Desktop che offre grosso modo le stesse funzionalità della versione server/docker. In questa guida ci siamo focalizzati maggiormente sulla versione server, ma se ti interessa farne un uso locale, solo sul tuo computer, puoi tranquillamente eseguire l’applicazione standalone, per maggiori informazioni, soprattutto per l’installazione dell’applicazione su Linux, ti rimandiamo alla documentazione.
Considerazioni finali
Stirling-PDF è una delle migliori soluzioni self-hosted da provare se vuoi sostituire molti servizi PDF online con un’alternativa locale, open source e accessibile via browser. L’installazione con Docker è semplice, il numero di funzioni è molto ampio e il progetto è adatto sia a uso personale sia a piccoli ambienti di lavoro.
Per iniziare davvero, ti basta la configurazione minima con Docker e qualche PDF di test. Una volta verificato che tutto funziona, potrai espandere l’installazione con volumi più completi, OCR e integrazioni via API.