Gronod
f500f4db3b
- Fix seriesMap key (use Sonarr internal id, not tvdbId) - Fix Sonarr tag resolution (use tag map like Radarr) - Use sourceTitle for history record matching - Fall back to embedded movie/series objects when API timeouts - Add includeMovie/includeSeries params to queue/history API calls - Add coverArt field to all download responses (TMDB poster URLs) - Add cover art display to frontend download cards - Fix user-summary route to use instance config and tag maps
220 lines
6.9 KiB
Markdown
220 lines
6.9 KiB
Markdown
# sofarr
|
|
|
|
> *See your downloads "so far" while you relax on the sofa waiting for your *arr services to finish*
|
|
|
|
**sofarr** is a personal media download dashboard that aggregates and displays real-time download progress from all your media automation services. Named for the experience of checking what has downloaded "so far" while you wait comfortably on your "sofa" for Sonarr, Radarr, and your download clients to do their thing!
|
|
|
|
## What It Does
|
|
|
|
sofarr connects to your media stack and shows you a personalized view of:
|
|
- **Active Downloads** - See what's currently downloading from Usenet (SABnzbd) and BitTorrent (qBittorrent)
|
|
- **Progress Tracking** - Real-time progress bars with speed, ETA, and completion estimates
|
|
- **User Matching** - Downloads are matched to you based on tags in Sonarr/Radarr
|
|
- **Multi-Instance Support** - Connect to multiple instances of each service
|
|
|
|
## How It Works
|
|
|
|
### Architecture Overview
|
|
|
|
```
|
|
┌─────────────┐ ┌──────────────┐ ┌─────────────────────────────┐
|
|
│ Browser │────▶│ sofarr │────▶│ SABnzbd (Usenet downloads) │
|
|
│ (User) │◀────│ Server │ │ qBittorrent (Torrents) │
|
|
└─────────────┘ └──────────────┘ │ Sonarr (TV management) │
|
|
│ │ Radarr (Movie management) │
|
|
│ │ Emby (User authentication) │
|
|
▼ └─────────────────────────────┘
|
|
┌──────────────┐
|
|
│ Dashboard │
|
|
│ Aggregator │
|
|
└──────────────┘
|
|
```
|
|
|
|
### The Matching Process
|
|
|
|
1. **User Authentication**: Login via Emby credentials
|
|
2. **Tag-Based Matching**:
|
|
- Your media in Sonarr/Radarr is tagged with your username (e.g., "gordon")
|
|
- sofarr checks Sonarr/Radarr activity to find items tagged with your name
|
|
- Downloads (from SABnzbd/qBittorrent) are matched by title to that activity
|
|
- Only your downloads appear on your dashboard
|
|
|
|
### Multi-Instance Support
|
|
|
|
sofarr supports multiple instances of each service via JSON array configuration:
|
|
|
|
```bash
|
|
# Single line JSON arrays in .env
|
|
QBITTORRENT_INSTANCES=[{"name":"server1","url":"..."},{"name":"server2","url":"..."}]
|
|
SONARR_INSTANCES=[{"name":"main","url":"...","apiKey":"..."}]
|
|
```
|
|
|
|
## Prerequisites
|
|
|
|
- Node.js (v12 or higher)
|
|
- npm
|
|
- At least one of: SABnzbd or qBittorrent
|
|
- Sonarr (optional, for TV tracking)
|
|
- Radarr (optional, for movie tracking)
|
|
- Emby (for user authentication)
|
|
|
|
## Installation
|
|
|
|
1. **Clone and install**:
|
|
```bash
|
|
git clone <repository-url>
|
|
cd sofarr
|
|
npm install
|
|
```
|
|
|
|
2. **Configure environment**:
|
|
```bash
|
|
cp .env.sample .env
|
|
# Edit .env with your service details
|
|
```
|
|
|
|
3. **Start the server**:
|
|
```bash
|
|
npm start
|
|
# or for development with auto-restart:
|
|
npm run dev
|
|
```
|
|
|
|
4. **Access the dashboard**:
|
|
Open `http://localhost:3001` in your browser
|
|
|
|
## Configuration (.env)
|
|
|
|
### Basic Server Settings
|
|
```bash
|
|
PORT=3001 # Server port
|
|
LOG_LEVEL=info # Logging: debug, info, warn, error, silent
|
|
```
|
|
|
|
### Service Instances (JSON Array Format)
|
|
|
|
All services support multi-instance configuration via single-line JSON arrays:
|
|
|
|
```bash
|
|
# SABnzbd Instances
|
|
SABNZBD_INSTANCES=[{"name":"primary","url":"https://sabnzbd.example.com","apiKey":"your-api-key"}]
|
|
|
|
# qBittorrent Instances (uses username/password, not API key)
|
|
QBITTORRENT_INSTANCES=[{"name":"main","url":"https://qbittorrent.example.com","username":"admin","password":"secret"}]
|
|
|
|
# Sonarr Instances
|
|
SONARR_INSTANCES=[{"name":"hd","url":"https://sonarr.example.com","apiKey":"your-api-key"}]
|
|
|
|
# Radarr Instances
|
|
RADARR_INSTANCES=[{"name":"movies","url":"https://radarr.example.com","apiKey":"your-api-key"}]
|
|
|
|
# Emby (single instance for authentication)
|
|
EMBY_URL=https://emby.example.com
|
|
EMBY_API_KEY=your-emby-api-key
|
|
```
|
|
|
|
### Legacy Single-Instance Format (still supported)
|
|
|
|
If you only have one instance, you can use the legacy format:
|
|
```bash
|
|
SABNZBD_URL=https://sabnzbd.example.com
|
|
SABNZBD_API_KEY=your-api-key
|
|
```
|
|
|
|
## Setting Up User Tags
|
|
|
|
To see your downloads, you need to tag your media in Sonarr/Radarr:
|
|
|
|
1. **In Sonarr** (TV Shows):
|
|
- Go to Series → Edit Series
|
|
- Add a tag with your username (lowercase)
|
|
- Save
|
|
|
|
2. **In Radarr** (Movies):
|
|
- Go to Movies → Edit Movie
|
|
- Add a tag with your username (lowercase)
|
|
- Save
|
|
|
|
3. **Result**: When sofarr sees a download matching a show/movie tagged with "gordon", it appears on gordon's dashboard
|
|
|
|
## Features in Detail
|
|
|
|
### Real-Time Updates
|
|
- Auto-refresh every 5 seconds (configurable: 1s, 5s, 10s, or off)
|
|
- In-place DOM updates for smooth UI (no flickering)
|
|
|
|
### Download Information Displayed
|
|
- **Progress bar** with visual completion percentage
|
|
- **Speed** - Current download speed
|
|
- **ETA** - Estimated time remaining
|
|
- **Size** - Total size and downloaded amount
|
|
- **Status** - Downloading, Paused, Queued, etc.
|
|
- **Instance** - Which server the download is from
|
|
|
|
### For qBittorrent Downloads
|
|
- **Seeds** - Number of seeders
|
|
- **Peers** - Number of peers
|
|
- **Availability** - Percentage available in swarm
|
|
|
|
## API Endpoints
|
|
|
|
### Authentication
|
|
- `POST /api/auth/login` - Login with Emby credentials
|
|
- `POST /api/auth/logout` - Logout and clear session
|
|
|
|
### Dashboard
|
|
- `GET /api/dashboard/downloads` - Get all downloads for authenticated user
|
|
|
|
### Service APIs (proxy to your services)
|
|
- `GET /api/sabnzbd/*` - SABnzbd API proxy
|
|
- `GET /api/qbittorrent/*` - qBittorrent API proxy
|
|
- `GET /api/sonarr/*` - Sonarr API proxy
|
|
- `GET /api/radarr/*` - Radarr API proxy
|
|
- `GET /api/emby/*` - Emby API proxy
|
|
|
|
## Logging Levels
|
|
|
|
Set `LOG_LEVEL` in your `.env`:
|
|
- `debug` - Verbose logging for troubleshooting
|
|
- `info` - Standard operational logging (default)
|
|
- `warn` - Only warnings and errors
|
|
- `error` - Only errors
|
|
- `silent` - No logging
|
|
|
|
Logs are written to both console and `server.log` file.
|
|
|
|
## Troubleshooting
|
|
|
|
**"No downloads showing"**
|
|
- Verify your media is tagged with your username in Sonarr/Radarr
|
|
- Check that LOG_LEVEL=debug shows matching attempts
|
|
- Ensure download names match between client and *arr apps
|
|
|
|
**"Can't connect to service"**
|
|
- Check URLs are accessible from the sofarr server
|
|
- Verify API keys and credentials
|
|
- Check CORS settings on your services
|
|
|
|
**"qBittorrent not showing"**
|
|
- Ensure username/password are correct
|
|
- Check qBittorrent Web UI is enabled
|
|
- Verify the URL includes the full path (e.g., `https://qb.example.com`)
|
|
|
|
## Development
|
|
|
|
```bash
|
|
# Start with auto-restart on changes
|
|
npm run dev
|
|
|
|
# Production start
|
|
npm start
|
|
```
|
|
|
|
## License
|
|
|
|
MIT
|
|
|
|
---
|
|
|
|
*sofarr: See what has downloaded "so far" from the comfort of your "sofa"*
|