rsspub

rsspub is a self-hosted Rust application that turns your favorite RSS/Atom feeds/ Read Later articles into a personal daily newspaper (EPUB). It fetches articles, processes images, and bundles everything into an EPUB file that you can read on your e-reader or tablet.

It also serves an OPDS feed, making it easy to download the generated EPUBs directly to compatible readers (like KOReader, Moon+ Reader, etc.).

Features

• Read It Later: Save articles to read later. It will created different EPUB for read later articles and marked as read once epub is generated.(Can be saved via web UI or post request via IOS shortcut or Android app http shortcut
• RSS/Atom Parsing: Automatically fetches and parses content from your configured feeds.
• EPUB Generation: Compiles articles into a well-formatted EPUB ebook.
• Image Optimization: Downloads and processes images for optimal e-reader viewing (grayscale, resizing).
• Web Interface: A simple web UI to manage feeds, schedules, and manually trigger generation.
• OPDS Catalog: Built-in OPDS server (/opds) to browse and download generated EPUBs.
• Email Delivery: Automatically send generated EPUBs to a configured email address.
• Latest Downloads Fetch the latest generated epub directly via (hostname/downloads/latest_rss.epub) and (hostname/downloads/latest_readlater.epub)
• Scheduling: Automated generation based on cron expressions.
• Authentication: Optional Basic Authentication to protect your instance.
• Performance: Built with Rust, Axum, and Tokio for high performance and low resource usage.

Roadmap

• Add email send option for Kindle
• Add basic Read it later feature.
  • Add basic "Share" App to add read it later article for ios,android and browser extension.
• Make it multi-platform via Tauri or Dioxus
• Add user defined custom article extraction logic via Scrapper dom_query crate
  • add deduplication logic for Custom Extractor
  • add another option to fetch content from rss itself
• Add configuration for few of the hardcoded settings
• Cleanup unused/unnecessary features
• Refactor OPDS server according to the official spec.

Getting Started

Prerequisites

• Rust (latest stable)
• (Optional) libvips if using the mem_opt feature for optimized image processing.

Installation

1. Clone the repository:

   git clone https://github.com/yourusername/rsspub.git
   cd rsspub

2. Run the application:

   cargo run

   The server will start at http://0.0.0.0:3000.

Docker

You can also run rsspub using Docker Compose.

1. Make sure you have Docker and Docker Compose installed.
2. (Optional) Create a .env file to configure environment variables:

   RPUB_USERNAME=your_username
   RPUB_PASSWORD=your_password
   SECURE_OPDS=false

3. Run the application:

   docker-compose up -d

   The server will start at http://localhost:3000.

Manual Build:

To build the Docker image manually:

docker build -t rsspub .

To run the container:

docker run -p 3000:3000 -v $(pwd)/data:/app/db rsspub

Usage

1. Open the Web UI: Navigate to http://localhost:3000 in your browser.
2. Add Feeds: Use the interface to add the RSS/Atom feed URLs you want to follow.
3. Generate EPUB: Click the "Generate" button (or configure a schedule) to create an EPUB from the latest articles.
4. Download:
   • Direct Download: Download generated EPUBs from the "Downloads" section in the UI.
   • OPDS: Add http://<your-server-ip>:3000/opds to your e-reader's OPDS catalog list.

Email Configuration

You can configure the application to automatically send generated EPUBs via email (e.g., to your Send-to-Kindle address).

• Gmail Configuration: Tested with smtp.gmail.com on port 587.
• App Password: If using Gmail, you must use an App Password (your regular password will not work).
• Recommendation: It is recommended to use a temporary or dedicated email account for this feature, rather than your primary personal account.

Configuration

You can configure the application using environment variables:

• RPUB_USERNAME: Set a username for Basic Authentication.
• RPUB_PASSWORD: Set a password for Basic Authentication.
• SECURE_OPDS : Secure Download routes with Basic Authentication.

If these variables are set, the Web UI and API (except /opds) will require authentication.

Read It Later

You can save individual articles to be included in your next daily EPUB delivery.

Web UI:

1. Go to the "Read Later" tab.
2. Paste the article URL and click "Add".

Android Integration (HTTP Shortcuts): You can easily add articles from your Android phone using the HTTP Shortcuts app.

1. Install the "HTTP Shortcuts" app.
2. Create a new shortcut:
   • Name: Add to rsspub
   • Method: POST
   • URL: http://<your-server-ip>/read-it-later
   • Body Type: JSON
   • Body Content:

     {
       "url": "{share_text}"
     }

   • Note: {share_text} is a variable that will be replaced by the URL you share.
3. Authentication (if enabled):
   • Go to "Authentication" section of the shortcut settings.
   • Select "Basic Authentication".
   • Enter your RPUB_USERNAME and RPUB_PASSWORD.
4. Usage:
   • When browsing an article in Chrome or any app, tap Share.
   • Select HTTP Shortcuts.
   • Select your Add to rsspub shortcut.

Added sample rsspub_http_shortcuts.json which can be imported in the app.

IOS Integration (Inbuild Shortcut):

Content Extraction

rsspub supports three content extraction methods for fetching full article content. You can configure the extractor per feed in the UI.

Extractor	Description
Default	Uses dom_smoothie crate with Readability algorithm. Best for most websites. Automatically extracts the main article content.
DomSmoothie	Uses dom_smoothie crate's native extraction logic. Alternative to Readability that may work better for certain sites.
Custom (Experimental)	CSS selector-based extraction. Allows you to define custom selectors to extract content and discard unwanted elements.

Custom Extractor Configuration

For sites where automatic extraction doesn't work well, you can define custom CSS selectors using YAML format:

selector:
  - '.article-content'
  - '.post-body'
  - 'article'
discard:
  - '.ads'
  - '.sidebar'
  - '.comments'
  - '.social-share'
output_mode: html

Fields:

• selector (required): Array of CSS selectors to extract content from. The extractor will use the first matching selector.
• discard (optional): Array of CSS selectors for elements to remove from the extracted content.
• output_mode (optional): Output format - html (default) or text.

Domain Override

Domain Override allows you to set a custom content processor for a specific domain. This applies to both RSS feed articles and Read It Later articles.

Use Case: This is particularly useful when a feed contains links to multiple external URLs. For example:

• HackerNews - Links to various external sites

Configuration:

1. Go to the "Domain Overrides" section in the UI.
2. Add the domain with subdomain (e.g., www.example.com, subdomain.example.com).
3. Select the processor type (Default, DomSmoothie, TextOnly, or Custom).
4. Optionally provide a custom configuration (YAML format) for the Custom processor.

When processing an article, rsspub will check if a domain override exists for the article's URL and use the configured processor instead of the feed's default.

### Building with Optimization (Optional)

For better memory usage during image processing (recommended for low-memory devices), you can enable the mem_opt feature (requires libvips installed on your system):

cargo run --features mem_opt

Alternatives

• Calibre: Calibre also has a "Fetch News" feature that can download RSS feeds and convert them to EPUB/MOBI. It is a desktop application, whereas rsspub is designed to run as a server.
• KindleEar: KindleEar is a Calibre port that runs on web to aggregate RSS feeds and send them to your Kindle.(https://github.com/harshit181/KindleEar minor code change to enable opds server)

Architecture

• Backend: Rust (Axum, Tokio)
• Database: SQLite (Rusqlite)
• Frontend: Static HTML/CSS/JS served by Axum
• Image Processing: image crate (default) or libvips (optional)

License

MIT License