Come fare il self-hosting di Stirling PDF nel 2026: upload, OCR e sicurezza del login

Esistono due versioni del “far funzionare Stirling PDF”: esiste un container oppure il servizio svolge davvero il suo lavoro. Solo la seconda conta. In questo caso, la verifica consiste nell’unire due PDF, applicare l’OCR a una pagina acquisita tramite scansione, comprimere il risultato e verificare il comportamento di upload e download attraverso il proxy pubblico.

Stirling PDF serve proprio a questo: offre un’interfaccia web e un’API per le operazioni PDF più comuni. Il deployment deve preservare gli elementi che rendono possibile questo comportamento; una porta, un volume e un certificato sono input, non il risultato.

Impostazioni del container da verificare

Il primo container dovrebbe poter essere eliminato e ricreato facilmente. Mantieni i dati fuori dal writable layer, fai il bind della porta 8080 solo dove il proxy può raggiungerla e passa la configurazione a runtime.

docker run -d \
  --name stirling-pdf \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -v stirling-pdf-data:/configs \
  -e SECURITY_ENABLELOGIN=true \
  stirlingtools/stirling-pdf:latest

Dopo il test iniziale, fissa la versione dell’immagine. Leggi il primo errore di avvio invece dell’ultimo messaggio di riavvio, verifica ogni mount con docker inspect e segui i log mentre unisci due PDF, applichi l’OCR a una pagina acquisita tramite scansione, comprimi il risultato e verifichi il comportamento di upload e download attraverso il proxy pubblico. Questa sequenza distingue un comando dell’immagine errato da un problema di dipendenze o permessi.

Definisci prima il successo di Stirling PDF

Per Stirling PDF, separa quattro aspetti: ingress, listener sulla porta 8080, stato persistente e servizi di supporto o capacità locale. Il requisito del runtime locale consiste, se necessario, nei dati delle lingue OCR e in spazio temporaneo sufficiente per i job di grandi dimensioni. Registralo accanto all’immagine e alla porta, così un host sostitutivo riceverà le stesse capacità locali.

Esegui la transazione verificata — unisci due PDF, applica l’OCR a una pagina acquisita tramite scansione, comprimi il risultato e verifica il comportamento di upload e download attraverso il proxy pubblico — prima di considerare completata questa separazione. Misura lo spazio temporaneo, i language pack OCR, la memoria JVM e il numero di job di conversione simultanei, quindi conserva il risultato insieme al record del deployment. Avrai così sia un criterio di accettazione sia la prima baseline di capacità.

Metti in sicurezza Stirling PDF dopo il bootstrap

Il rischio di sicurezza specifico dell’applicazione consiste nel lasciare disabilitata la sicurezza su un servizio pubblico di elaborazione documenti. La soluzione operativa è abilitare il login per un’istanza esposta a Internet ed evitare di conservare i documenti caricati più a lungo del necessario per il job. Completa il bootstrap tramite un percorso limitato e rimuovi subito dopo l’accesso temporaneo alla configurazione.

SECURITY_ENABLELOGIN controlla il comportamento, non la riservatezza; verificane tipo e valore e conserva le credenziali effettive di Stirling PDF separatamente. Concedi al processo di Stirling PDF solo i mount e i percorsi verso le dipendenze documentati; evita l’accesso alla root dell’host e al socket Docker. Registra i tentativi di autenticazione falliti e gli errori di configurazione, ma oscura token, connection string e contenuti degli utenti.

Assegna a Stirling PDF un unico indirizzo canonico

Browser, client API e Stirling PDF devono concordare su un’unica origin. Per ottenere questo risultato, configura l’origin HTTPS pubblico e i limiti di upload del proxy. Mantieni host e protocollo originali, lasciando però la porta 8080 non disponibile come indirizzo pubblico alternativo.

La guida alla risoluzione dei problemi quando il sito non è raggiungibile aiuta a distinguere un percorso irraggiungibile da un’applicazione che risponde. Qui la distinzione è importante: gli upload superano il limite del proxy oppure il container non riesce a scrivere i file temporanei. Solo il primo caso si risolve modificando l’ingress; il secondo richiede l’analisi dei log, dello stato o del carico di lavoro di Stirling PDF.

Separa i container sostituibili dai dati persistenti

Il set di ripristino persistente comprende la configurazione, i file personalizzati e tutti i dati OCR che hai installato intenzionalmente. Esegui il mount di /configs prima del bootstrap, scrivi dati di esempio innocui e sostituisci il container per dimostrare che il percorso è effettivamente persistente. Un volume protegge i dati dalla sostituzione del container, ma non dalla perdita dell’host, dalla cancellazione accidentale o dalla corruzione a livello applicativo.

Esegui backup compatibili con la sorgente dei dati: quando necessario, usa dump logici per i database attivi e copia i file solo da uno stato coerente. Conserva una copia cifrata lontano dall’host di Stirling PDF. Il criterio di accettazione per un restore deve essere specifico: la configurazione e gli asset OCR devono tornare disponibili e un documento di test fisso deve produrre un risultato leggibile e accettabile. La guida ai backup verificati tramite restore spiega perché il solo esito positivo del job non è sufficiente.

Raccogli le evidenze prima di portare Stirling PDF in produzione

