Fable

A personal fork of [Booklore] with extended features, UI customizations, and an optional AI-powered comic panel detection service.

Advisory: This is a personal project, shared as-is. It is 100% vibe-coded. I am not a developer. I may or may not update it. I may or may not read the Issues. I will not delete it if I get upset, I'm always upset. Please fork freely and do whatever you like with it. I am not taking requests.

---

Contents

• Under the Hood
• Main Features
• Installation
  • Requirements
  • Fresh Install
  • Update Existing Install
  • Install Without AI
• Sample .env
• Sample docker-compose.yml
• Saving Your Data
  • Application Settings
  • Book Files and Covers
• AI Panel Detection — Quick Start
• Familiarization Guide
• Screenshots

---

Under the Hood

This fork includes a number of targeted fixes to improve reliability, memory efficiency, and UI responsiveness — particularly for larger libraries. No upstream features were removed.

• ~50% less peak memory per image operation — reduced pixel decode ceiling and replaced a lazy image scaler that held source buffers in memory with a direct bicubic draw that flushes source memory immediately
• Native image buffers always released — flush calls are now guaranteed via finally blocks across all thumbnail generation paths, preventing silent leaks during error conditions
• No more zombie subprocesses — KEPUB conversion and CBR metadata extraction processes are now properly terminated in finally blocks; failed or timed-out operations can no longer accumulate as orphaned OS processes
• Komga series endpoints no longer fall back to catalog-wide scans — series pages, series detail, and series book lists now resolve the requested series name first and fetch only the matching books; the all-libraries series view no longer builds an in-memory map from a full eager-loaded catalog scan
• Summary list responses avoid heavy metadata loads — list and paged summary fetches now use a lighter summary graph, while long descriptions stay lazy until a detail flow actually requests them
• Browser views now start paged-first — opening All Books, a library, a shelf, or Not Shelfed no longer has to bootstrap the full catalog just to render the first screen; sidebar counts and topbar search now use lightweight paged queries as well
• Covers load once, not on every navigation — browser-cache headers added to all image endpoints (7-day TTL for book covers, 1-hour for author images); the existing cache-busting URL timestamps ensure stale images are never served
• Sidebar navigation no longer rebuilds the book grid — the Angular route reuse strategy now correctly stores and reattaches the "All Books" and "Not Shelfed" views, preventing unnecessary cover reloads when switching sidebar sections
• HTTP download safety — downloaded image payloads are now rejected if they exceed 5 MB before being handed to the image decoder; network connections for image fetching are bounded by connect (10 s) and read (30 s) timeouts, preventing runaway thread holds on slow or unresponsive sources

---

Main Features

• Comic Panel Detection AI — Detects and saves panel flow data for CBZ/CBR comics using a bundled YOLO-based AI model. Enables panel-by-panel navigation in the reader.
• ComicVine URL Issue Navigation — In metadata search, paste a ComicVine volume or issue URL and optionally provide an issue number or inclusive range (for example 46 or 43-171) to resolve exact ComicVine issue matches.
• ComicVine Batch Issue Sequencing — In custom metadata fetch for multi-book selections, you can use the same ComicVine source URL plus issue number/range inputs and Fable will assign sequential issues across the selected books while keeping review-mode workflows.
• Directory Explorer — Browse books by actual library folders from a collapsible folder panel in All Books and library views, then use the reset button beside the folder toggle to clear the active folder scope while keeping the larger book view available.
• Currently Reading Dashboard Panel — Add an optional Currently Reading scroller from Dashboard Settings and populate it from a book's More Actions menu to keep a hand-picked reading shortlist on the home screen.
• Custom Theme Colors — Use preset palettes or set custom primary and surface colors with a color picker or pasted hex value; theme preferences are saved per user.
• Adjustable Cover Preview Panel — Toggle the right-side cover preview on or off in Settings.
• Customizable Upper Toolbar — Add, remove, and reorder toolbar buttons; insert separators. Drag-and-drop support.
• Adjustable Side Panels — Resizable left and right sidebars.
• Drag-and-Drop Sidebar Sorting — Turn on Re-order mode to drag left sidebar headings and rows on desktop or mobile without affecting normal sidebar navigation.
• Settings Backup & Restore — Export and import your full application settings.
• User-Defined Media Types — Create custom media types (Magazines, Catalogs, Textbooks, etc.) and filter by them.
• Title Row Controls — Fine-grained tweaks for book card title display.
• Sidebar Repositioned Controls — Settings and Language Selection moved to the bottom of the left sidebar.
• Telemetry Removed — All upstream telemetry, support icons, and removed documentation links have been stripped out.
• OIDC / Forward Auth Support — OpenID Connect login and proxy forward-auth support included.
• Language Selection — Multi-language support with in-app language switcher.

