📚 MyBibliotheca

MyBibliotheca is a self-hosted personal library and reading-tracker—your open-source alternative to Goodreads, StoryGraph, and Fable! It lets you log, organize, and visualize your reading journey. Add books by ISBN, track reading progress, log daily reading, and generate monthly wrap-up images of your finished titles.

---

✨ Features

• 📖 Add Books: Add books quickly by ISBN with automatic cover and metadata fetching. Now featuring bulk-import from Goodreads and other CSV files!
• ✅ Track Progress: Mark books as Currently Reading, Want to Read, Finished, or Library Only.
• 📅 Reading Logs: Log daily reading activity and maintain streaks.
• 🖼️ Monthly Wrap-Ups: Generate shareable image collages of books completed each month.
• 🔎 Search: Find and import books using the Google Books API.
• 📱 Responsive UI: Clean, mobile-friendly interface built with Bootstrap.
• 🔐 Multi-User Support: Secure authentication with user data isolation. (COMING SOON)
• 👤 Admin Management: Administrative tools and user management. (COMING SOON)

---

🚀 Getting Started

📦 Run with Docker

MyBibliotheca can be run completely in Docker — no need to install Python or dependencies on your machine.

✅ Prerequisites

• Docker installed
• Docker Compose installed

🔁 Option 1: One-liner (Docker only)

docker run -d \
  --name mybibliotheca \
  -p 5054:5054 \
  -v /path/to/data:/app/data \
  -e TIMEZONE=America/Chicago \
  -e WORKERS=6 \
  --restart unless-stopped \
  pickles4evaaaa/mybibliotheca:1.1.1

🔁 Option 2: Docker Compose

Create a docker-compose.yml file:

services:
  mybibliotheca:
    image: pickles4evaaaa/mybibliotheca:1.1.1
    container_name: mybibliotheca
    ports:
      - "5054:5054"
    volumes:
      - /path/to/data:/app/data      # ← bind-mount host
    restart: unless-stopped
    environment:
      - TIMEZONE=America/Chicago  # ✅ Set your preferred timezone here
      - WORKERS=6  # Change to the number of Gunicorn workers you want

Then run:

docker compose up -d

💡 You may need to restart your docker container after the initial setup. This is a bug that will be worked on.

🔧 Configurable Environment Variables

Variable	Description	Default / Example
SECRET_KEY	Flask secret key for sessions	auto-generated
SECURITY_PASSWORD_SALT	Password hashing salt	auto-generated
TIMEZONE	Sets the app's timezone	America/Chicago
WORKERS	Number of Gunicorn worker processes	6

---

🔐 Authentication & User Management (COMING SOON)

First Time Setup

When you first run MyBibliotheca, you'll be prompted to complete a one-time setup:

1. Access the application at http://localhost:5054 (or your configured port)
2. Complete the setup form to create your administrator account:
3. Choose an admin username
4. Provide an admin email address
5. Set a secure password (must meet security requirements)
6. Start using MyBibliotheca - you'll be automatically logged in after setup

✅ Secure by Design: No default credentials - you control your admin account from the start!

Password Security

• Strong password requirements: All passwords must meet security criteria.
• Automatic password changes: New users are prompted to change their password on first login.
• Secure password storage: All passwords are hashed using industry-standard methods.

Migration from V1.x

Existing single-user installations are automatically migrated to multi-user:

• Automatic database backup created before migration
• All existing books are assigned to an admin user (created via setup)
• No data is lost during migration
• V1.x functionality remains unchanged
• Setup required if no admin user exists after migration

---

🐍 Install from Source (Manual Setup)

✅ Prerequisites

• Python 3.8+
• pip

🔧 Manual Installation

1. Clone the repository

bash git clone https://github.com/pickles4evaaaa/mybibliotheca.git cd mybibliotheca

1. Create a Python virtual environment

bash python3 -m venv venv source venv/bin/activate

1. Install dependencies

bash pip install -r requirements.txt

1. Setup data directory (ensures parity with Docker environment)

On Linux/macOS: bash python3 setup_data_dir.py

On Windows: ```cmd REM Option 1: Use Python script (recommended) python setup_data_dir.py

REM Option 2: Use Windows batch script setup_data_dir.bat ```

This step creates the data directory and database file with proper permissions for your platform.

1. Run the app

On Linux/macOS: bash gunicorn -w NUMBER_OF_WORKERS -b 0.0.0.0:5054 run:app

On Windows: ```bash REM If gunicorn is installed globally gunicorn -w NUMBER_OF_WORKERS -b 0.0.0.0:5054 run:app

REM Or use Python module (more reliable on Windows) python -m gunicorn -w NUMBER_OF_WORKERS -b 0.0.0.0:5054 run:app ```

💡 No need to manually set up the database — it is created automatically on first run.

⚙️ Configuration

• By default, uses SQLite (books.db) and a simple dev secret key.
• For production, you can configure:
• SECRET_KEY
• DATABASE_URI

via environment variables or .env.

---

🗂️ Project Structure

MyBibliotheca/
├── app/
│   ├── __init__.py           # App factory and setup
│   ├── admin.py              # Admin routes and logic
│   ├── auth.py               # Authentication routes and logic
│   ├── debug_utils.py        # Debugging utilities
│   ├── forms.py              # WTForms definitions
│   ├── models.py             # SQLAlchemy/ORM models (legacy)
│   ├── routes.py             # Main application routes
│   ├── utils.py              # Utility functions
│   ├── static/               # CSS, JS, images, icons
│   └── templates/            # Jinja2 HTML templates
│       ├── add_book_new.html
│       ├── base.html
│       ├── ... (other pages)
│       ├── admin/            # Admin templates
│       ├── auth/             # Auth templates
│       └── community_stats/  # Community stats templates
├── data/                     # App data (e.g. Redis, SQLite)
├── scripts/                  # Migration and setup scripts
├── tests/                    # Automated tests
├── requirements.txt          # Python dependencies
├── run.py                    # App entry point
├── docker-compose.yml        # Docker orchestration
├── Dockerfile                # Docker build file
├── README.md                 # Project documentation
└── USER_GUIDE.md             # End-user documentation

• app/: Main application code, routes, logic, templates, and static files.
• data/: Database and runtime data (Redis, SQLite, etc.).
• scripts/: Utilities for migration, setup, and admin tasks.
• tests/: Automated test suite.
• static/: CSS, JS, images, and fonts for the UI.
• templates/: All HTML templates for rendering pages.
• README.md: Project overview and setup instructions.
• USER_GUIDE.md: End-user documentation and help.

---

📄 License

Licensed under the MIT License.

---

❤️ Contribute

MyBibliotheca is open source and contributions are welcome!

Pull requests, bug reports, and feature suggestions are appreciated.