Novela

Novela is a self-hosted web application for managing and reading a personal digital library. It supports EPUB, PDF, and CBR/CBZ, with metadata editing, reading progress tracking, a web scraper/converter, and Dropbox backups.

What Novela Provides

Library

• Import and indexing for EPUB, PDF, CBR/CBZ
• Drag-and-drop import from library page or home page
• Cover extraction and caching (EPUB, PDF first page, CBR/CBZ first page); manual cover upload for EPUB
• Metadata editing: title, author, publisher, series, volume, tags, genres, sub-genres, star rating, publication status
• Publication statuses: Complete, Ongoing, Temporary Hold, Long-Term Hold
• Want-to-read flag and archived flag
• 1–5 star ratings (stored in EPUB OPF / CBZ ComicInfo.xml / DB)
• Download individual files

Views and Navigation

• Home dashboard: continue reading, unread shorts/novels, read shorts/novels
• Library grid/list views with search (title, author, genre)
• Series view: grouped by series with volume order
• Duplicates view: groups books with matching title+author
• Incomplete view: books not marked Complete
• New view: recently imported books awaiting review; bulk "Remove from New" action
• Following page: track external URLs per author

Bulk Import

• /bulk-import page: import multiple files at once with filename-based metadata parsing
• Free-text %placeholder% pattern editor (e.g. %series% - %volume% - %title% - %year%)
• Available placeholders: %series%, %volume%, %title%, %year%, %month%, %day%, %author%, %publisher%, %ignore%
• Colored chips: click to insert at cursor or drag onto the pattern input
• Shared metadata fields (author, publisher, status, genres, tags) override filename-parsed values
• Preview table with editable cells before importing
• Duplicate detection: checks title+author against existing library; duplicate rows highlighted, skipped by default
• Batched upload (5 files per request) with progress bar
• Batched bulk delete (20 files per request) with progress bar

Reader

• EPUB reader: chapter navigation, configurable content width and text colour, bookmarks
• PDF reader: page-by-page rendering
• CBR/CBZ reader: page-by-page image rendering
• Reading progress saved per book (resume where you left off)
• Bookmarks with notes; listed in library sidebar section

EPUB Tools

• EPUB editor (/library/editor/{filename}): edit chapter HTML in the browser
• Book Builder (/builder): create EPUB books from scratch with a WYSIWYG editor; publish directly to library
• Web Grabber (/grabber): scrape and convert web fiction to EPUB; site credentials management
• Converter (/convert): convert a URL to EPUB; duplicate detection before conversion

Analytics

• Statistics dashboard: reads by month / day / hour, genre and publisher breakdowns, top books, read history

Backups

• Dropbox backup: versioned snapshots with object-level deduplication and retention policy
• OAuth2 flow (preferred) or legacy access token
• Scheduled background backups (configurable interval)
• Live progress indicator during backup runs
• PostgreSQL dump included in each backup

Sidebar

• Disk usage warning: amber ≥ 85% or < 2 GB free; red ≥ 95% or < 500 MB free

Tech Stack

• FastAPI
• Jinja2 templates + vanilla JavaScript
• PostgreSQL 16
• Docker / Docker Compose style deployment

Repository Layout

• containers/novela/ — application code (routers, templates, static assets, migrations)
• stack/ — deployment stack files and environment configuration
• docs/ — technical status and changelog documentation
• build-and-push.sh — helper script for container build/push

Quick Start (Development)

1. Configure environment values in stack/novela.env.
2. Start the stack using your preferred Docker workflow (Compose/Portainer stack).
3. Open the app and complete backup credential setup on /backup if needed.

Key Environment Variables

• POSTGRES_DB
• POSTGRES_USER
• POSTGRES_PASSWORD
• NOVELA_MASTER_KEY
• CONFIG_DIR
• LIBRARY_DIR (optional override)

Documentation

• Technical status: docs/TECHNICAL.md
• Develop changelog: docs/changelog-develop.md

Disclaimer

This project was developed entirely with AI-assisted implementation workflows. Use it at your own discretion and responsibility, and validate behavior, security, and data handling for your environment before production use.

Status

This repository is actively evolving. The develop documentation reflects implemented behavior in the current codebase.