wiki/Catalogue-Self-Hosted/apps/app-bookhaven.md

---
title: BookHaven
created: 2026-06-07
updated: 2026-06-07
type: app
tags: [catalogue, books, epub, reader, opds, python, oidc, rbac]
confidence: medium
contested: false
sources: [https://selfh.st/apps/?tag=books, https://github.com/HrBingR/BookHaven]
---

# 📚 BookHaven

> **Lecteur EPUB browser-based avec gestion de bibliothèque** : scannez votre dossier local d'EPUBs, lisez et téléchargez depuis n'importe quel device, avec support OPDS et OIDC.

| Métadonnée | Valeur |
| :--- | :--- |
| **Site web** | [github.com/HrBingR/BookHaven](https://github.com/HrBingR/BookHaven) |
| **GitHub** | [HrBingR/BookHaven](https://github.com/HrBingR/BookHaven) |
| **License** | GPL-3.0 |
| **Langage** | Python (backend), TypeScript/Vue (frontend) |
| **Étoiles** | 115 ⭐ |
| **Dernière MAJ** | 2025-11 (v1.7.x) |
| **Catégorie** | [[cat-books]] |

## Description

BookHaven est un **gestionnaire/lecteur de bibliothèque EPUB** développé comme **alternative minimale** aux solutions type Calibre-Web ou Kavita. L'auteur (HrBingR) voulait quelque chose de plus simple à déployer et plus moderne côté UI. Le pari est tenu : stack légère (Python + Vue), DB au choix (SQLite/MySQL/PostgreSQL), cache Redis, image Docker officielle.

L'application **scanne automatiquement** un dossier local d'EPUBs (intervalle configurable + scan manuel), extrait les métadonnées (titre, auteur, série, couverture) **sans toucher aux fichiers originaux** — toutes les modifications sont stockées en base. C'est un choix architectural important : BookHaven est **non-destructif**.

Côté fonctionnalités : **lecteur EPUB dans le navigateur** (basé sur Readium ou epub.js), **téléchargement** direct, **recherche** plein texte (auteur, titre, série), **filtres** par statut (favoris, terminés, en cours), **page auteur** avec grille alphabétique, **uploads** utilisateurs (avec correction de métadonnées post-upload), **RBAC basique** (admin, editor, user), **requêtes de livres** (les users peuvent demander l'ajout d'un titre), **OIDC** pour l'authentification centralisée, **OPDS** pour la lecture depuis des apps e-reader (KOReader, Moon+ Reader, etc.), et **support Cloudflare Access** pour bypass le login.

**Points forts** : non-destructif (métadonnées en DB, fichiers intacts), OIDC + RBAC + Cloudflare Access prêts à l'emploi, OPDS fonctionnel, image Docker officielle, README clair, install Docker en 4 étapes.

**Points faibles** : **EPUB uniquement** (pas de PDF, MOBI, AZW3), **bus factor 1** (un seul mainteneur), rythme de release lent (~1 release majeure/an), stack Python + Node à maintenir pour le build frontend, projets plus complets et matures (Calibre-Web, Kavita) existent.

## Installation

### Via Docker (recommandé)

L'image `hrbingr/bookhaven` est sur Docker Hub. La stack officielle inclut MySQL + Redis (mais SQLite fonctionne aussi).

```yaml
# docker-compose.yml
services:
  bookhaven:
    image: hrbingr/bookhaven:latest
    container_name: bookhaven
    restart: unless-stopped
    ports:
      - "5000:5000"
    env_file: .env
    volumes:
      - ./data:/app/data
      - /chemin/vers/epubs:/library
    depends_on:
      - mysql
      - redis

  mysql:
    image: mysql:8-alpine
    restart: unless-stopped
    environment:
      MYSQL_DATABASE: bookhaven
      MYSQL_USER: bookhaven
      MYSQL_PASSWORD: change-me
      MYSQL_ROOT_PASSWORD: change-me-root
    volumes:
      - bookhaven_db:/var/lib/mysql

  redis:
    image: redis:7-alpine
    restart: unless-stopped

volumes:
  bookhaven_db:
```

### Installation manuelle

Cloner le dépôt, `cp compose.exmaple.yml compose.yml` (sic, le repo contient une coquille), `cp .env.example .env`, lancer la stack.

## Configuration

1. Renommer `compose.yml.example` → `compose.yml` et `.env.example` → `.env`.
2. Choisir la base de données (`SQLITE`, `MYSQL` ou `POSTGRES` dans `.env`).
3. Définir `BASE_URL`, `APP_PORT` et un `SECRET_KEY` fort.
4. Configurer OIDC si vous avez un [[app-authentik]] ou Keycloak (sections dédiées dans `.env`).
5. Activer Cloudflare Access (`CF_ACCESS_ENABLED=true`) si vous êtes derriere un tunnel.
6. Premier démarrage : créer le compte admin, configurer le chemin de scan EPUB.
7. Activer OPDS via `OPDS_ENABLED=true` et donner l'URL à votre liseuse / app reader.

## Alternatives

### Open source
- [[app-calibre]] — Monstre sacré, EPUB/PDF/MOBI/AZW3, stack Python lourde
- **Calibre-Web** — Front web pour une DB Calibre existante, mature
- **Kavita** — Lecteur comics/manga/LN avec OPDS, interface moderne
- [[app-stump]] — Alternative Rust à Kavita
- **LibreShelves** — Outil minimaliste, EPUB/PDF, plus jeune que BookHaven

### Propriétaires
- **Calibre** (desktop, gratuit mais pas self-hostable en tant que serveur) — Le modèle historique
- **BookFusion** — Lecteur EPUB en ligne, freemium
- **Tolino** — Liseuse + écosystème cloud propriétaire

## Sécurité

- ✅ **OIDC** supporté (déléguer l'auth à Keycloak/Authentik)
- ✅ **RBAC** (admin/editor/user) — limiter qui peut uploader ou demander
- ⚠️ **Bus factor 1** : mainteneur unique, pas d'organisation derrière
- ✅ Pas d'auth native par défaut → mettre derrière HTTPS via [[app-caddy]] ou [[app-traefik]]
- ⚠️ **Uploads utilisateurs** : attention aux EPUB vérolés (XSS via EPUB malformé)
- ✅ Métadonnées stockées en DB = fichiers originaux intacts (rollback trivial)
- ⚠️ Releases peu fréquentes : rester attentif aux CVE Python/Node

## Ressources

- [GitHub HrBingR/BookHaven](https://github.com/HrBingR/BookHaven)
- [Reddit — présentation](https://www.reddit.com/r/selfhosted/comments/1ikog7v/bookhaven_a_selfhosted_epub_library_management/)
- [selfh.st Books](https://selfh.st/apps/?tag=books)

## Pages Liées

- [[cat-books]] — Catégorie Books
- [[app-calibre]] — Alternative plus complète (mais plus lourde)
- [[app-kavita]] — Lecteur moderne avec OPDS, EPUB/CBZ
- [[app-authentik]] — SSO/OIDC à brancher
- [[recettes-docker-compose]] — Templates Docker