Seerr Lists

Canonical repository: https://github.com/devmesh-git/seerr-lists

A powerful manager that syncs Seerr categories (Trending, Popular, Upcoming) directly into Plex collections, complete with smart stub management for missing items.

Table of Contents

• Quick Start
• Overview
• Features
• Categories
• Configuration
• API Endpoints
• Installation
• Development
• Error Handling
• Performance
• Limitations
• Contributing
• License
• Privacy

Quick Start

Get started with Seerr Lists in minutes:

1. Clone the repository:

   git clone https://github.com/devmesh-git/seerr-lists.git
   cd seerr-lists

2. Start the Service:

   # Run with Docker Compose (Recommended)
   docker compose -f Docker/docker-compose.yml up -d

3. Finish Setup: Open your browser and navigate to http://localhost:8080 to complete the configuration using the web dashboard.

Overview

This seerr-lists service acts as a bridge between:

• Discovery-style category data (Trending, Popular, Recently Added, etc.) from Seerr
• Plex Collections

The service polls the Seerr API, normalizes category results, and directly manages Plex collections, ensuring they stay in sync with the latest trends. It handles creating collections, adding items, removing old items, and managing "Ghost Items" (stubs) for content you don't own yet.

Architecture

graph TD
    SeerrTV[SeerrTV Android] -.->|Reference Logic| Service[Seerr Lists Service Go]
    Service -->|Fetch Data| SeerrAPI[Seerr API]
    Service -->|Direct Sync| Plex[Plex Media Server]

Loading

Ghost Item Support (Stub Files)

