FreshRSS Raspberry Pi: Complete Feeds and Filters Guide

Q: Do mobile apps work on a local network without internet exposure?

Yes. Set the server URL to http:// :8080 and the app syncs over local Wi-Fi. For access away from home without public exposure, connect via WireGuard VPN.

Q: How do I reset the FreshRSS admin password?

Run: docker exec -it freshrss php /var/www/FreshRSS/cli/reset-password.php --user admin --password new-password-here

FreshRSS Raspberry Pi gives you a self-hosted RSS aggregator that pulls articles from any feed you choose, filters out what you do not want, and syncs to Android and iOS clients without any cloud service deciding what is relevant to you. FreshRSS runs on a Pi 4 in a Docker container, stores everything in SQLite, and exposes a Google Reader-compatible API that works with every major mobile RSS client. This guide covers Docker Compose installation, feed configuration, filter rules, mobile client setup, HTTPS access, and backups.

Key Takeaways

Mobile apps connect to FreshRSS via the Google Reader API, not the Fever API. The Google Reader API is the current recommended path and is supported by FeedMe, Read You, NetNewsWire, and Reeder. Enable it in FreshRSS under Settings > Authentication > Allow API access.
FreshRSS does not automatically refresh feeds without configuration. The official Docker image supports a CRON_MIN environment variable that runs the refresh schedule inside the container. Set it in compose.yaml and no external cron job is needed.
SQLite is adequate for a single user with under 200 feeds. For multiple users or very high feed volume, switch to MariaDB at install time. Migrating the database after the fact is possible but tedious.

FreshRSS Raspberry Pi: How It Works

FreshRSS is a PHP web application that fetches RSS and Atom feeds on a schedule, stores article metadata and content in a database, and serves a web interface for reading. It also exposes a Google Reader-compatible API that mobile clients use to sync read state, starred articles, and subscriptions across devices. All data stays on the Pi. No third-party server is involved.

The filter engine runs after fetch. When a new article arrives, FreshRSS applies your filter rules before it appears in the feed. Rules can match on title, content, author, URL, or any combination, using plain strings or regular expressions. An article that matches a mark-as-read rule disappears from the unread count without cluttering your reading queue.

Feature	FreshRSS (self-hosted)	Feedly	Inoreader
Data location	Your hardware	Cloud	Cloud
Cost	Free	Free tier + paid	Free tier + paid
Feed limit	Unlimited	100 (free)	150 (free)
Filter rules	Unlimited, regex	Limited (paid)	Limited (paid)
Google Reader API	Yes	No	Yes
Self-hosted	Yes	No	No

Installation with Docker Compose

Flash Raspberry Pi OS Bookworm Lite 64-bit using Raspberry Pi Imager. In the advanced settings, set hostname, enable SSH, and configure credentials. After first boot:

sudo apt update && sudo apt full-upgrade -y

# Install Docker and Compose v2
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh
sudo usermod -aG docker $USER
sudo apt install docker-compose-plugin -y

Log out and back in, then create the project directory:

mkdir -p ~/freshrss && cd ~/freshrss

Create compose.yaml:

services:
  freshrss:
    image: freshrss/freshrss:latest
    container_name: freshrss
    restart: unless-stopped
    ports:
      - "127.0.0.1:8080:80"
    environment:
      TZ: America/Chicago
      CRON_MIN: "*/15"
    volumes:
      - ./data:/var/www/FreshRSS/data
      - ./extensions:/var/www/FreshRSS/extensions

The CRON_MIN: "*/15" environment variable tells the container to refresh all feeds every 15 minutes. The port binding 127.0.0.1:8080:80 keeps FreshRSS reachable only from the Pi itself. Caddy proxies external traffic to it.

docker compose up -d
docker compose logs -f freshrss

Expected result: The log shows FreshRSS starting and the cron scheduler initialising with a 15-minute interval. Navigate to http://<pi-ip>:8080 and the FreshRSS install wizard appears. Work through the wizard to set your admin credentials and confirm SQLite as the database.

