Add comprehensive README with usage, architecture, and configuration docs
This commit is contained in:
droideparanoico
@@ -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
|
||||
Reference in New Issue
Block a user