Files

T

john-okeefe 76c6826920 feat(deploy): split compose into prod base + dev override

Restructure the container setup to support registry-based deployment:
the default docker-compose.yml now pulls a prebuilt app image from the
Gitea container registry instead of building locally, while a new
docker-compose.dev.yml override preserves the local build + integration
test workflow for development.

Why:
- Production and self-hosting should consume a published image, not
  rebuild from source on the host. The default `docker compose up` now
  pulls the app image (git.linuxhg.com/bookhoard/bookhoard) alongside the
  public postgres image, with no build step required.
- Development still needs to build from source and run integration
  tests, so those concerns move to an override file the Makefile applies.
  Shared config (env, volumes, ports, healthchecks) lives in one place to
  avoid drift between environments.

Changes:
- docker-compose.yml (prod base): the app service now references
  `image: git.linuxhg.com/bookhoard/bookhoard:${IMAGE_TAG:-latest}` instead
  of a build context. The tests service is removed (moved to the
  override). IMAGE_TAG lets deployers pin or roll back a specific version.
- docker-compose.dev.yml (new override): adds the local `build:` context
  for the app and defines the integration `tests` service (profile-gated).
  Everything else is inherited from the base file via compose merging.
- Makefile: introduce a COMPOSE variable that merges the base and
  override (`-f docker-compose.yml -f docker-compose.dev.yml`); all dev
  targets now use it. Plain `docker compose` against the base file only
  remains the production path.
- README: quickstart updated to pull and start prebuilt images; clone URL
  points at the Gitea instance.

The development workflow (`make rebuild-app`, `make test-integration`,
etc.) is functionally unchanged.

2026-07-29 15:47:40 -04:00

5.9 KiB

Raw Blame History

📚 Bookhoard

A modern self-hosted media library system built with Go, PostgreSQL, HTMX, and Tailwind CSS featuring universal cross-device sync, beautiful dark themes, and comprehensive media management.

✨ Why Bookhoard?

🔄 Universal Sync: Your reading progress, highlights, and notes sync automatically across all your devices - KOReader, Kobo, web, and mobile.

📱 Multi-Library: Organize your ebooks, comics, and manga with per-library folders and smart collections.

🎨 Beautiful UI: 11 gorgeous dark themes with responsive design that works on any device.

🔒 Secure: JWT authentication, bcrypt password hashing, rate limiting, and no passwords on devices.

🚀 Quick Start

Prerequisites

Podman (recommended) or Docker
5 minutes of your time

Installation

# 1. Clone the repository
git clone https://git.linuxhg.com/Bookhoard/bookhoard.git
cd bookhoard

# 2. Set up environment
cp .env.example .env
# Generate secure passwords (no special characters):
#   JWT_SECRET: openssl rand -hex 32
#   DBPASS: openssl rand -hex 16
# Edit .env with your generated values

# 3. Pull images and start the server
docker compose pull
docker compose up -d
# Optionally pin a specific version: set IMAGE_TAG in .env (defaults to "latest")

# 4. Open your browser
open http://localhost:8765

The first user to register automatically becomes an admin.

📖 Key Features

Universal Cross-Platform Sync

Real-Time Progress: Turn a page on your Kindle, see it on your phone
Format-Aware: EPUB CFI, page numbers, percentages - all handled correctly
Offline Queue: Changes sync when you reconnect, priority-processed
Conflict Resolution: Smart handling when same book read on multiple devices
Book Matching: Automatic matching using SHA-256, ISBN, UUID
OPDS Catalog: Wireless book delivery to e-readers over Wi-Fi
Format Conversion: On-the-fly EPUB→KEPUB for Kobo devices

Media Management

Calibre Integration: Automatic metadata import from Calibre metadata.opf sidecar files
Smart Search: Partial matching with fuzzy search fallback for typos
Advanced Filtering: Filter by author, series, genre, language, year, cover images
Dynamic Sorting: By title, author, date added, published date, page count, series
Rich Metadata: Title, author, series, publisher, ISBN, language, edition, tags
5-Star Ratings: Half-star precision (1-10 scale)
Notes & Highlights: Color-coded annotations with linked notes
Usage Analytics: Reading statistics, device usage, popular books

Smart Collections

Auto-Assign Rules: Automatically add books based on genre, author, series, tags, language, publisher, year
Device Shelf Mappings: Sync collections to Kobo shelves and KOReader categories
Test Before Creating: Preview which books match your rules

Library Organization

Multi-Library Support: Ebooks, Comics, and Manga with type-specific file formats
Multiple Folders: Add multiple scanning folders per library
Visibility Control: Admins control which libraries each user can see
Background Scanning: Auto-scan with per-user frequency settings
Watch Mode: Real-time file system monitoring for instant updates

Security

JWT Authentication: Short-lived access tokens (1 hour) with refresh tokens (7 days)
Strong Passwords: Complexity requirements enforced (8+ chars, uppercase, lowercase, number, special)
Account Lockout: 5 failed attempts = 15-minute lockout
Rate Limiting: 10 requests/minute on auth endpoints
Input Validation: Comprehensive validation on all inputs
No Passwords on Devices: Web-based device approval with QR codes

📚 Documentation

For Users & Self-Hosters

docs/user/calibre-integration.md - Calibre library integration
docs/user/sync-guide.md - Understanding and using universal sync
docs/user/devices/kobo-setup.md - Kobo e-reader configuration
docs/user/devices/koreader-setup.md - KOReader configuration
docs/user/user-guide.md - General user guide
docs/user/admin-guide.md - Admin features and configuration
docs/user/settings-guide.md - Settings and preferences

For Developers

docs/developer/api/api-reference.md - Complete API documentation
docs/contributing/DEVELOPMENT.md - Development workflow

🎯 Supported Devices

Platform	Sync	OPDS	Status
Web Browser	✅	✅	Full support
KOReader	✅	✅	Kindle, Kobo, PocketBook
Kobo Devices	✅	✅	Clara, Libra, Sage, etc.
Mobile Apps	🚧	🚧	Coming Q2 2026

🛠 Tech Stack

Backend: Go 1.25+ with Echo framework
Database: PostgreSQL 15+ with pgx v5
Frontend: HTMX + Tailwind CSS + Templ
Auth: JWT tokens with bcrypt password hashing
Container: Podman (Docker compatible)

🧪 Testing

# Run all tests
make test-all

# Run integration tests (with test mode)
make test-integration

# Run Bruno OpenCollection YAML API tests
npm install -g @usebruno/cli
bruno run

📊 Project Status

Version: 1.0
License: GPL-3.0
Status: Production-ready ✅

🤝 Contributing

We welcome contributions! Please see docs/DEVELOPMENT.md for guidelines.

📄 License

GPL-3.0 - See LICENSE file for details.

Built with ❤️ using Go, PostgreSQL, HTMX, and Tailwind CSS

5.9 KiB Raw Blame History