CloudLib - Rails 8 eBook Bibliothek

Eine moderne, responsive eBook-Bibliothek gebaut mit Rails 8.1, die EPUB-Bücher verwaltet und direkt im Browser lesen lässt.

✨ Features

• 📚 Automatische Buch-Erkennung: EPUB-Dateien im /books Verzeichnis werden automatisch erkannt und in die Bibliothek aufgenommen
• 📖 In-App EPUB Reader: Lies deine Bücher direkt im Browser mit epub.js
• 📱 Responsive Design: Optimiert für Desktop und Mobile mit Touch-Gesten
• 🔖 Lesezeichen & Fortschritt: Speichere deinen Lesefortschritt und setze Lesezeichen
• 👥 Multi-User Support: Jeder Benutzer hat seine eigene Bibliothek mit eigenem Lesefortschritt
• 🎨 Dark Mode: Komfortables Lesen bei Tag und Nacht
• 🔍 Metadaten-Extraktion: Automatische Extraktion von Titel, Autor, Cover und mehr

🚀 Technologie-Stack

• Ruby: 3.3.6
• Rails: 8.1.1
• Datenbank: SQLite3
• Frontend: Turbo + Stimulus
• CSS: Tailwind CSS 4.x
• EPUB Reader: epub.js 0.3.93
• EPUB Parsing: epub-parser gem
• Background Jobs: Solid Queue (Rails 8 built-in)
• Bild-Verarbeitung: ImageMagick + mini_magick

📋 Voraussetzungen

• Ruby 3.3+ (via rbenv empfohlen)
• ImageMagick (brew install imagemagick)
• Node.js (für Tailwind CSS)

🛠 Installation

1. Repository clonen (falls Git initialisiert):

   git clone <repo-url>
   cd cloudlib

2. Ruby Version prüfen:

   ruby --version  # sollte 3.3.6 sein

3. Dependencies installieren:

   bundle install

4. Datenbank erstellen:

   bin/rails db:migrate

5. Test-User erstellen (optional):

   bin/rails runner 'User.create(email_address: "[email protected]", password: "password123", password_confirmation: "password123")'

6. EPUB-Bücher hinzufügen:

   • Kopiere deine EPUB-Dateien in das /books Verzeichnis
   • Die Bücher werden automatisch alle 5 Minuten erkannt
   • Oder manuell triggern: bin/rails runner "BookDiscoveryJob.perform_now"

🎯 Nutzung

Server starten

Development Server mit Tailwind CSS Live-Reload:

bin/dev

Die App ist dann verfügbar unter: http://localhost:3000

Ersten Benutzer registrieren

1. Öffne http://localhost:3000 im Browser
2. Navigiere zu /session/new für Login oder registriere einen neuen User
3. Nach dem Login siehst du deine Bibliothek

Bücher hinzufügen

Neue EPUB-Dateien einfach ins /books Verzeichnis kopieren:

cp mein-buch.epub books/

Die Bücher werden automatisch alle 5 Minuten erkannt und verarbeitet.

Bücher lesen

• Klicke auf ein Buch-Cover in der Bibliothek
• Der Reader öffnet sich im Vollbild
• Navigation:
  • Buttons: "Zurück" / "Weiter"
  • Tastatur: Pfeiltasten links/rechts
  • Touch: Swipe links/rechts auf Mobile
• Features:
  • A- / A+: Schriftgröße anpassen
  • 🌙: Dark Mode Toggle
  • 🔖: Lesezeichen setzen

📁 Projekt-Struktur