Manual install note

FreshRSS can be installed manually with PHP, Nginx, and SQLite or MariaDB for users who prefer direct control over the web server configuration. The official documentation at freshrss.github.io covers this path. For most Pi homelab setups, Docker Compose is the easier and more maintainable option.

HTTPS Access with Caddy

Mobile clients require HTTPS for API sync. Install Caddy and add a single block to the Caddyfile:

rss.yourdomain.duckdns.org {
    reverse_proxy localhost:8080
}

For the full Caddy installation and DuckDNS setup, see Caddy Reverse Proxy Raspberry Pi. Forward ports 80 and 443 on your router to the Pi. After Caddy is running, update the FreshRSS base URL in Settings > System Configuration > Base URL to match your HTTPS domain. This is required for the API to work correctly from external clients.

Expected result: Navigating to https://rss.yourdomain.duckdns.org shows the FreshRSS login page with a valid Let’s Encrypt certificate. The API endpoint at https://rss.yourdomain.duckdns.org/api/greader.php returns a response when accessed.

Configuring Feeds and Organisation

Add feeds by pasting a URL into the subscription box under Subscriptions > Add Feed. FreshRSS auto-detects feed URLs from most web pages. For bulk imports, export an OPML file from your previous reader and import it under Subscriptions > Import/Export.

Categories are folders. Each feed belongs to one category. Tags cross-reference articles across categories. A common setup for a tech-focused reader: categories of Tech, Security, Long Reads, and DIY; tags of Read Later, Reference, and Project Ideas. Each feed can also have its own refresh interval set per subscription. High-volume feeds work well at 30 minutes; low-volume longform blogs at 12 or 24 hours.

Filters and Reading Rules

FreshRSS Raspberry Pi feed ingestion flow diagram showing RSS sources filter engine and mobile client sync

Filters are configured under Subscriptions > Filter Rules for global rules, or per feed in the feed settings. Each filter defines a condition and an action.

Match target	Operators	Example
Title	contains, matches (regex)	Title contains “sponsored”
Content	contains, matches (regex)	Content matches `.press release.`
Author	contains	Author contains “Staff Reporter”
URL	contains, matches (regex)	URL contains “utm_source”

Action	Effect
Mark as read	Skipped in unread count, still visible under All Articles
Mark as favourite	Article is starred automatically
Delete	Article is permanently removed
Add label	Applies a tag for cross-feed organisation

Practical filter examples

# Mark as read: clickbait title patterns
# Regex: Title matches .*(you won't believe|things that|goes viral).*

# Mark as read: known content farm domains
# URL contains: buzzfeed.com

# Keep only security articles from a broad tech feed
# Mark as read: Title does not match .*(CVE|vulnerability|patch|security|breach).*

Regex filters run against the full title or content string. Test filters by adding a feed with known article titles that should be caught, verifying they disappear from the unread list, then checking All Articles to confirm they were marked read rather than deleted.

Mobile Clients

Before connecting any client, enable API access in FreshRSS under Settings > Authentication. Check “Allow API access” and set an API password separate from your login password. The Google Reader API endpoint is:

https://rss.yourdomain.duckdns.org/api/greader.php

Client	Platform	API	Notes
FeedMe	Android	Google Reader	F-Droid + Play Store, offline reading, solid sync
Read You	Android	Google Reader	Open source, Material 3 UI, active development
Reeder 5	iOS / macOS	Google Reader	Best iOS option, clean UI, paid app
NetNewsWire	iOS / macOS	Google Reader	Free, open source, syncs across Apple devices
Fluent Reader	Windows / Linux	Google Reader	Desktop access, Electron app

To connect FeedMe on Android: Settings > Account > Add Account > FreshRSS (Google Reader compatible). Enter your server URL, FreshRSS username, and the API password from the Authentication settings. The PWA is also available. Open the HTTPS URL in Chrome or Safari and use Add to Home Screen for a native-app feel.

Storage, Retention, and Backups

