Your Personal, Self-Hosted Book Reading Interface.

Blombook is a private, single-user application designed for individuals who want a polished, highly performant, and immersive environment for reading their personal text and markdown book collections. With a focus on a distraction-free user experience, mobile-responsive layouts, and flat-file server-side storage, Blombook puts you in complete control of your library.

View Screenshots

Library View

Book Reader

Table of Contents

• Table of Contents
• Key Features
  • Core Functionality
  • Immersive Reading
  • Flexibility & Integration
• Installation & Setup
  • Docker (Recommended)
    • Deployment Options
    • Quick Start (Pre-built Image)
  • Python
• Usage Guide
  • Uploading Books
  • Reading Progress
  • Cover Images
• Technical Details
• Disclaimer
• License

Key Features

Core Functionality

• Flat-File Storage: Books and their metadata are stored entirely using standard text files and JSON. No complex database setup is required.

• Chunked Uploads: Upload massive text files effortlessly. The server intelligently processes file chunks to ensure stability.

• Library Management: Edit book metadata, update cover images, and easily manage your collection from a centralized library view.

Immersive Reading

• Static Pagination: Enjoy a font-size-independent pagination system that provides a consistent, physical book-like feel across all your devices.

• Responsive Layout: The reader gracefully transitions from a strict 2:3 aspect ratio desktop view to a full-screen, edge-to-edge mobile experience.

• Progress Tracking: Blombook automatically tracks your reading status (unread, reading, or read) and remembers your current spread, so you can always pick up right where you left off.

Flexibility & Integration

• High-Resolution Covers: Upload custom cover images or let the application automatically generate a stylish gradient placeholder if none is provided.

• Markdown Support: The reader beautifully renders standard markdown formatting, bringing your plain text books to life.

Installation & Setup

You can choose to either use Blombook in a Docker container (recommended) or run it directly with Python.

Docker (Recommended)

Note

DOCKER SUPPORT COMING SOON

This is the recommended method for using Blombook. Pre-built images are available on GitHub Container Registry.

Prerequisite	Notes
Docker	Required

Deployment Options

Option	Image Tag	Use Case
Latest Stable	latest (default)	Production use, tracks the latest GitHub release
Development	Local build	Contributing, modifying source code

Quick Start (Pre-built Image)

1. Download the required files

   Create a folder for Blombook (e.g., blombook), then download the docker-compose.yml file from the latest release and place it inside it.

2. Start the server
   Start the Docker container (make sure you are inside the folder where you placed the docker-compose.yml file):

   docker compose up -d

   You may need to use sudo or run the command from a terminal with elevated privileges.

   Now, open your web browser and navigate to http://localhost:7842. All settings and metadata are saved to the data folder inside your Blombook directory.

3. Shutting down the container

   docker compose down

Python

Prerequisite	Notes
Python 3.10+	Required
Node.js	Required for building the frontend

1. Clone the repository

   git clone https://github.com/mrblomblo/blombook.git
   cd blombook

2. Build the frontend

   npm install
   npm run build

3. Create a Python virtual environment and install dependencies

   python -m venv venv
   source venv/bin/activate  # On Windows, use `venv\Scripts\activate`
   pip install -r requirements.txt

4. Start the server

   ./server/run.sh

   Now, open your web browser and navigate to http://localhost:7842.

Usage Guide

Uploading Books

To add a new book to your library, click the upload button in the Library view. You can provide a title, author, description, and the raw text or markdown file. Blombook supports chunked uploads, ensuring even the largest text files are uploaded smoothly.

Reading Progress

Your reading progress is saved automatically. The application tracks whether a book is unread, currently being read, or finished. When you open a book, you will be brought directly back to your last viewed spread.

Cover Images

You can customize the appearance of your books in the library by uploading high-resolution cover images. If no cover image is uploaded, Blombook will generate a fallback gradient cover based on the selected cover style index.

Technical Details

Component	Technology
Backend	FastAPI (Python)
Frontend	React 19, Tailwind CSS (Vite)
Storage	Local filesystem (JSON index and .txt files)
Supported Formats	TXT, MD

Disclaimer

This is a self-hosted, single-user application. As the administrator, you are exclusively responsible for all content you upload and manage using this software.

Ensure your use complies with all applicable laws, especially regarding copyright.

License

This project is licensed under the MIT License. See the LICENSE file for details.