Federico Book Library

Una libreria digitale personale realizzata con Perl e Mojolicious, che legge gli scaffali pubblici di un account BookWyrm e li presenta in un'interfaccia responsive.

Il catalogo viene salvato in un file JSON locale: non serve un database.

Stato del progetto: la configurazione per una distribuzione pubblica è in preparazione. Prima di pubblicare il repository, verificare le istruzioni su un'installazione pulita e aggiungere una licenza.

Funzionalità

• Catalogo dei libri con copertine, titoli e autori.
• Ricerca per titolo e autore, ordinamento e filtri per scaffale.
• Evidenza del libro attualmente in lettura.
• Pagina di dettaglio, statistiche e pagina 404 personalizzata.
• Sincronizzazione degli scaffali pubblici di BookWyrm (to-read, reading, read, stopped-reading).
• Rilevamento di libri aggiunti, rimossi, modificati e invariati.
• Aggiornamento atomico di data/books.json e ricaricamento automatico del catalogo in memoria.
• Esecuzione con Podman e server di produzione Hypnotoad.

Requisiti

Per l'esecuzione locale:

• Perl (versione compatibile con il cpanfile).
• Mojolicious, inclusi il server Hypnotoad e il plugin NotYAMLConfig.
• IO::Socket::SSL e certificati CA per le richieste HTTPS.
• Accesso HTTPS pubblico all'istanza BookWyrm scelta.

Per il container: Podman e connettività Internet per costruire l'immagine.

Su Debian 12, i pacchetti utilizzati dall'immagine sono perl, libmojolicious-perl, libio-socket-ssl-perl e ca-certificates.

Prima installazione — esecuzione locale

1. Ottenere il codice

git clone URL_DEL_REPOSITORY
cd NOME_DIRECTORY_REPOSITORY

Sostituire i segnaposto con l'URL e la directory effettivi del repository dopo la pubblicazione.

2. Installare le dipendenze (Debian/Ubuntu)

sudo apt update
sudo apt install -y perl libmojolicious-perl libio-socket-ssl-perl ca-certificates

3. Creare la configurazione privata dell'applicazione

cp federico_book_portal.yml.example federico_book_portal.yml
openssl rand -hex 32

Inserire il segreto generato al posto del segnaposto nel file federico_book_portal.yml. Non pubblicare il segreto.

Per un avvio locale senza reverse proxy, mantenere hypnotoad.proxy: 0 nell'esempio.

4. Configurare BookWyrm

cp .env.example .env

Modificare .env:

BOOKWYRM_INSTANCE=https://bookwyrm.social
BOOKWYRM_USERNAME=nomeutente

L'istanza deve utilizzare HTTPS. Lo script usa gli scaffali pubblici dell'account indicato. Non sono previste credenziali BookWyrm.

Il file .env non viene caricato automaticamente da Perl: nel terminale che avvia il downloader occorre esportarne le variabili.

set -a
. ./.env
set +a

5. Scaricare il catalogo prima di avviare il sito

Il sito richiede che data/books.json esista all'avvio. Occorre quindi effettuare il primo download prima di avviare Mojolicious.

perl script/download_books.pl --check
perl script/download_books.pl --download

--check verifica la sincronizzazione senza scrivere; --download crea o aggiorna data/books.json.

6. Avviare l'applicazione per lo sviluppo

morbo script/federico_book_portal

Aprire l'URL indicato da Morbo nel terminale (normalmente http://127.0.0.1:3000). Morbo è il server di sviluppo, non quello previsto per la produzione.

7. Eseguire i test

prove -lv t/

I test del downloader utilizzano fixture locali: non richiedono accesso a un account BookWyrm reale.

Prima installazione — Podman

1. Preparare i file locali

Completare i passaggi di configurazione precedenti: federico_book_portal.yml, .env e primo download di data/books.json.

2. Costruire l'immagine

podman build --build-arg APP_VERSION=1.0.0 -t federico-book-library:1.0.0 .

Il Containerfile utilizza Debian e avvia Hypnotoad in foreground sulla porta interna 8080. La versione è mostrata nel footer.

3. Avviare il sito

Dalla directory del repository, come utente normale (senza sudo):

