reFreshRSS

Your feeds. Your rules. On iOS.

A privacy-first RSS reader that pairs with your FreshRSS server and delivers a Google Discover–style browsing experience — entirely on your device. This is the PWA edition of FresshReader, built so iPhone/iPad users can install it from their browser and use it the same way Android users use the native app.

Every article, feed, sync, and ranking decision is fully auditable. The source is open, the algorithms are documented, and nothing happens in secret.

---

What it is

reFreshRSS bundles two things into one self-hostable package:

1. FreshRSS — the RSS aggregator/server (source of truth for fetching & storing feeds). Used unchanged from upstream.
2. The reFreshRSS PWA — a Progressive Web App that replicates the FresshReader Android app's design, icons, and functionality, installable on iOS/Android.

A guided installer (a web wizard with plain-language help on every step) collects everything needed and brings both the server and the app into a working state — no server experience required.

Highlights

• FreshRSS Greader API sync (auth, subscriptions, articles, read/star push-back)
• Discover feed with on-device ranking (recency, source weighting, cooldown, category balancing, duplicate clustering) — fully explainable
• Five feed modes: Discover (Balanced / Priority), Latest, Starred, Catch Up
• Offline support (articles cached locally, readable without network)
• Pull-to-refresh manual sync
• Material 3 design perfectly matching the Android app (Hero/Medium/Compact layouts)
• Interactive swipe-to-mark-read and swipe-to-star gestures
• Installable PWA with an app-icon launch on iOS home screen

Privacy & security

• Same-origin architecture: the PWA only ever talks to your FreshRSS server. No third parties, no analytics, no telemetry.
• Credentials are encrypted at rest in the browser (WebAuthn PRF hardware-backed key, or a local passphrase via PBKDF2 + AES-GCM). Your password is never sent anywhere except to your own FreshRSS server, over HTTPS.
• See PRIVACY.md and SECURITY.md.

Installation

reFreshRSS is designed to be self-hosted and comes with an automated, built-in setup wizard. You don't need any prior server experience to get it running.

1. Clone the repository:

   git clone https://forge.sabylasolutions.com/sabyla/reFreshRSS.git
   cd reFreshRSS
   

2. Start the Setup Wizard: Run the following command to boot up the installer (requires Docker):

   docker compose up -d
   

3. Run the Configuration Wizard: Open your browser and navigate to http://localhost:8088/app/setup/. The friendly wizard will walk you through:

   • Setting up your domain or local network address.
   • Creating your FreshRSS admin account.
   • Generating a secure API password.
   • Choosing your app paths and themes.

4. Automated Provisioning: Once you click "Install", the wizard handles the heavy lifting in the background. It provisions the FreshRSS database, creates your configuration files, locks the setup screen for security, and automatically brings the app online!

Usage

Once installed, navigate to your configured domain (e.g., https://yourdomain.com/app) on your mobile device.

Installing the PWA

reFreshRSS is a Progressive Web App (PWA) designed to look and feel like a native mobile app. For the best experience, you should install it to your home screen:

• iOS (Safari): Tap the Share button at the bottom of the screen, then scroll down and tap Add to Home Screen.
• Android (Chrome): Tap the three-dot menu and select Install App or Add to Home screen.

Interacting with Feeds

• Swipe Gestures: Swipe left on an article card to mark it as read, or swipe right to star/unstar it.
• Pull-to-Refresh: Simply pull down from the top of your feed to manually sync and fetch new articles from your server.
• Offline Reading: Articles you've synced are automatically cached, meaning you can read your feeds even when you don't have an active internet connection.

Status

Planning complete; implementation in progress (see PLAN.md milestones).

License

Proposed Apache License 2.0 (matching FresshReader).