Come fare self-hosting di Shiori nel 2026: archivi, account e storage persistente

Un deployment di Shiori che non funziona non va necessariamente in crash. Potrebbe mostrare la pagina di login mentre l'archiviazione non funziona perché le dipendenze di Chromium o i permessi del filesystem sono errati. Inizia invece con un controllo end-to-end: salva un bookmark con contenuto archiviato, cercalo, modifica i tag e verifica che l'archivio resti disponibile dopo che la pagina sorgente è cambiata.

Questo controllo corrisponde allo scopo catalogato di Shiori: un bookmark manager che archivia il contenuto delle pagine. Inoltre, rende visibili prima di un semplice uptime probe le dipendenze mancanti, le ipotesi errate sul proxy e i dati effimeri.

Delimita il runtime di Shiori

Per Shiori, la salute del processo e quella del prodotto sono due aspetti distinti. La porta 8080 potrebbe rispondere anche se la transazione lato utente continua a fallire. Il requisito esterno di Shiori è un data volume scrivibile e l'accesso in uscita alle pagine da archiviare. Verifica DNS in uscita, TLS e il comportamento del provider senza pubblicare un altro servizio in ingresso.

Esegui questo readiness test dopo modifiche significative alla configurazione: salva un bookmark con contenuto archiviato, cercalo, modifica i tag e verifica che l'archivio resti disponibile dopo che la pagina sorgente è cambiata. Tieni i controlli esterni più costosi fuori dai liveness probe, così un'interruzione del provider non causa un restart loop. Il capacity planning dovrebbe tenere traccia della cattura delle pagine basata sul browser, delle dimensioni degli archivi, delle thumbnail e del fetching in uscita: questi elementi riflettono meglio la reale pressione su Shiori rispetto alle richieste alle pagine.

Ripristina Shiori su un host vuoto

Elenca lo stato prima di creare il primo record reale: database, contenuto delle pagine archiviate, thumbnail e configurazione. Monta /shiori prima del bootstrap, scrivi dati di esempio innocui e sostituisci il container per dimostrare che quel percorso è effettivamente persistente. Conferma il mount scrivendo dati innocui, sostituendo Shiori e rileggendoli.

Gli snapshot sono utili per un rollback rapido, ma serve un backup indipendente quando l'host o il volume non sono più disponibili. Esegui il ripristino in un ambiente vuoto con l'immagine fissata a una versione specifica e verifica che bookmark, tag, file di archivio e account vengano ripristinati e che un link sorgente non più attivo continui ad aprire il contenuto salvato. Usa persistent volumes e snapshot per mantenere distinti questi due meccanismi di recovery.

Decisioni di sicurezza specifiche per Shiori

Il rischio di sicurezza specifico dell'applicazione consiste nel lasciare invariato l'account iniziale su un'istanza pubblica. La risposta operativa è sostituire l'account iniziale, limitare la condivisione pubblica e trattare gli URL privati archiviati come contenuti sensibili. Completa il bootstrap tramite una route con accesso limitato e rimuovi subito dopo l'accesso temporaneo alla configurazione.

SHIORI_DIR controlla il comportamento, non la riservatezza; convalida il tipo e il valore e conserva separatamente le vere credenziali di Shiori. Concedi al processo Shiori solo i mount e le route delle 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.

Procedura di acceptance per Shiori in produzione

Una release candidate di Shiori merita di ricevere traffico quando completa uno scenario predefinito: salva un bookmark con contenuto archiviato, cercalo, modifica i tag e verifica che l'archivio resti disponibile dopo che la pagina sorgente è cambiata. Acquisisci il digest dell'immagine, la configurazione effettiva non contenente segreti, l'origine pubblica e i timestamp relativi a quello scenario. I dati di test devono essere eliminabili, ma abbastanza realistici da esercitare lo stesso percorso degli utenti.

Esegui il test dopo aver sostituito il runtime, quindi ricostruisci il servizio a partire da database, contenuto delle pagine archiviate, thumbnail e configurazione. Il recovery ha esito positivo quando bookmark, tag, file di archivio e account vengono ripristinati e un link sorgente non più attivo continua ad aprire il contenuto salvato. Confronta le misurazioni delle risorse relative alla cattura delle pagine basata sul browser, alle dimensioni degli archivi, alle thumbnail e al fetching in uscita con quelle della release precedente e analizza ogni variazione significativa prima della promozione.

Infine, esegui questo failure test controllato: nega temporaneamente il percorso di test utilizzato da un data volume scrivibile e l'accesso in uscita alle pagine da archiviare. Verifica che Shiori spieghi il problema, non danneggi lo stato esistente e riprenda a funzionare quando la condizione valida torna disponibile. Salva un estratto del log con i dati sensibili rimossi e il tempo di recovery. Insieme, questi controlli coprono comportamento, durabilità e operatività, non soltanto l'uptime del processo.

Avvia Shiori con impostazioni osservabili predefinite

Mantieni l'avvio iniziale di Shiori sufficientemente riproducibile da poterlo esaminare in una pull request.