Per Stirling PDF, definisci una transazione verificata prima del lancio: unisci due PDF, applica l’OCR a una pagina acquisita tramite scansione, comprimi il risultato e verifica il comportamento di upload e download attraverso il proxy pubblico. Inserisci i prerequisiti, la risposta attesa e i passaggi di pulizia nel version control, senza valori segreti. Fissa la versione dell’immagine utilizzata per stabilire questo riferimento.

Usa la transazione per convalidare una sostituzione e un restore indipendente. Il servizio ripristinato è accettabile solo quando la configurazione e gli asset OCR tornano disponibili e un documento di test fisso produce un risultato leggibile e accettabile. Allo stesso tempo, osserva lo spazio temporaneo, i language pack OCR, la memoria JVM e il numero di job di conversione simultanei, quindi trasforma la parte più lenta o più vincolata in un alert a livello di servizio.

Il gate deve includere anche un caso negativo: invia un input innocuo vicino al limite di risorse o formato associato a questo confine: gli upload superano il limite del proxy oppure il container non riesce a scrivere i file temporanei. Verifica che Stirling PDF produca un errore utile senza compromettere i dati, ripristina la condizione valida e ripeti la transazione verificata. Conservare entrambi i risultati impedisce che un endpoint di health superficiale diventi l’unica evidenza disponibile in produzione.

Gestisci Stirling PDF tenendo conto del suo vero collo di bottiglia

Osserva il lavoro svolto da Stirling PDF: spazio temporaneo, language pack OCR, memoria JVM e numero di job di conversione simultanei. Imposta i limiti lasciando margine sufficiente per questo carico ed evita un liveness probe che entri in competizione con esso. Il controllo dell’operatore dovrebbe comunque provare, secondo una pianificazione, a unire due PDF, applicare l’OCR a una pagina acquisita tramite scansione, comprimere il risultato e verificare il comportamento di upload e download attraverso il proxy pubblico.

Per gli aggiornamenti, ricorda che i dati OCR installati, la configurazione personalizzata e le impostazioni di sicurezza devono essere confrontati prima dell’upgrade dell’immagine. Esegui il candidate deployment su una copia ripristinata e ripeti il test verificato. Se gli upload superano il limite del proxy oppure il container non riesce a scrivere i file temporanei, usa i log di runtime e la richiesta di rete effettiva per individuare quale ipotesi è cambiata.

Esegui il deployment di Stirling PDF su Dockup senza perdere questi confini

Dockup elimina il lavoro manuale relativo a reverse proxy e lifecycle di Stirling PDF. Il servizio riceve un percorso HTTPS stabile verso la porta 8080, configurazione iniettata e storage persistente durante le sostituzioni. Un server del cliente collegato segue lo stesso modello del compute ospitato su Dockup.

Dopo il lancio, soddisfa il contratto dell’applicazione: configura l’origin HTTPS pubblico e i limiti di upload del proxy, conferma il requisito locale — dati delle lingue OCR opzionali e spazio temporaneo sufficiente per i job di grandi dimensioni — ed esegui questa verifica: unisci due PDF, applica l’OCR a una pagina acquisita tramite scansione, comprimi il risultato e verifica il comportamento di upload e download attraverso il proxy pubblico. In questo modo l’esperienza one-click resta utile senza appiattire i dettagli che rendono Stirling PDF ripristinabile e sicuro.

Domande frequenti

Di cosa ha bisogno Stirling PDF per un deployment in produzione?

Instrada il container di Stirling PDF sulla porta 8080 attraverso un’unica origin HTTPS. Il requisito del runtime locale consiste nei dati delle lingue OCR opzionali e in spazio temporaneo sufficiente per i job di grandi dimensioni. Non considerare Stirling PDF pronto finché non puoi unire due PDF, applicare l’OCR a una pagina acquisita tramite scansione, comprimere il risultato e verificare il comportamento di upload e download attraverso il proxy pubblico.

Quali dati di Stirling PDF devono essere inclusi in un backup?

Rendi persistente /configs e includi configurazione, file personalizzati e tutti i dati OCR installati intenzionalmente nello stesso manifest di ripristino. Un restore pulito di Stirling PDF è riuscito solo quando la configurazione e gli asset OCR tornano disponibili e un documento di test fisso produce un risultato leggibile e accettabile.

Stirling PDF richiede HTTPS dietro un reverse proxy?

Usa HTTPS per l’origin pubblica di Stirling PDF e mantieni la porta 8080 sul percorso interno. Applica correttamente l’impostazione di Stirling PDF: configura l’origin HTTPS pubblico e i limiti di upload del proxy. Per Stirling PDF, HTTPS protegge le credenziali o i contenuti degli utenti durante il transito e mantiene coerente il comportamento del client sensibile all’origin.

Come si deve testare un upgrade di Stirling PDF?

Ripristina lo stato corrente di Stirling PDF in un deployment isolato, applica la versione candidata e ripeti la transazione di accettazione. Presta particolare attenzione al fatto che i dati OCR installati, la configurazione personalizzata e le impostazioni di sicurezza devono essere confrontati prima dell’upgrade dell’immagine. Mantieni l’immagine precedente di Stirling PDF finché non avrai compreso i confini della migrazione dei dati e del rollback.