cloudlib/
├── app/
│   ├── controllers/
│   │   ├── books_controller.rb          # Library & Reader
│   │   ├── reading_sessions_controller.rb
│   │   └── bookmarks_controller.rb
│   ├── models/
│   │   ├── book.rb
│   │   ├── reading_session.rb
│   │   ├── bookmark.rb
│   │   └── user.rb
│   ├── services/
│   │   ├── epub_metadata_extractor.rb   # EPUB Parsing
│   │   └── book_discovery_service.rb    # Auto-Discovery
│   ├── jobs/
│   │   └── book_discovery_job.rb        # Background Job
│   ├── javascript/
│   │   └── controllers/
│   │       └── epub_reader_controller.js # EPUB Reader Logic
│   └── views/
│       └── books/
│           ├── index.html.erb           # Library View
│           ├── show.html.erb            # Reader View
│           └── _book_card.html.erb      # Book Card Partial
├── books/                               # 📚 EPUB Storage
├── public/
│   └── covers/                          # Extracted Cover Images
├── config/
│   ├── recurring.yml                    # Solid Queue Jobs
│   └── importmap.rb                     # JavaScript Imports
└── db/
    └── schema.rb

🔧 Konfiguration

Background Jobs (Solid Queue)

Die Buch-Erkennung läuft automatisch alle 5 Minuten. Konfiguration in config/recurring.yml:

development:
  book_discovery:
    class: BookDiscoveryJob
    schedule: every 5 minutes

EPUB Verzeichnis

Standard: /books im Projekt-Root. Zum Ändern BOOKS_DIR in app/services/book_discovery_service.rb anpassen.

🎨 Datenbank Schema

• users: Email, Password (Rails 8 Authentication)
• books: Titel, Autor, Cover, ISBN, Dateipfad, etc.
• reading_sessions: User-Buch-Zuordnung mit Lesefortschritt (CFI-Location, Progress %)
• bookmarks: Lesezeichen mit CFI-Location

🚢 Deployment

Development

bin/dev  # Startet Rails + Tailwind CSS

Production

1. Assets precompilieren:

   RAILS_ENV=production bin/rails assets:precompile

2. Datenbank migrieren:

   RAILS_ENV=production bin/rails db:migrate

3. Server starten:

   RAILS_ENV=production bin/rails server

4. Solid Queue Worker starten:

   RAILS_ENV=production bin/jobs

Docker (optional)

Ein Dockerfile ist bereits im Projekt vorhanden:

docker build -t cloudlib .
docker run -p 3000:3000 cloudlib

📝 Entwicklung

Neue Bücher manuell verarbeiten

bin/rails runner "BookDiscoveryJob.perform_now"

Rails Console

bin/rails console

Beispiele:

# Alle Bücher anzeigen
Book.all

# Buch mit Cover-Extraktion neu verarbeiten
BookDiscoveryService.new.discover_new_books

# Lesefortschritt eines Users
user = User.first
user.reading_sessions.includes(:book).each do |rs|
  puts "#{rs.book.title}: #{rs.progress_percentage}%"
end

🐛 Troubleshooting

EPUB wird nicht erkannt

• Prüfe ob die Datei im /books Verzeichnis liegt
• Prüfe Rails Logs: tail -f log/development.log
• Manuell triggern: BookDiscoveryJob.perform_now

Cover-Bild fehlt

• ImageMagick installiert? convert --version
• Prüfe ob /public/covers Verzeichnis existiert und beschreibbar ist

Reader lädt nicht

• Browser Console öffnen (F12) für JavaScript Fehler
• Prüfe ob epub.js im importmap geladen wird
• Prüfe ob EPUB-Datei noch am Original-Pfad existiert

📚 Genutzte Gems

gem 'epub-parser'        # EPUB Metadaten-Extraktion
gem 'listen'             # File System Watching
gem 'mini_magick'        # ImageMagick Wrapper
gem 'image_processing'   # Cover Image Processing
gem 'solid_queue'        # Background Jobs (Rails 8)
gem 'tailwindcss-rails'  # CSS Framework

🎯 Roadmap / Zukünftige Features

• Volltext-Suche in Büchern
• Notizen & Highlights
• Export von Notizen
• Bücherregale / Sammlungen
• Lesestatistiken
• PDF-Support
• Audiobook-Support

📄 Lizenz

Dieses Projekt ist Open Source.

👨‍💻 Entwickelt mit

• Rails 8.1 Authentication Generator
• epub.js für Web-basiertes EPUB Reading
• Stimulus für interaktive UI-Komponenten
• Tailwind CSS für modernes, responsives Design