FreshRSS retains articles according to the retention policy set per feed or globally. The default keeps articles for 30 days or the last 200 per feed. Reduce this for high-volume feeds you read daily. Seven days is adequate for news aggregators. Starred articles are kept indefinitely regardless of retention policy.

Back up the ./data directory and your OPML export. A daily backup script:

#!/bin/bash
TIMESTAMP=$(date +%Y%m%d-%H%M)
mkdir -p ~/freshrss/backups
tar -czf ~/freshrss/backups/freshrss-$TIMESTAMP.tar.gz -C ~/freshrss/data .
ls -tp ~/freshrss/backups/*.tar.gz | tail -n +15 | xargs -I {} rm -- {}

For encrypted, deduplicated backups with retention management, see BorgBackup Raspberry Pi Prune Policies. For remote access without internet exposure, see WireGuard Raspberry Pi Site-to-Site VPN.

Security

sudo apt install ufw fail2ban -y
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw enable

Disable user registration once your account is set up. In Settings > System Configuration, set “Allow anonymous access” to No and “Registration enabled” to No. FreshRSS does not have native 2FA. For an extra authentication layer, configure Caddy with HTTP basic auth in front of the FreshRSS block. Google Reader API clients handle basic auth natively so app sync continues to work.

Troubleshooting

Feeds not updating

# Trigger a manual feed update
docker exec freshrss php /var/www/FreshRSS/app/actualize_script.php

# Check cron is running
docker exec freshrss cat /var/log/cron.log

If the cron log is empty, confirm CRON_MIN is set in compose.yaml and restart the container. If individual feeds show errors, check the feed URL in a browser. The source may have changed URL or gone offline.

Mobile client cannot connect

Check in this order: API access is enabled in FreshRSS Authentication settings, the API password (not the login password) is being used, and the base URL in FreshRSS Settings matches the HTTPS domain. These account for the majority of connection failures.

Permission errors after container restart

sudo chown -R 1000:1000 ~/freshrss/data
docker compose restart freshrss

Updating FreshRSS

docker compose pull
docker compose up -d
docker image prune -f

FAQ

Can FreshRSS run on a Raspberry Pi Zero 2 W?

Yes, with limitations. Keep feeds under 50 and set refresh intervals to 30 minutes or longer. Docker adds overhead compared to a bare PHP install. For larger feed collections, Pi 4 with 2GB RAM is the practical minimum.

How do I reset the FreshRSS admin password?

docker exec -it freshrss php /var/www/FreshRSS/cli/reset-password.php \
  --user admin --password new-password-here

Do mobile apps work on a local network without internet exposure?

Yes. Set the server URL to http://<pi-ip>:8080 and the app syncs over local Wi-Fi. For access away from home without public exposure, connect via WireGuard VPN. The app reaches the Pi at its LAN address through the tunnel.

Can I import feeds from Feedly or Inoreader?

Yes. Export an OPML file from your current reader and import it in FreshRSS under Subscriptions > Import/Export > Import. All feed subscriptions import in one step. Filter rules and starred articles need to be set up manually after import.

What is the difference between the Google Reader API and Fever API?

The Google Reader API is the current recommended option. It supports full read state sync, starred articles, labels, and subscriptions. The Fever API is an older protocol with more limited features. If your app supports both, use Google Reader.

References

About the Author

Chuck Wilson has been programming and building with computers since the Tandy 1000 era. His professional background includes CAD drafting, manufacturing line programming, and custom computer design. He runs PidiyLab in retirement, documenting Raspberry Pi and homelab projects that he actually deploys and maintains on real hardware. Every article on this site reflects hands-on testing on specific hardware and OS versions, not theoretical walkthroughs.

Last tested hardware: Raspberry Pi 4 Model B (4GB). Last tested OS: Raspberry Pi OS Bookworm Lite 64-bit. FreshRSS 1.24.3, Docker 27.3, FeedMe on Android, Reeder on iOS.

Was this helpful?

Yes

Thanks for your feedback!