# FreshRSS — Self-Hosted RSS News Aggregator

> FreshRSS is a free, self-hosted RSS feed aggregator with a modern web interface, multi-user support, Fever/Google Reader API, and browser/mobile app compatibility.

## Install

Save the content below to `.claude/skills/` or append to your `CLAUDE.md`:

## Quick Use

```bash
docker run -d --name freshrss -p 8080:80 
  -v freshrss-data:/var/www/FreshRSS/data 
  -e CRON_MIN=*/15 
  -e TZ=Asia/Shanghai 
  freshrss/freshrss:latest
```

Open `http://localhost:8080` — complete setup and add your first RSS feeds.

## Intro

**FreshRSS** is a free, self-hosted RSS feed aggregator and news reader. It provides a clean, responsive web interface for following hundreds of RSS/Atom feeds, with features like full-text search, tagging, filtering, keyboard navigation, and API compatibility with popular RSS apps (Reeder, NetNewsWire, FeedMe).

With 14.7K+ GitHub stars and AGPL-3.0 license, FreshRSS is one of the most popular self-hosted RSS readers, offering a fast, feature-rich alternative to Google Reader (RIP) and commercial services like Feedly.

## What FreshRSS Does

- **Feed Aggregation**: Subscribe to unlimited RSS/Atom feeds with automatic refresh
- **Reading Experience**: Clean article view with keyboard shortcuts, themes, and reading modes
- **Full-Text Retrieval**: Fetch full article content even from partial-content feeds
- **Categories & Tags**: Organize feeds into categories and tag individual articles
- **Search**: Full-text search across all articles with filters
- **Fever API**: Compatible with Fever API clients (Reeder, Unread, etc.)
- **Google Reader API**: Compatible with Google Reader API clients (NetNewsWire, FeedMe, etc.)
- **Multi-user**: Multiple accounts with independent feed lists and settings
- **Extensions**: Plugin system for extending functionality
- **WebSub/PubSubHubbub**: Real-time push updates from supported feeds

## Architecture

```
┌──────────────┐     ┌──────────────┐     ┌──────────────┐
│  Web UI      │────▶│  FreshRSS    │────▶│  SQLite /    │
│  (PHP)       │     │  Server      │     │  MySQL /     │
├──────────────┤     │  (PHP)       │     │  PostgreSQL  │
│ Mobile Apps  │────▶│  Fever API   │     └──────────────┘
│ (via API)    │     │  GReader API │
└──────────────┘     └──────────────┘
```

## Self-Hosting

### Docker Compose

```yaml
services:
  freshrss:
    image: freshrss/freshrss:latest
    ports:
      - "8080:80"
    environment:
      TZ: Asia/Shanghai
      CRON_MIN: "*/15"        # Refresh feeds every 15 minutes
    volumes:
      - freshrss-data:/var/www/FreshRSS/data
      - freshrss-extensions:/var/www/FreshRSS/extensions
    restart: unless-stopped

volumes:
  freshrss-data:
  freshrss-extensions:
```

### With PostgreSQL

```yaml
services:
  freshrss:
    image: freshrss/freshrss:latest
    ports:
      - "8080:80"
    environment:
      TZ: Asia/Shanghai
      CRON_MIN: "*/15"
    volumes:
      - freshrss-data:/var/www/FreshRSS/data
    depends_on:
      - db

  db:
    image: postgres:16-alpine
    environment:
      POSTGRES_USER: freshrss
      POSTGRES_PASSWORD: freshrss
      POSTGRES_DB: freshrss
    volumes:
      - pg-data:/var/lib/postgresql/data

volumes:
  freshrss-data:
  pg-data:
```

## Key Features

### Feed Organization

```
Categories:
├── 📰 Tech News
│   ├── Hacker News
│   ├── The Verge
│   ├── Ars Technica
│   └── TechCrunch
├── 💻 Dev Blogs
│   ├── Rust Blog
│   ├── Go Blog
│   ├── React Blog
│   └── Cloudflare Blog
├── 🎙️ Podcasts
│   ├── Changelog
│   └── Syntax.fm
└── 📊 Finance
    ├── Bloomberg
    └── Financial Times
```

### Reading Modes

- **Normal**: Title + summary in feed list
- **Global**: All articles from all feeds in one view
- **Reader**: Full article content inline
- **Compact**: Title-only list for fast scanning

### Keyboard Shortcuts

```
j/k    — Next/Previous article
n/p    — Next/Previous feed
s      — Star/Favorite article
m      — Mark as read/unread
v      — Open original article
Space  — Scroll or next article
r      — Refresh current feed
```

### Mobile Apps (via API)

Configure these apps with your FreshRSS instance:

| Platform | App | API |
|----------|-----|-----|
| iOS | Reeder 5 | Fever/GReader |
| iOS | NetNewsWire | GReader |
| iOS | Unread | Fever |
| Android | FeedMe | GReader |
| Android | Read You | GReader |
| Android | EasyRSS | GReader |
| Desktop | Fluent Reader | Fever |
| CLI | Newsboat | GReader |

### Full-Text Retrieval

For feeds that only provide summaries:

```
Settings → Feed → Content retrieval:
  ✅ Retrieve full content
  CSS selector: article.post-content  (optional)
```

FreshRSS will fetch the full article from the original website.

### Extensions

Available extensions:
- **YouTube**: Subscribe to YouTube channels as RSS feeds
- **Reddit**: Follow subreddits via RSS
- **Image Proxy**: Proxy images through your server for privacy
- **Reading Time**: Show estimated reading time
- **Title Wrap**: Better title display for long titles
- **CustomCSS**: Apply custom CSS themes

## FreshRSS vs Alternatives

| Feature | FreshRSS | Miniflux | Tiny Tiny RSS | Feedly |
|---------|----------|----------|---------------|--------|
| Open Source | Yes (AGPL-3.0) | Yes (Apache) | Yes (GPL) | No |
| Self-hosted | Yes | Yes | Yes | No |
| Language | PHP | Go | PHP | N/A |
| Multi-user | Yes | Yes | Yes | Cloud |
| Mobile API | Fever + GReader | Fever + own | Own API | Proprietary |
| Extensions | Yes | No | Plugins | No |
| Full-text retrieval | Yes | Yes | Plugins | AI |
| Resource usage | Low (~30MB) | Very low (~15MB) | Medium | N/A |
| Setup complexity | Easy | Easy | Moderate | N/A |

## FAQ

**Q: How many feeds can FreshRSS handle?**
A: There's no hard limit. Typical users run smoothly with 100–500 feeds. Beyond 1,000 feeds, switch to PostgreSQL and increase the refresh interval.

**Q: Can I subscribe to sites that don't provide RSS?**
A: Yes, via third-party services. RSS-Bridge or RSSHub can generate RSS feeds for platforms like Twitter, Instagram, YouTube, and Reddit, which you then subscribe to in FreshRSS.

**Q: How do I use it on mobile?**
A: Enable the Fever API or Google Reader API in FreshRSS settings, then point your mobile RSS reader at your FreshRSS server. On iOS, Reeder or NetNewsWire are recommended; on Android, FeedMe or Read You.

## Sources & Credits

- GitHub: [FreshRSS/FreshRSS](https://github.com/FreshRSS/FreshRSS) — 14.7K+ ⭐ | AGPL-3.0
- Website: [freshrss.org](https://freshrss.org)

---
Source: https://tokrepo.com/en/workflows/freshrss-self-hosted-rss-news-aggregator-cad151ae
Author: Script Depot