john-okeefe
c3769fe7f1
- Change Go module name back from 'shelf' to 'bookmann' - Update all import paths back to 'bookmann' module - Update README.md project name back to 'Bookmann' - Update docker-compose.yml container names back to 'bookmann' and 'bookmann_db' - Regenerate database code with restored module imports
189 lines
8.3 KiB
Markdown
189 lines
8.3 KiB
Markdown
# 📚 Bookmann
|
|
|
|
A self-hosted ebook management system built with Go, PostgreSQL, HTMX, and Tailwind CSS (fully integrated into a single service) featuring multiple beautiful dark themes with Tokyo Night as default.
|
|
|
|
## ✨ Features
|
|
|
|
- **🔒 Multi-User Authentication**: Complete user system with registration/login, JWT-based sessions, and bcrypt password hashing
|
|
- **✅ Server-Side Validation**: Comprehensive input validation with detailed error messages
|
|
- **🌙 Multiple Themes**: 11 beautiful themes including Tokyo Night, Dracula, Nord, Solarized Dark, Monokai, One Dark Pro, Material Dark, and Catppuccin variants (Mocha, Macchiato, Frappé, Latte) with user preferences saved to database
|
|
- **🎨 Theme Persistence**: User theme choices sync between browser and server
|
|
- **📖 Reading Progress**: User-specific reading progress tracking
|
|
- **📁 Multiple Folder Support**: Configure multiple ebook folders per user for comprehensive library management
|
|
- **🔍 Smart Scanner**: Automatic ebook discovery with EPUB metadata extraction (title, author, description, publisher, etc.)
|
|
- **👀 Real-Time Monitoring**: File system monitoring for automatic ebook detection and updates
|
|
- **📚 Rich Metadata**: Automatic extraction of ebook metadata from EPUB files
|
|
- **🔧 RESTful API**: Clean API endpoints with JWT authentication
|
|
- **🐳 Docker Ready**: Single-container deployment with PostgreSQL
|
|
- **🧪 API Testing**: Complete Bruno collection for testing all endpoints
|
|
- **📱 Responsive Design**: Mobile-first responsive interface using Tailwind CSS
|
|
- **⚡ HTMX Integration**: Dynamic interactions without JavaScript frameworks
|
|
- **🎯 TypeScript Support**: Client-side scripting with TypeScript compilation
|
|
|
|
## Quick Start
|
|
|
|
### Prerequisites
|
|
|
|
- Docker and Docker Compose
|
|
|
|
### Running the Application
|
|
|
|
1. Clone the repository
|
|
2. Run the application:
|
|
|
|
```bash
|
|
docker-compose up --build
|
|
```
|
|
|
|
3. Access the application at http://localhost:8765
|
|
|
|
### Database
|
|
|
|
PostgreSQL runs on port 5432 with default credentials:
|
|
- Database: ebookdb
|
|
- User: postgres
|
|
- Password: password
|
|
|
|
## Development
|
|
|
|
### Development
|
|
|
|
```bash
|
|
go mod tidy
|
|
go run github.com/sqlc-dev/sqlc/cmd/sqlc@latest generate
|
|
go run cmd/server/main.go
|
|
```
|
|
|
|
The application uses Go HTML templates for server-side rendering with HTMX for dynamic interactions. Templates are located in `templates/`.
|
|
|
|
**✨ Enhanced Features:**
|
|
- **Authentication**: Login/Register forms with multiple theme support at `/login` and `/register`
|
|
- **JWT Management**: Secure token storage with localStorage and session persistence
|
|
- **Theme Switching**: 7 popular dark themes with dropdown selector and database persistence
|
|
- **HTMX Integration**: Form submissions and dynamic updates without page reloads
|
|
- **Input Validation**: Server-side validation with detailed error messages
|
|
- **Multiple Themes**: Beautiful dark themes with smooth transitions
|
|
- **Responsive Design**: Mobile-first approach with optimized layouts for all screen sizes
|
|
|
|
**Note**: The frontend is fully integrated into the Go backend using HTML templates and HTMX.
|
|
|
|
## API Endpoints
|
|
|
|
### Auth (Public)
|
|
- `POST /api/auth/register` - Register new user
|
|
- `POST /api/auth/login` - Login user (email or username)
|
|
- `GET /api/auth/profile` - Get user profile (requires JWT)
|
|
- `PUT /api/auth/theme` - Update user theme preference (requires JWT)
|
|
|
|
### Ebook Folders (Protected)
|
|
- `POST /api/auth/ebook-folders` - Add an ebook folder for scanning
|
|
- `GET /api/auth/ebook-folders` - List user's configured ebook folders
|
|
- `DELETE /api/auth/ebook-folders/:folderPath` - Remove an ebook folder
|
|
|
|
### Ebooks (Protected)
|
|
- `GET /api/ebooks` - List ebooks
|
|
- `GET /api/ebooks/:id` - Get specific ebook
|
|
- `POST /api/ebooks` - Create new ebook
|
|
- `PUT /api/ebooks/:id` - Update ebook
|
|
- `DELETE /api/ebooks/:id` - Delete ebook
|
|
|
|
### Reading Progress (Protected)
|
|
- `GET /api/ebooks/:id/progress` - Get reading progress
|
|
- `PUT /api/ebooks/:id/progress` - Update reading progress
|
|
|
|
### Ratings (Protected)
|
|
- `GET /api/ebooks/:id/rating` - Get user's rating for ebook
|
|
- `POST /api/ebooks/:id/rating` - Create or update ebook rating
|
|
- `PUT /api/ebooks/:id/rating` - Create or update ebook rating
|
|
- `DELETE /api/ebooks/:id/rating` - Delete user's rating
|
|
- `GET /api/ebooks/:id/ratings` - Get all ratings for ebook
|
|
|
|
### Scanner (Protected)
|
|
- `POST /api/scanner/scan` - Manually scan configured folders for ebooks
|
|
- `POST /api/scanner/start` - Start real-time monitoring of configured folders
|
|
- `POST /api/scanner/stop` - Stop real-time folder monitoring
|
|
|
|
## 📁 Ebook Scanner
|
|
|
|
Bookmann includes an intelligent ebook scanner that can automatically discover and catalog ebooks from your configured folders.
|
|
|
|
### Setting Up Folders
|
|
|
|
1. **Add Folders**: Use the API or Bruno to add ebook folders to your account
|
|
2. **Supported Formats**: EPUB, PDF, MOBI, AZW3, FB2, TXT
|
|
3. **Metadata Extraction**: EPUB files automatically get rich metadata (title, author, description, publisher, etc.)
|
|
|
|
### Scanner Operations
|
|
|
|
- **Manual Scan**: `POST /api/scanner/scan` - Immediately scan all configured folders
|
|
- **Start Monitoring**: `POST /api/scanner/start` - Begin real-time monitoring for changes
|
|
- **Stop Monitoring**: `POST /api/scanner/stop` - Stop monitoring (folders remain configured)
|
|
|
|
### Real-Time Features
|
|
|
|
- **Auto-Discovery**: New ebooks added to folders are automatically detected
|
|
- **Metadata Updates**: Modified files get updated metadata
|
|
- **Duplicate Prevention**: Existing ebooks are updated, not duplicated
|
|
- **Multi-Folder Support**: Monitor multiple directories simultaneously
|
|
|
|
## API Testing
|
|
|
|
Use the included Bruno collection in the `bruno/` directory for testing the API:
|
|
|
|
1. Install [Bruno](https://www.usebruno.com/)
|
|
2. Import the `bruno/` folder as a collection
|
|
3. Select the "localhost" environment
|
|
4. Run the application and test the endpoints
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
.
|
|
├── cmd/server/ # Application entry point
|
|
├── internal/
|
|
│ ├── config/ # Configuration management
|
|
│ ├── database/ # Database connection and queries
|
|
│ ├── handlers/ # HTTP handlers (auth + ebooks)
|
|
│ └── services/ # Business logic services (ebook scanner)
|
|
├── migrations/ # Database migrations
|
|
├── templates/ # Go HTML templates with HTMX
|
|
├── bruno/ # Bruno API testing collection
|
|
├── Dockerfile # Docker build configuration
|
|
├── docker-compose.yml # Docker Compose setup
|
|
├── go.mod # Go module definition
|
|
├── go.sum # Go module checksums
|
|
├── sqlc.yaml # SQL code generation config
|
|
└── README.md
|
|
```
|
|
|
|
## 🎨 Recent Enhancements
|
|
|
|
### Backend Improvements
|
|
- **Server-Side Rendering**: Replaced static frontend with Go HTML templates
|
|
- **Theme System**: Database-backed user theme preferences with 7 popular dark themes
|
|
- **HTMX Integration**: Dynamic interactions using HTMX for modern UX
|
|
- **Enhanced Security**: JWT authentication with theme persistence
|
|
- **Multiple Folder Support**: Users can configure multiple ebook directories
|
|
- **Smart Ebook Scanner**: Automatic discovery and metadata extraction from EPUB files
|
|
- **Real-Time Monitoring**: File system watching for automatic ebook updates
|
|
|
|
### Frontend Redesign
|
|
- **Beautiful Homepage**: Hero section with features showcase and modern design
|
|
- **Multiple Themes**: 11 beautiful themes including Tokyo Night, Dracula, Nord, Solarized Dark, Monokai, One Dark Pro, Material Dark, and Catppuccin variants (Mocha, Macchiato, Frappé, Latte) with CSS variables
|
|
- **HTMX Forms**: Real-time form submissions and updates without JavaScript frameworks
|
|
- **Theme Switcher**: Dropdown selector that saves preferences to database
|
|
- **Responsive Design**: Tailwind CSS for mobile-first responsive layouts
|
|
- **Smooth Animations**: CSS transitions and scroll effects
|
|
|
|
### Technical Updates
|
|
- **Go Templates**: Server-side rendering with template inheritance
|
|
- **Tailwind CSS**: Utility-first CSS framework via CDN
|
|
- **TypeScript Support**: Client-side scripting with TypeScript compilation
|
|
- **Database Schema**: Added user_ebook_folders table for multiple folder support
|
|
- **API Expansion**: New endpoints for folder management and scanner operations
|
|
- **Metadata Extraction**: EPUB parsing for rich ebook information
|
|
- **File System Monitoring**: Real-time folder watching with fsnotify
|
|
|
|
## License
|
|
|
|
GPL-3.0 |