---

Installation

Requirements

• Docker and Docker Compose
• MariaDB (included in the provided Compose file)

Fresh Install

# 1. Download the Compose file
curl -O https://raw.githubusercontent.com/opensourcefan/Fable/develop/docker-compose.yml

# 2. Create your .env file (see Sample .env below)

# 3. Pull and start
docker compose pull
docker compose up -d

# 4. If AI is enabled, pull and start the AI container separately
docker compose pull app-ai-panel
docker compose up -d app-ai-panel

Update Existing Install

curl -O https://raw.githubusercontent.com/opensourcefan/Fable/develop/docker-compose.yml
docker compose pull
docker compose up -d

# If AI is enabled:
docker compose pull app-ai-panel
docker compose up -d app-ai-panel

Optional RAR Binary For CBR Metadata Writes

If you want Fable to preserve .cbr files during metadata writes instead of falling back to a slower .cbz conversion, place a compatible Linux rar binary at ./docker/rar/rar before starting the container.

• The repository docker-compose.yml now mounts ./docker/rar into the container at /opt/fable-rar.
• The container entrypoint automatically exports FABLE_RAR_BIN=/opt/fable-rar/rar when that file exists and is executable.
• If no rar binary is provided, Fable keeps its current fallback behavior and may convert .cbr to .cbz when writing embedded metadata.

Install Without AI

Omit COMPOSE_PROFILES=ai from your .env. No AI image will be pulled and no model files will be downloaded. AI features can be left disabled in Settings > AI Panel Detection.

---

Sample .env

# User / Group IDs for file ownership
APP_USER_ID=1000
APP_GROUP_ID=1000

# Timezone
TZ=America/Vancouver

# Database connection
DATABASE_URL=jdbc:mariadb://mariadb:3306/fable
DB_USER=fable
DB_PASSWORD=ChangeMe@$@P

# MariaDB container
DB_USER_ID=1000
DB_GROUP_ID=1000
MYSQL_ROOT_PASSWORD=ChangeMe@$@P
MYSQL_DATABASE=fable
REMOTE_USER_PASSWORD=ChangeMe@$@P

# Storage type: LOCAL (default) or NETWORK (all data written to MariaDB only)
#DISK_TYPE=NETWORK

# AI Panel Detection (optional — remove or comment out to disable AI)
COMPOSE_PROFILES=ai
AI_SERVICE_BASE_URL=http://app-ai-panel:8080
AI_PANEL_PORT=18080

---

Sample docker-compose.yml

services:
  mariadb:
    image: mariadb:11
    container_name: fable-db
    restart: unless-stopped
    environment:
      MYSQL_ROOT_PASSWORD: ${MYSQL_ROOT_PASSWORD}
      MYSQL_DATABASE: ${MYSQL_DATABASE}
      MYSQL_USER: ${DB_USER}
      MYSQL_PASSWORD: ${DB_PASSWORD}
    volumes:
      - db-data:/var/lib/mysql
    networks:
      - fable-net

  app-backend:
    image: ghcr.io/opensourcefan/fable:latest
    container_name: app-backend
    restart: unless-stopped
    depends_on:
      - mariadb
    environment:
      DATABASE_URL: ${DATABASE_URL}
      DB_USER: ${DB_USER}
      DB_PASSWORD: ${DB_PASSWORD}
      APP_USER_ID: ${APP_USER_ID:-1000}
      APP_GROUP_ID: ${APP_GROUP_ID:-1000}
      TZ: ${TZ:-UTC}
      AI_SERVICE_BASE_URL: ${AI_SERVICE_BASE_URL:-}
    ports:
      - "6060:6060"
    volumes:
      - ./books:/books
      - ./data:/app-data
      - ./bookdrop:/bookdrop
      - ./docker/rar:/opt/fable-rar:ro  # Optional: mount a compatible Linux rar binary at ./docker/rar/rar for in-place CBR metadata writes
    networks:
      - fable-net

  app-ai-panel:
    image: ghcr.io/opensourcefan/fable-panel-ai:latest
    container_name: app-ai-panel
    restart: unless-stopped
    profiles:
      - ai
    ports:
      - "${AI_PANEL_PORT:-18080}:8080"
    volumes:
      - ./data/ai-models:/models
    networks:
      - fable-net