podman run --rm \
  --name federico-book-library \
  --userns=keep-id \
  --user "$(id -u):$(id -g)" \
  -p 127.0.0.1:8080:8080 \
  -v "$PWD/data:/app/data:ro" \
  -v "$PWD/federico_book_portal.yml:/app/federico_book_portal.yml:ro" \
  localhost/federico-book-library:1.0.0

Aprire http://127.0.0.1:8080.

Il catalogo e il file YAML non devono essere incorporati nell'immagine: sono montati dall'host. La porta è pubblicata soltanto su 127.0.0.1 per non esporre direttamente Hypnotoad.

4. Eseguire una sincronizzazione dal container

podman run --rm \
  --userns=keep-id \
  --user "$(id -u):$(id -g)" \
  --env-file .env \
  -v "$PWD/data:/app/data:rw" \
  localhost/federico-book-library:1.0.0 \
  perl script/download_books.pl --download

Il sito rileva le modifiche al file JSON senza bisogno di essere riavviato.

Deploy in produzione

Per la produzione si consiglia:

1. Podman rootless con volumi persistenti per data/ e configurazione YAML privata.
2. Hypnotoad come server applicativo.
3. systemd utente per avviare il container web e per eseguire il downloader come servizio oneshot.
4. Un timer systemd per la sincronizzazione periodica (ad esempio ogni sei ore).
5. Un reverse proxy Nginx con HTTPS, che inoltri le richieste a 127.0.0.1:8080.

Con Podman 4.3 su Debian 12 è possibile usare normali unità systemd utente anche senza Quadlet. In caso di esecuzione senza sessione SSH attiva, verificare che l'utente abbia Linger=yes.

Importante: i servizi web e downloader devono montare la stessa directory persistente, rispettivamente in lettura (ro) e scrittura (rw). Il processo downloader deve ricevere BOOKWYRM_INSTANCE e BOOKWYRM_USERNAME anche dentro il container (ad esempio tramite --env-file oppure --env).

Per HTTPS dietro reverse proxy, configurare hypnotoad.proxy: 1 solo quando l'accesso diretto a Hypnotoad è limitato a un proxy attendibile.

Aggiornare l'applicazione

Per una nuova release, ad esempio 1.0.1:

prove -lv t/
podman build --build-arg APP_VERSION=1.0.1 -t federico-book-library:1.0.1 .
podman save --format docker-archive -o federico-book-library-1.0.1.tar localhost/federico-book-library:1.0.1

Trasferire il TAR sul server con scp (usando la porta SSH specifica del server, se diversa da 22), quindi importarlo come lo stesso utente rootless che avvia i container:

podman load -i federico-book-library-1.0.1.tar

Aggiornare il tag dell'immagine sia nel servizio web sia nel servizio downloader, quindi:

systemctl --user daemon-reload
systemctl --user restart federico-book-library.service
systemctl --user is-active federico-book-library.service

I nomi dei servizi qui sono esempi: devono corrispondere ai file .service effettivamente installati. Il timer non richiede modifiche se richiama sempre il servizio downloader con lo stesso nome.

Verificare il sito e la versione indicata nel footer. Conservare l'immagine precedente per un eventuale rollback del codice: eventuali modifiche incompatibili ai dati richiedono invece un backup separato.

Sicurezza e dati personali

Non pubblicare o includere nell'immagine:

• federico_book_portal.yml, che contiene il segreto Mojolicious.
• .env, che contiene la configurazione privata dell'installazione.
• data/books.json, che contiene il catalogo personale.
• Log, file temporanei, esportazioni di immagini container.

Controllare .gitignore e .containerignore prima del primo commit. I file ignorati ma già tracciati da Git devono essere rimossi dall'indice; un .gitignore non cancella i dati dalla cronologia precedente.

Struttura del progetto

Containerfile
cpanfile
.env.example
federico_book_portal.yml.example
lib/
public/
script/
  federico_book_portal
  download_books.pl
t/
templates/
data/                  # dati privati, non versionati
logs/                  # log privati, non versionati

Licenza

Da definire prima della pubblicazione: aggiungere un file LICENSE con la licenza scelta e verificare eventuali attribuzioni necessarie per risorse e dipendenze di terze parti.