RSSPub

KO | EN

gitlite — search

#typescript #ai-agents #deepseek-harness #dsh-plugin #open-source #ai #cli #dsh #claude-code #codex #developer-tools #react

★ 129 Open GitHub ↗

Turn your RSS feeds and Read later articles into a personal daily newspaper for your e-reader.

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# rsspub
[![Deploy to Koyeb](https://www.koyeb.com/static/images/deploy/button.svg)](https://app.koyeb.com/deploy?name=rsspub&type=docker&image=harshit181%2Frsspub%3Alatest&instance_type=eco-nano&regions=sin&env%5BRPUB_PASSWORD%5D=root&env%5BRPUB_USERNAME%5D=root&ports=3000%3Bhttp%3B%2F&hc_protocol%5B3000%5D=tcp&hc_grace_period%5B3000%5D=5&hc_interval%5B3000%5D=30&hc_restart_limit%5B3000%5D=3&hc_timeout%5B3000%5D=5&hc_path%5B3000%5D=%2F&hc_method%5B3000%5D=get)

**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.).

![rsspub screenshot](https://raw.githubusercontent.com/harshit181/RSSPub/master/screenshot.png)
![rsspub screenshot](https://raw.githubusercontent.com/harshit181/RSSPub/master/screenshot2.png)
![rsspub screenshot](https://raw.githubusercontent.com/harshit181/RSSPub/master/screenshot3.png)

## 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](https://play.google.com/store/apps/details?id=ch.rmy.android.http_shortcuts&hl=en_IN)
- **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

- [x] Add email send option for Kindle
- [x] 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
- [x] Add user defined custom article extraction logic via <s>Scrapper</s> [dom_query](https://github.com/niklak/dom_query) crate
    - [x] add deduplication logic for Custom Extractor
    - [ ] add another option to fetch content from rss itself
- [x] 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:
    ```bash
    git clone https://github.com/harshit181/RSSPub.git
    cd rsspub
    ```

2.  Run the application:
    ```bash
    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:
    ```env
    RPUB_USERNAME=your_username
    RPUB_PASSWORD=your_password
    SECURE_OPDS=false
    ```
3.  Run the application:
    ```bash
    docker-compose up -d
    ```
    The server will start at `http://localhost:3000`.

**Manual Build:**

To build the Docker image manually:

```bash
docker build -t rsspub .
```

To run the container:
```bash
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).
- **SMTP Username:** Can be configured separately from the sender email address. If left empty, RSSPub falls back to the sender email address.
- **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.
-   `EMAIL_TLS`: Configure SMTP encryption mode. Defaults to `starttls`.
    -   `starttls` : Uses STARTTLS for opportunistic encryption.
    -   `relay`    : Uses implicit TLS.
    -   `plaintext`: Uses an unencrypted connection.

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](https://play.google.com/store/apps/details?id=ch.rmy.android.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:**
        ```json
        {
          "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`](https://github.com/niklak/dom_smoothie) crate with Readability algorithm. Best for most websites. Automatically extracts the main article content. |
| **DomSmoothie** | Uses [`dom_smoothie`](https://github.com/niklak/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:

```yaml
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.

<s>    
### 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
</s>

### Alternatives

- **Calibre:** [Calibre](https://calibre-ebook.com/) 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](https://github.com/cdhigh/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](LICENSE)

RSSPub

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README