volumes:
  db-data:

networks:
  fable-net:

Note: This is a representative sample. Always use the docker-compose.yml pulled from the repository for the most up-to-date configuration.

---

Saving Your Data

Fable stores your data in two places. Back up both to ensure a complete recovery.

Application Settings

Your admin configuration (libraries, users, shelves, metadata settings, etc.) lives in the MariaDB database.

Export via the UI — Go to Settings → Global Preferences → Settings Transfer and click Export. This downloads a fable-settings-*.json file you can re-import on the same or a new instance.

Full database backup (recommended for complete protection) — Exports everything including all book metadata, read progress, and shelf assignments:

# Load your .env variables, then run:
docker exec mariadb mariadb-dump \
  --single-transaction --quick --no-tablespaces \
  -u root -p"$MYSQL_ROOT_PASSWORD" \
  fable > "fable_backup_$(date +%Y%m%d_%H%M%S).sql"

See docs/mariadb-backup-restore.html for the full backup, restore, and automation guide.

Book Files and Covers

Your actual book files, cover images, and thumbnails are not stored in the database. Back them up separately:

Directory	Contents
./books/	All book files
./data/	Cover images, thumbnails, author images, AI model
./bookdrop/	Bookdrop inbox (if in use)

A simple full backup copies all three:

tar -czf fable-files-backup-$(date +%Y%m%d).tar.gz ./books ./data ./bookdrop

---

AI Panel Detection — Quick Start

1. Add COMPOSE_PROFILES=ai to your .env
2. Pull and start all services (see Installation above)
3. Open Settings > AI Panel Detection
4. Enable AI Panel Detection and wait for status to show READY
   • The model is bundled inside the AI container image
   • On first start it is automatically seeded to ./data/ai-models/best.pt
   • No manual file placement is required
5. Open a comic in the reader and use the AI button to scan the current book
6. Optionally run Manual Panel Detection Scan in AI settings to batch-process all comics

AI Notes

• The AI compose profile is opt-in. Omitting COMPOSE_PROFILES=ai skips the AI image entirely.
• The AI container uses CPU-only inference to keep the image size manageable.
• If the model fails to load, use the Reload Model button in Settings.
• If running Fable outside Docker, set AI_SERVICE_BASE_URL to the host-mapped endpoint (e.g., http://localhost:18080).

---

Familiarization Guide

New to Fable? A complete Familiarization Guide is available in the docs/ folder:

• Fable-Familiarization-Guide.pdf — Printable PDF version
• Fable-Familiarization-Guide.html — Browser-viewable HTML version

The guide is written for users of all experience levels and covers every feature — libraries, importing, reading, shelves, metadata, search, AI panel detection, OPDS, user management, settings, backups, and more. Each section includes what you can do, what you can't do, and things to be careful about.

The app's footer PDF button links to this same guide file directly. If you want the guide to behave like a normal imported PDF in the built-in reader, copy the PDF into a library or into BookDrop and import it like any other asset.

Maintenance rule: the HTML guide is the source of truth. When the guide changes, regenerate the PDF from that HTML and update this README section in the same change so the repository docs stay in sync.

---

Screenshots

Automated Maintenance

Dependabot is configured to watch the Gradle backend, the UI npm manifest, the AI panel's pip requirements, the Dockerfiles, the Docker Compose files, and GitHub Actions workflows. Patch and minor Dependabot pull requests are labeled for unattended merge only after the develop CI workflow succeeds, so routine maintenance does not depend on manual PR handling or branch protection. Repository-side GitHub vulnerability alerts and automated security fixes should remain enabled. The Gradle automation intentionally ignores com.github.RouHim:jaudiotagger because that JitPack-hosted dependency currently triggers Dependabot source-authentication failures; it should be reviewed manually until it is replaced with a Dependabot-compatible source. The AI panel's pillow dependency now tracks secure 12.x releases directly, so future patch and minor updates can flow through the normal unattended Dependabot path. Workflow-file dependency updates are still surfaced automatically, but GitHub's default Actions token does not auto-merge them, so those updates remain the one part of the maintenance flow that still needs a workflow-capable automation token or GitHub App if you want them merged unattended as well.