Seerr Lists can sync "Ghost Items" (content you don't own yet) into Plex by creating lightweight dummy files (.strm). This ensures that lists like "Trending" appear in Plex even if your library is empty.

Required Setup:

1. Host Folder: Create two folders on your server (e.g., /media/discovery-movies and /media/discovery-tv).
2. Plex Library: Create a new "Discovery-Movies" library in Plex pointing to /media/discovery-movies and a new "Discovery-TV" library in Plex pointing to /media/discovery-tv.
3. Docker Mount: Mount these folders into the Seerr Lists container (e.g., -v /media/discovery-movies:/stubs-movies and -v /media/discovery-tv:/stubs-tv).
4. Config: Set libraryPath in your config to the container path (/stubs-movies and /stubs-tv).

The tool will automatically generate content in this folder, allowing Plex to scan and match metadata.

Features

• ✅ Fetches data from Seerr API
• ✅ Supports all SeerrTV categories (Trending, Popular, Upcoming, Recently Added, Recent Requests)
• ✅ Configurable list size per category
• ✅ In-memory caching with automatic expiration
• ✅ Handles API pagination automatically
• ✅ Direct Plex Collection Management (Syncs items directly to Plex)
• ✅ RESTful HTTP endpoints (Legacy support)
• ✅ Health check endpoint
• ✅ Graceful shutdown
• ✅ Structured logging
• ✅ Docker support

Categories

Seerr Lists supports splitting mixed content (Movies/TV) into separate lists for better Plex integration.

Category ID	Name	Media Type
trending-movies	Trending Movies	Movie
trending-series	Trending Series	TV
popular-movies	Popular Movies	Movie
popular-series	Popular Series	TV
upcoming-movies	Upcoming Movies	Movie
upcoming-series	Upcoming Series	TV
recently-added-movies	Recently Added Movies	Movie
recently-added-series	Recently Added Shows	TV
recent-requests-movies	Recent Requests Movies	Movie
recent-requests-series	Recent Requests Shows	TV

Setup & Configuration

Seerr Lists includes a web-based setup wizard to make configuration easy.

Initial Setup

1. Start the Service: Run the container or binary.
   • If no configuration is found, the service enters "waiting for setup" mode.
   • Access the web UI at http://localhost:8080.
2. Plex Authentication:
   • The wizard guides you to authenticate with your Plex account.
   • This authorizes the service to sync collections to your Plex server.
3. Seerr Connection:
   • Enter your Seerr instance URL (e.g., http://seerr.local:5055) and API Key.
   • The service validates the connection immediately.
4. Library Selection:
   • Enter the name of the Plex Library (e.g., "Movies") where collections should be created.
5. Collection Customization:
   • Review the default collection names (e.g., "Trending Now", "Popular Movies").
   • Rename any collection to your liking.
   • Note: All collections are automatically configured to "Hide Items from this collection" in Plex to keep your library clean.
6. Finish:
   • Configuration is saved to data/config.json.
   • The service automatically starts syncing.

Persistence

To persis you configuration, you must mount a volume to the /app/data directory when using Docker:

docker run -d \
  -v /path/to/data:/app/data \
  -p 8080:8080 \
  ghcr.io/devmesh-git/seerr-lists:latest

This ensures your login and settings survive container restarts.

API Endpoints

GET /health

Health check endpoint. Returns 200 OK if the service is running.

Example:

curl http://localhost:8080/health

Installation

Using Docker Compose (Recommended)

The easiest way to run Seerr Lists is using Docker Compose. A docker-compose.yml file is provided in the Docker/ directory.

1. Clone the repository:

   git clone https://github.com/devmesh-git/seerr-lists.git
   cd seerr-lists

2. Start the Service: Run from the project root:

   docker compose -f Docker/docker-compose.yml up -d

   Or navigate to the Docker directory:

   cd Docker
   docker compose up -d

3. Access the Web UI: The service will be available at http://localhost:8080.

Published Docker Images

If you prefer to run the container manually without Compose:

# Pull and run the latest version
docker run -d \
  --name seerr-lists \
  -p 8080:8080 \
  ghcr.io/devmesh-git/seerr-lists:latest

# Or specify a version (recommended for production)
docker run -d \
  --name seerr-lists \
  -p 8080:8080 \
  ghcr.io/devmesh-git/seerr-lists:v2.0.0

Building from Source

1. Ensure you have Go 1.22 or later installed.
2. Clone the repository:

   git clone https://github.com/devmesh-git/seerr-lists.git
   cd seerr-lists

3. Build:

   go mod tidy
   go build -o seerr-lists ./cmd/seerr-lists

4. Run:

   ./seerr-lists

Releases

This project uses automated releases triggered by git tags. Each version tag (e.g., v1.0.0) automatically:

• Builds and publishes multi-platform Docker images to GitHub Container Registry
• Creates cross-platform binaries (Linux, macOS, Windows) attached to GitHub Releases

Downloading Binaries

If you prefer to run seerr-lists as a native binary instead of Docker:

1. Go to Releases

2. Download the appropriate binary for your platform:

   • seerr-lists_linux_amd64 (Linux x86_64)
   • seerr-lists_linux_arm64 (Linux ARM64)
   • seerr-lists_darwin_amd64 (macOS Intel)
   • seerr-lists_darwin_arm64 (macOS Apple Silicon)
   • seerr-lists_windows_amd64.exe (Windows)

3. Make the binary executable and run:

   chmod +x seerr-lists_linux_amd64
   ./seerr-lists_linux_amd64

Development

Testing

The project includes two test scripts for development and testing:

run.sh - Local Development Script

A convenience script for running the service locally:

./run.sh

This script:

• Builds the application if needed (or uses existing binary)
• Runs the service locally for testing

The script automatically detects if the binary needs to be rebuilt based on source file timestamps.

test-endpoints.sh - Endpoint Testing Script

A simple test script that validates the service is running:

# Test against localhost (default)
./test-endpoints.sh

This script tests the health check endpoint to ensure the service is responsive.

Example Output:

============================================================
Testing seerr-lists endpoints
Base URL: http://localhost:8080
============================================================

Testing Health Endpoint
----------------------------------------
✓ Health check endpoint (HTTP 200)

============================================================
Test Summary
============================================================
Passed: 1
Failed: 0

All tests passed! ✓

Project Structure

seerr-lists/
├── cmd/
│   └── seerr-lists/
│       └── main.go           # Application entry point
├── Docker/
│   ├── Dockerfile
│   └── docker-compose.yml
├── internal/
│   ├── api/
│   │   ├── seerr.go          # Seerr API client
│   │   └── models.go         # API response models
│   ├── cache/
│   │   └── manager.go        # Cache management
│   ├── categories/
│   │   ├── fetcher.go        # Category fetching interface
│   │   └── registry.go       # Category registry
│   ├── config/
│   │   └── config.go         # Configuration management
│   ├── constants/
│   │   └── constants.go      # Shared constants
│   ├── managers/
│   │   ├── collection_manager.go # Plex collection management
│   │   ├── library_manager.go    # Plex library management
│   │   └── media_manager.go      # Media & stub file management
│   ├── models/
│   │   └── media.go          # Shared data models
│   ├── plex/
│   │   ├── client.go         # Direct Plex API client
│   │   ├── models.go         # Plex API models
│   │   └── resources.go      # Plex.tv resource handling
│   ├── server/
│   │   ├── auth_handlers.go  # Plex authentication
│   │   ├── events.go         # SSE event handling
│   │   ├── handlers.go       # General HTTP handlers
│   │   ├── middleware.go     # HTTP middleware
│   │   ├── plex_handlers.go  # Plex-related endpoints
│   │   └── ui_handlers.go    # Dashboard UI endpoints
│   ├── utils/
│   │   └── utils.go          # Utility functions
│   └── version/
│       └── version.go        # Version information
├── web/                      # Embedded Web Dashboard
│   ├── app.js
│   ├── index.html
│   ├── setup.html
│   ├── setup.js
│   └── styles.css
├── go.mod
├── LICENSE
├── PRIVACY.md
└── README.md

Adding a New Category

1. Create a new fetcher file in internal/categories/
2. Implement the CategoryFetcher interface
3. Register the fetcher in cmd/seerr-lists/main.go
4. Update this README with category details

Error Handling

• 404: Category not found (invalid category ID)
• 500: Internal server error (API error, etc.)
• 503: Service unavailable (during startup/shutdown)

All errors are logged with structured logging. API keys are never logged.

Performance

• Startup time: < 2 seconds
• Memory footprint: < 100MB
• Cache hit response time: < 1 second
• Cache miss response time: < 5 seconds (depending on API response time)

Limitations

• No user context: Service uses a single API key (no per-user watchlists)
• Polling-based: Updates every minute
• In-memory cache: Cache is lost on service restart
• No database: No persistence of cache or configuration

Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

Please make sure your code follows existing style conventions and includes tests where appropriate.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Privacy

This project does not collect or store personal information. See PRIVACY.md for more details.

Acknowledgments

• Built for the Seerr ecosystem
• Designed to bridge the gap between Seerr discovery and your Plex library

Support

• Issues: GitHub Issues
• Discussions: GitHub Discussions