Bookish (fork Docker)

Convertitore e reader di ebook self-hostato — Flask, Pandoc, WeasyPrint, SQLite.

Questo repository è un fork di Bookish pensato per girare in Docker. L'originale resta in bookish/.

Avvio con Docker

cp .env.example .env
# modifica BOOKISH_SECRET in .env
docker compose up --build -d

Apri http://localhost:5000.

Dati persistenti (SQLite, upload, convertiti) stanno nel volume bookish-data montato su /data.

docker compose logs -f
docker compose down

Variabili d'ambiente

Variabile	Default	Descrizione
BOOKISH_SECRET	(obbligatorio se DEBUG=false)	Secret Flask
BOOKISH_DEBUG	false in Docker, true con run.sh	Debugger Werkzeug
BOOKISH_DATA_DIR	directory del progetto / /data in Docker	Upload, convertiti, bookish.db
BOOKISH_CLEANUP_HOURS	1	Ore prima di cancellare i file temporanei
PORT	5000	Porta host (compose) / bind gunicorn
BOOKISH_AUTH_USERNAME	(vuoto)	Se impostato insieme a BOOKISH_AUTH_PASSWORD, abilita l'autenticazione Basic su tutte le route (tranne healthz/static)
BOOKISH_AUTH_PASSWORD	(vuoto)	Password dell'autenticazione Basic
BOOKISH_RATE_LIMIT_UPLOAD	20	Massimo upload per IP/ora (0 disabilita)
FORWARDED_ALLOW_IPS	127.0.0.1	IP dei proxy fidati (Caddy/nginx) per rispettare X-Forwarded-For

Avvio locale (senza Docker)

Serve Python 3.12 e Pandoc di sistema.

sudo apt install pandoc
python3 -m venv .venv
.venv/bin/pip install -r requirements.lock  # o requirements.txt in sviluppo
./run.sh

In locale BOOKISH_DEBUG è true e il secret di default è accettato. Non esporre questa modalità in LAN.

Dipendenze e lockfile

• requirements.txt — dipendenze dirette (per lo sviluppo).
• requirements.lock — lock completo (dirette + transitive) generato con pip-compile, usato dalla build Docker per build riproducibili.

Per aggiornare il lock (in Python 3.12, come l'immagine):

pip install pip-tools
pip-compile --strip-extras --no-hash --output-file requirements.lock requirements.txt

La build Docker verifica che requirements.lock coincida con l'hash pinnato in docker-compose.yml (REQUIREMENTS_CHECKSUM, R4b): se aggiorni le dipendenze, aggiorna anche il pin:

sed -i "s/[a-f0-9]\{64\}/$(sha256sum requirements.lock | awk '{print $1}')/" docker-compose.yml

(trova la riga REQUIREMENTS_CHECKSUM: — primo hash del file). La CI (.github/workflows/checksum.yml) fallisce se il pin non coincide col lock.

Note sul container

• Gunicorn, 1 worker + thread: i task SSE vivono in memoria del processo.
• Utente non-root bookish (uid 1000).
• Conversione PDF può richiedere fino a 5 minuti (timeout gunicorn 300s).
• Nessuna autenticazione di default: adatto a LAN fidata dietro reverse proxy.

Sicurezza opzionale

Per esporre Bookish anche solo in LAN, abilita l'autenticazione Basic e limita gli upload:

# .env
BOOKISH_AUTH_USERNAME=admin
BOOKISH_AUTH_PASSWORD=una-password-lunga
BOOKISH_RATE_LIMIT_UPLOAD=20   # upload/ora per IP

• L'autenticazione Basic è la più semplice ma non cifra la password: usala solo su HTTP dietro un reverse proxy HTTPS (Caddy/nginx).
• Il rate limit è in-memory (per processo, single-worker): adatto a uso personale; per difese più robuste metti un limite a livello di proxy.
• Vengono applicati header di sicurezza su ogni risposta: Content-Security-Policy (default-src 'self', nessuna allowlist CDN), X-Content-Type-Options: nosniff, X-Frame-Options: SAMEORIGIN, Referrer-Policy: no-referrer.
• Tutti i JavaScript del reader (epub.js, pdf.js+worker, JSZip, DOMPurify) sono self-hosted in static/vendor/ → funziona anche offline, senza CDN.
• I contenuti HTML del reader vengono sanitizzati lato client (DOMPurify self-hosted in static/vendor/).

API extra

GET /healthz — healthcheck Docker ({"status":"ok"}).

Licenza

MIT