docker run -d \
  --name shiori \
  --restart unless-stopped \
  -p 127.0.0.1:8080:8080 \
  -v shiori-data:/shiori \
  -e SHIORI_DIR=/shiori \
  ghcr.io/go-shiori/shiori:latest

Non fare affidamento su latest dopo che esistono dati reali. Acquisisci il digest funzionante, l'utente del container e la ownership del mount. Segui il log dell'applicazione durante un test completo — salva un bookmark con contenuto archiviato, cercalo, modifica i tag e verifica che l'archivio resti disponibile dopo che la pagina sorgente è cambiata — e annota eventuali migrazioni prima di mettere la route dietro il traffico di produzione.

Domini, header del proxy e porta 8080

Tratta l'URL esterno di Shiori come una configurazione che deve sopravvivere ai redeploy. Prima instrada UI e API attraverso un'origine HTTPS stabile; poi instrada l'hostname verso la porta 8080 mantenendo invariati host e schema originali.

La checklist per verificare la raggiungibilità del deployment può dimostrare che le richieste entrano nel container. Da quel momento, il problema noto — l'archiviazione non funziona perché le dipendenze di Chromium o i permessi del filesystem sono errati — va analizzato in Shiori, nel suo stato o nel suo workload, non nell'automazione dei certificati.

Aggiorna Shiori senza procedere per tentativi

La prima metrica operativa utile per Shiori è verificare se riesce a salvare un bookmark con contenuto archiviato, cercarlo, modificarne i tag e confermare che l'archivio resti disponibile dopo che la pagina sorgente è cambiata. Affianca a questo dato i segnali di saturazione relativi alla cattura delle pagine basata sul browser, alle dimensioni degli archivi, alle thumbnail e al fetching in uscita. Un probe limitato al processo non dovrebbe chiamare dipendenze costose né riavviare il container perché un upstream è temporaneamente non disponibile.

Tratta gli upgrade come modifiche ai dati, perché le migrazioni del database di Shiori e le dipendenze per la cattura delle pagine possono cambiare il comportamento degli archivi. Fissa le versioni, prova la procedura su uno stato ripristinato e conserva l'immagine precedente finché il rollback non resta valido. Quando l'archiviazione non funziona perché le dipendenze di Chromium o i permessi del filesystem sono errati, conserva i log precedenti al riavvio: di solito contengono il messaggio che identifica la causa.

Cosa dovrebbe automatizzare Dockup per Shiori

Il platform layer per Shiori comprende la porta 8080, l'ingress, TLS, la configurazione del runtime, lo storage e la raggiungibilità delle dipendenze. Dockup può riprodurre questi elementi sulla propria infrastruttura o su un server collegato dal cliente.

L'operatore completa quindi il product layer: instrada UI e API attraverso un'origine HTTPS stabile; applica questa regola di accesso — sostituisci l'account iniziale, limita la condivisione pubblica e tratta gli URL privati archiviati come contenuti sensibili —; ed esegue “salva un bookmark con contenuto archiviato, cercalo, modifica i tag e verifica che l'archivio resti disponibile dopo che la pagina sorgente è cambiata”. Registrare questo test insieme al deployment evita di confondere il provisioning automatizzato con la readiness dell'applicazione.

Domande frequenti

Di cosa ha bisogno Shiori per un deployment in produzione?

Instrada il container Shiori sulla porta 8080 attraverso un'unica origine HTTPS. Il requisito esterno per la distribuzione è un data volume scrivibile e l'accesso in uscita alle pagine da archiviare. Non considerare Shiori pronto finché non puoi salvare un bookmark con contenuto archiviato, cercarlo, modificarne i tag e verificare che l'archivio resti disponibile dopo che la pagina sorgente è cambiata.

Quali dati di Shiori devono essere inclusi in un backup?

Rendi persistente /shiori e includi database, contenuto delle pagine archiviate, thumbnail e configurazione nello stesso recovery manifest. Un ripristino pulito di Shiori ha esito positivo solo quando bookmark, tag, file di archivio e account vengono ripristinati e un link sorgente non più attivo continua ad aprire il contenuto salvato.

Shiori richiede HTTPS dietro un reverse proxy?

Usa HTTPS per l'origine pubblica di Shiori e mantieni la porta 8080 sulla route interna. Applica correttamente l'impostazione di Shiori: instrada UI e API attraverso un'origine HTTPS stabile. Per Shiori, HTTPS protegge le credenziali o i contenuti degli utenti durante il transito e mantiene coerente il comportamento del client sensibile all'origine.

Come si deve testare un upgrade di Shiori?

Ripristina lo stato corrente di Shiori in un deployment isolato, applica la versione candidata e ripeti la sua transazione di acceptance. Presta particolare attenzione, perché le migrazioni del database di Shiori e le dipendenze per la cattura delle pagine possono cambiare il comportamento degli archivi. Conserva l'immagine precedente di Shiori finché non avrai compreso i limiti della migrazione dei dati e del rollback.