From aef7bd067c346b312dd6e24d9ea5cd8e77852d1e Mon Sep 17 00:00:00 2001 From: droideparanoico Date: Thu, 2 Jul 2026 15:52:17 +0200 Subject: [PATCH] Add comprehensive README with usage, architecture, and configuration docs --- README.md | 252 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 252 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..42b6e86 --- /dev/null +++ b/README.md @@ -0,0 +1,252 @@ +# DiscDrop + +> Self-hosted RSS feed generator for [MusicBrainz](https://musicbrainz.org) release groups. + +Track your favourite artists and get a unified RSS feed of their release groups — albums, singles, EPs, and more. No duplicates (release groups, not individual releases), per-artist type monitoring, and a clean modern UI. + +Built with **Quarkus + HTMX + daisyUI**. + +--- + +## Features + +- **Unified RSS feed** — One feed for all tracked artists, ordered chronologically by first release date +- **Per-artist monitoring** — Choose which release types to track per artist (Album, Single, EP, Broadcast, Other) +- **Artist search** — Autocomplete search against the MusicBrainz API with disambiguation info +- **Release group deduplication** — Tracks release groups instead of individual releases (no duplicate vinyl/CD/digital entries) +- **OPML export** — Subscribe in any RSS reader +- **Theme switching** — daisyUI themes: Dark, Light, Synthwave, Retro, Dracula, Night, Dim, Nord +- **Settings** — Configurable cache TTL (6/12/24h) and default release types +- **Zero infrastructure** — SQLite single-file database, no external services needed + +--- + +## Quick Start + +### Prerequisites + +- Java 21+ +- Maven 3.9+ + +### Development + +```bash +# Run in dev mode with live reload +mvn quarkus:dev +``` + +The app starts at [http://localhost:8080](http://localhost:8080). + +### Production (JAR) + +```bash +# Build +mvn clean package + +# Run +java -jar target/quarkus-app/quarkus-run.jar +``` + +### Docker + +```bash +# Build the JAR +mvn clean package + +# Build the image (from project root) +docker build -f src/main/docker/Dockerfile.jvm -t discdrop . + +# Run +docker run -p 8080:8080 \ + -e DISC_DROP_BASE_URL=http://localhost:8080 \ + -v discdrop-data:/app/data \ + discdrop +``` + +--- + +## Configuration + +All configuration is via environment variables: + +| Variable | Default | Description | +|----------|---------|-------------| +| `DISC_DROP_DB_PATH` | `data/discdrop.db` | Path to the SQLite database file | +| `DISC_DROP_CACHE_TTL` | `8` | Cache TTL in hours (how often release groups are refreshed from MusicBrainz) | +| `DISC_DROP_BASE_URL` | `http://localhost:8080` | Public URL for RSS feed links | + +The MusicBrainz User-Agent is set to `DiscDrop/1.0 (david.alvarez.81@gmail.com)` per [MusicBrainz API etiquette](https://musicbrainz.org/doc/MusicBrainz_API/Rate_Limiting). + +--- + +## Usage + +### 1. Add artists + +Use the search bar in the navbar (available on all pages) to find artists. Each result shows the artist name, disambiguation, and country/area. If an artist is already tracked, it shows "✓ Added". + +Click **+ Add** to start tracking an artist. DiscDrop immediately fetches their release groups from MusicBrainz and caches them locally. + +### 2. Configure monitoring + +On the **Artists** page, toggle release type checkboxes per artist: +- **Album** (monitored by default) +- **Single** +- **EP** +- **Broadcast** +- **Other** + +Changes take effect immediately. The feed updates on next refresh. + +### 3. Subscribe to the feed + +On the **Releases** page, use the **RSS Feed** button to get the feed URL: +- RSS: `http://your-instance/feed/rss.xml` +- OPML: `http://your-instance/feed/opml` + +The feed includes: +- Release title and artist name +- Cover art from Cover Art Archive +- Release type (Album, Single, etc.) +- First release date +- Link to MusicBrainz release group page + +### 4. Settings + +Click the ⚙️ icon in the navbar to configure: +- **Cache refresh interval** (6, 8, 12, or 24 hours) +- **Default release types** for newly added artists + +--- + +## Architecture + +``` +Browser (HTMX + daisyUI) RSS Reader + │ │ + │ HTML fragments │ RSS/XML + ▼ ▼ +┌──────────────────────────────────────┐ +│ Quarkus HTTP Server │ +│ ┌────────┐ ┌────────┐ ┌────────┐ │ +│ │ Qute │ │ REST │ │ RSS │ │ +│ │ Pages │ │ API │ │ Feed │ │ +│ └───┬────┘ └───┬────┘ └───┬────┘ │ +│ └───────────┼────────────┘ │ +│ ▼ │ +│ Service Layer │ +│ ArtistService · ReleaseGroupService │ +│ FeedService · CacheService │ +│ │ │ │ +│ ┌──────┴──────┐ ┌─────┴──────┐ │ +│ │ SQLite │ │ MusicBrainz│ │ +│ │ (raw JDBC) │ │ REST │ │ +│ └─────────────┘ └────────────┘ │ +└──────────────────────────────────────┘ +``` + +### Stack + +| Layer | Technology | +|-------|-----------| +| Framework | Quarkus 3.x | +| Language | Java 21 | +| Templating | Qute + HTMX 2.x | +| CSS | daisyUI 4.x (Tailwind CSS) | +| Database | SQLite via raw JDBC | +| RSS | Rome (rometools) | +| Build | Maven | +| Deployment | Docker (JVM) | + +--- + +## API Endpoints + +### Pages + +| Endpoint | Description | +|----------|-------------| +| `GET /` | Releases feed page | +| `GET /artists` | Tracked artists management page | + +### HTMX API + +| Method | Endpoint | Description | +|--------|----------|-------------| +| `GET` | `/api/artists/search?q=` | Artist search autocomplete (HTML fragment) | +| `POST` | `/api/artists/{mbid}/track` | Add artist to tracking | +| `DELETE` | `/api/artists/{mbid}` | Remove artist | +| `PATCH` | `/api/artists/{mbid}/monitor?type=` | Toggle release type monitoring | +| `GET` | `/api/artists/list` | Tracked artists list (HTML fragment) | +| `GET` | `/api/artists/feed-table` | Feed entries table (HTML fragment) | +| `GET` | `/api/settings/form` | Settings form (HTML fragment) | +| `PATCH` | `/api/settings` | Save settings | + +### RSS / Export + +| Endpoint | Description | +|----------|-------------| +| `GET` | `/feed/rss.xml` | RSS 2.0 feed | +| `GET` | `/feed/opml` | OPML subscription file | + +--- + +## Data Model + +Two SQLite tables: + +- **`tracked_artist`** — Artists you're tracking with per-type monitoring flags +- **`release_group_cache`** — Cached release groups from MusicBrainz +- **`settings`** — Key-value app settings (cache TTL, default types) + +Database file location is configurable via `DISC_DROP_DB_PATH`. + +--- + +## Comparison: mbz-rss-feeder → DiscDrop + +| Feature | mbz-rss-feeder (Flask) | DiscDrop (Quarkus) | +|---------|----------------------|-------------------| +| Multiple feeds | Yes | **Single unified feed** | +| Tracks | Individual releases | **Release groups** (no duplicates) | +| Artist search | Simple list | **Autocomplete** with disambiguation | +| Type filtering | None | **Per-artist monitoring** (Album/Single/EP etc.) | +| RSS order | Newest first | **Chronological ascending** by release date | +| Theme | Plain CSS | **daisyUI themes** (7 themes) | +| Cache | File-based | **Database-level TTL cache** | +| Persistence | YAML files | **SQLite** (zero infra) | + +--- + +## Development + +### Prerequisites + +- Java 21 (Corretto or OpenJDK) +- Apache Maven 3.9+ + +### Build + +```bash +mvn clean package +``` + +### Run tests + +```bash +mvn test +``` + +### Live reload + +```bash +mvn quarkus:dev +``` + +Changes to Java source and templates are hot-reloaded. + +--- + +## License + +MIT