How to Use FreshRSS: The Beginner's Guide (First Compose, the CRON_MIN Rule, First Feed, and the OPML Lesson)

CodexFuse Team · 2026-11-01T03:50:00.000Z · 15 min read

Learn how to use FreshRSS, the self-hosted RSS reader: Docker Compose install, the CRON_MIN rule, the install wizard, your first feed, OPML import from Feedly, categories, HTTPS, and mobile apps.

What Is FreshRSS — and Why Would You Self-Host It?

FreshRSS is a free, open-source, self-hosted RSS reader: it collects the feeds you subscribe to — blogs, news sites, YouTube channels, podcasts, release notes — and shows them in one clean web app that you run on your own server. If you are wondering how to use freshrss, the short version is this: you install it with Docker Compose, turn on its built-in feed-updater, walk a five-step install wizard, add your first feed, and import your old subscriptions from Feedly or Inoreader with one OPML file. This freshrss tutorial for beginners covers that whole arc — the compose file, the CRON_MIN rule, the wizard, your first feed, the OPML lesson, categories, HTTPS, and the phone apps — on one page.

FreshRSS is an AGPL-3.0 project that has been maintained since 2012, with roughly 16,471 GitHub stars and a release cadence that stayed active through October 2026 (the current 1.30.4 shipped on October 21, 2026). It is the classic "your own Feedly" self-hosted app: no account with a vendor, no algorithm deciding what you see, no subscription price. New to containers first? Our Docker beginner guide covers the compose basics this guide assumes.

How Do You Install FreshRSS with Docker?

Install FreshRSS with Docker Compose using the official freshrss/freshrss image, one data volume, and the CRON_MIN environment variable so feeds refresh themselves. That is the whole recipe — and it is the arc every recent guide on Google page 1 converges on (dev.to's serverkueche tutorial from about 30 days ago, fossengineer's compose guide, the official Docker Hub page). Here are the exact steps:

1. Create a folder and a compose file. Make a directory for the project (for example ~/freshrss) and put a docker-compose.yml inside it.
2. Use the official image. Set the image to freshrss/freshrss (the project also publishes ghcr.io/freshrss/freshrss; both are listed on the official Docker Hub page). The image serves the app on port 80 inside the container.
3. Mount the data volume. Mount a named volume to /var/www/FreshRSS/data — that is where the database, settings, and cached feeds live, so your subscriptions survive container updates.
4. Set CRON_MIN. Add CRON_MIN=13,43 to the environment (quoted as a string). This is the rule that turns on the built-in feed updater — the next section explains exactly what it does.
5. Set your timezone. Add TZ=America/New_York (or your own zone) so feed timestamps and the cron schedule read correctly.
6. Map a port. Map the container's port 80 to something like 8080 on the host: "8080:80".
7. Bring it up. Run docker compose up -d and wait a few seconds.
8. Open the wizard. Browse to http://YOUR-SERVER-IP:8080 — the install wizard starts automatically on first visit.
9. Run the five-step wizard. Pick a language, confirm the server checks pass, choose a database, create the admin account, and finish (section 5 walks the whole thing).
10. Add your first feed and press refresh. Subscribe to any blog, then click the refresh button in the UI to fetch it immediately instead of waiting for the first cron run.

The compose file looks like this (put your server's timezone in TZ):

services:
  freshrss:
    image: freshrss/freshrss:1.30.4
    container_name: freshrss
    environment:
      - TZ=America/New_York
      - "CRON_MIN=13,43"
    volumes:
      - freshrss-data:/var/www/FreshRSS/data
    ports:
      - "8080:80"
    restart: unless-stopped

volumes:
  freshrss-data:

Don't have a server to run this on? Our what is VPS hosting explainer covers the options — any small VPS is enough for a reader.

A note on image choice before you copy (fossengineer's 2025 guide, mariushosting's Synology guide from 9 days ago) use the third-party linuxserver/freshrss image instead. It works, but it is not mentioned anywhere in the official FreshRSS documentation — the official recommendation is the project's own image, so this guide uses it and you should too when following along.

What Does CRON_MIN Actually Do — the Cron Rule

CRON_MIN switches on the official image's built-in feed updater, and without it FreshRSS never refreshes your feeds on its own. Setting CRON_MIN=13,43 starts an internal cron that re-downloads your subscriptions at 13 and 43 minutes past every hour — no separate timer container, no host cron job, nothing else to install. This is the freshrss cron lesson every beginner must learn, because CRON_MIN is disabled by default: if you skip the variable, feeds update only when you press the refresh button in the web UI.

The official Docker README documents 13,43 as the recommended example and notes that cron-style values like */20 also work, but there is a hard floor you should know: the update script never re-downloads any single feed more often than once every 20 minutes, so setting a tighter interval is pointless. An empty string disables the cron outright. When you want to see that it is running, the docs suggest docker compose logs freshrss | grep -i cron. If you are in a hurry, two faster paths exist: the refresh button in the UI fetches feeds immediately, and from a terminal you can force a run with docker exec -u www-data freshrss ./cli/actualize-user.php.

What Happens in the Five-Step Install Wizard?

The install wizard turns a blank FreshRSS container into your personal reader in five steps: language and session check, server checks, database choice, general configuration, and done. The sequence is defined in the installer source (app/install.php on the project's edge branch), and the freshrss install behaves the same whether you used the official image or the third-party one.

Step 0 is a language picker plus a session check. Step 1 verifies the server: PHP version, PDO drivers, required extensions, and write permissions on the data directory. Step 2 is the database choice — SQLite, MySQL/MariaDB, or PostgreSQL. The official prerequisites page recommends PostgreSQL 10+ and lists SQLite as "also works with"; in practice, every beginner guide (including the 30-day-old dev.to tutorial) uses SQLite for a solo reader and it is genuinely fine for one person — you need PostgreSQL only when many users share the instance. Step 3 is general configuration: an instance title, the default admin user (usernames cap at 16 alphanumeric characters, per the MakeUseOf walkthrough), the authentication type (form, http_auth, or none), the admin password, and the auto-refresh-feeds toggle. Step 4 congratulates you and hands you the login.

You only need two things from step 2's decision: pick SQLite if this reader is just for you, and remember which admin username you chose — it is the login you will use forever.

How Do You Add Your First Feed?

To add a feed in FreshRSS, click the + button next to "Subscriptions management", paste the feed URL into the "Feed URL" field, and save. FreshRSS auto-detects the feed if the site declares it in a standard way — you can usually paste the site's homepage URL and it finds the feed itself, which is the shortcut beginners miss.

Feeds live inside categories, and the two management habits worth learning on day one are these. First, feeds can be moved between categories by drag-and-drop or through each feed's own settings (hover any feed or category and a gear icon appears). Second, a newly added feed does not fetch instantly: feeds update on the cron schedule, and the update script enforces a minimum of 20 minutes between updates of the same feed. So after adding your first feed, click the refresh/update button in the UI to fetch it immediately instead of staring at an empty list for twenty minutes. That one click is the most common beginner stumble, and it takes one second to fix.

While you are subscribing, it is worth knowing what FreshRSS is not. It subscribes to feeds — it does not watch arbitrary websites for changes. If you want alerts when a page without an RSS feed changes (price drops, restock notices, new releases on a site with no feed), that is a different job; our Changedetection.io beginner guide covers the website-change-monitoring lane. Feeds here, change-detection there — never rivals.

How Do You Import Your Old Feeds from Feedly with OPML?

You import your old feeds by going to Subscriptions management → Import / export, clicking Browse, selecting your OPML file, and clicking Import. That single flow is the OPML lesson and it is how everyone escaping Feedly, Inoreader, or Miniflux moves in one sitting.

The import accepts OPML exports from Feedly, Inoreader, and Miniflux, plus FreshRSS's own archive and JSON exports, and the same screen lets you export your feed list, labelled articles, and favourites — so leaving is just as easy as arriving. One documented limitation: FreshRSS cannot import a plain text list of feed URLs. If your old reader only gave you a text file, convert it to OPML first — the official user docs suggest Pandoc or opmlmaker for the conversion. Practical tip for the switch: import with cron already enabled (CRON_MIN from section 3), because a few hundred imported feeds will take a while to fetch the first time, and the staggered cron keeps it from hammering every server at once.

How Do You Organize Feeds with Categories?

Categories are folders for your feeds: create one per interest (Tech news, Blogs, Podcasts, Releases), put feeds inside it, and the reader's sidebar collapses each category into a readable outline. Feeds can be moved between categories by drag-and-drop or from the gear-icon settings on each feed, and hovering any feed or category reveals the gear that opens its options.

The habit that makes categories pay off is matching them to how often you want to read, not to the topic: a "Morning skim" category you open daily and an "Occasional" category you open on weekends keeps a 200-feed reader from feeling like a job. Categories also decide what the mobile apps show you (next section), so a tidy category tree is a tidy phone reading experience too.

FreshRSS vs Miniflux: Which One Should a Beginner Pick?

FreshRSS and Miniflux are the two names that come up in every "self hosted rss reader" comparison, and the short answer is: FreshRSS is the fuller-featured option for readers who want categories, a rich web UI, OPML tooling, and a huge client-app ecosystem; Miniflux is the leaner, minimalist alternative. (Miniflux stays a comparison member of this guide — it never gets its own page here.) The table below compares the beginner-relevant facts:

For a beginner, the FreshRSS install is the easier first day: the wizard holds your hand, SQLite means no separate database container, and the bigger client-app ecosystem means your phone reader probably already supports it. Choose Miniflux if you want the smallest possible footprint and a keyboard-driven minimalist UI.

How Do You Put FreshRSS Behind a Reverse Proxy with HTTPS?

You put FreshRSS behind a reverse proxy by forwarding HTTPS to the container's port 80, passing the X-Forwarded-Proto header so the app knows the original request was HTTPS, and setting the TRUSTED_PROXY environment variable to your proxy's IP range. This is the freshrss reverse proxy recipe, and the official Docker README documents it explicitly: TRUSTED_PROXY takes a space-separated list of trusted IPs or CIDRs (for example 172.16.0.1/12 192.168.0.1/16) and controls how the app logs client IPs and handles external authentication methods.

For Caddy specifically — the reverse proxy our guides standardize on — the official FreshRSS docs include a dedicated admin page for using Caddy as a reverse proxy, and our Caddy beginner guide walks the certificate setup. Two details to get right: the proxy must send X-Forwarded-Proto: https (the docs show the Apache equivalent as RequestHeader set X-Forwarded-Proto "https"), and if you serve FreshRSS in a subdirectory instead of its own subdomain, pass the prefix through with X-Forwarded-Prefix (the docs' example uses /freshrss). You need HTTPS before exposing the reader to the internet — the privacy section below explains why.

How Do You Read Your FreshRSS Feeds on Your Phone?

You read FreshRSS on your phone through a third-party app that talks to FreshRSS's Google-Reader-compatible API — and that is the freshrss mobile app lesson: there is no official mobile app, but the API support is excellent. FreshRSS exposes a GReader-compatible API at /api/greader.php (plus a Fever API), and enabling it takes two steps: go to Settings → Profile → "External access via API" and set a separate API password that is different from your login password.

With the API enabled and the API address in hand (https://your-instance/api/greader.php), the official docs name a long list of compatible clients. For iPhone readers there is Reeder Classic and Lire; for Android there is FeedMe, Readrops, News+, Fluent Reader Lite, FocusReader, and Read You; on the desktop there is Newsflash and Newsboat (2.24+) on Linux and Vienna RSS on macOS. Every one of them syncs the same read/unread state back to your server, so marking an article read on your phone clears it on your desktop too.

FreshRSS or Linkwarden — Which One Do You Need?

FreshRSS and Linkwarden solve different reading problems: FreshRSS subscribes to feeds and shows you new articles as they are published; Linkwarden saves individual pages you found elsewhere into a read-later library. If the habit is "tell me whenever this site publishes something new," that is FreshRSS. If the habit is "I found this article while browsing and want to read it this weekend," that is Linkwarden. Most readers eventually run both, and our Linkwarden beginner guide covers the read-later half. Never rivals — subscriptions and bookmarks live side by side.

What Is the One Privacy Rule for Self-Hosting FreshRSS?

Expose FreshRSS over HTTPS with authentication, and nothing less. Your feed list is a map of what you read, when you read it, and what you care about — the official Docker README ships auth enabled by default for exactly this reason, and the installer wizard's auth-type step (form, http_auth, or none) exists so you consciously pick one. Do not expose the raw port to the internet, do not leave authentication off "just until I set up HTTPS," and use the separate API password for phone apps rather than reusing your login password. Feed readers are personal infrastructure: treat the reader's door like your email's door.

Sources

• FreshRSS on GitHub (FreshRSS/FreshRSS) — version 1.30.4 released October 21, 2026; ~16,471 stars; AGPL-3.0 confirmed in the raw LICENSE.txt; default branch edge. https://github.com/FreshRSS/FreshRSS
• Official FreshRSS Docker Hub page (freshrss/freshrss) — official images freshrss/freshrss and ghcr.io/freshrss/freshrss; GNU AGPL 3 license. https://hub.docker.com/r/freshrss/freshrss
• Official FreshRSS Docker README — CRON_MIN disabled by default, "13,43" recommended example, per-feed 20-minute update floor, manual refresh and ./cli/actualize-user.php, TRUSTED_PROXY, port 80, data volume /var/www/FreshRSS/data. https://github.com/FreshRSS/FreshRSS/blob/edge/Docker/README.md
• Official FreshRSS installer source (app/install.php, edge branch) — the five wizard steps: language/session, server checks, database choice, general config, done. https://github.com/FreshRSS/FreshRSS/blob/edge/app/install.php
• Official FreshRSS prerequisites page — PostgreSQL 10+ recommended; SQLite, MariaDB 10.6+, MySQL 8.0+ also supported. https://freshrss.github.io/FreshRSS/en/admins/02_Prerequisites.html
• Official FreshRSS subscriptions user docs (04_Subscriptions.md) — "+" next to Subscriptions management, feed auto-detection, categories drag-and-drop, gear-icon settings, OPML Import/export path, plain-text-list limitation. https://github.com/FreshRSS/FreshRSS/blob/edge/docs/en/users/04_Subscriptions.md
• Official FreshRSS GReader API docs — /api/greader.php, Settings → Profile → External access via API, separate API password, compatible client list. https://freshrss.github.io/FreshRSS/en/users/06_Mobile_access.html
• serverkueche, "FreshRSS: Your Own RSS Reader" (dev.to, updated ~30 days before 2026-11-01) — official-image compose arc, CRON_MIN internal cron, wizard, OPML, GReader API with Reeder/FeedMe. https://dev.to/serverkueche/freshrss-your-own-rss-reader-5gin
• fossengineer, "FreshRSS Docker Setup" (Jan 2025) — compose self-host guide using the third-party linuxserver/freshrss image. https://fossengineer.com/freshrss-docker-setup/
• ossalt, "FreshRSS vs Miniflux 2026" (March 2026) — the comparison piece; its 14.4K-star claim is stale against the current ~16.4K. https://ossalt.com/guides/freshrss-vs-miniflux-2026
• mariushosting, "How to Install FreshRSS on Your Synology NAS" (updated ~9 days before 2026-11-01) — Synology Portainer guide, cites 1.30.4 as latest. https://mariushosting.com/synology-install-freshrss-with-portainer/
• MakeUseOf, "How to Install FreshRSS on a Raspberry Pi" (2022) — wizard walkthrough, admin username cap of 16 alphanumeric characters. https://www.makeuseof.com/how-to-install-freshrss-on-raspberry-pi/

Frequently Asked Questions

Is FreshRSS free?

Yes. FreshRSS is free and open-source under the AGPL-3.0 license — no paid tier, no account, no subscription. The only cost is whatever you already pay to run a server: the app itself runs fine on the same VPS most readers already keep, and the SQLite database needs no extra database container.

Do I need Docker to run FreshRSS?

No, but Docker is the documented beginner path. FreshRSS also runs on a manual LAMP stack (PHP + web server + database), which is what the older guides from 2022–2024 cover — but the official image with its built-in CRON_MIN updater is the setup the project's own docs now lead with, and this guide uses it for that reason.

Can I import my feeds from Feedly or Inoreader?

Yes, in one click. Export an OPML file from Feedly or Inoreader, then go to Subscriptions management → Import / export in FreshRSS, pick the file, and click Import. Feedly's export lives under its settings; the import works the same way for Miniflux exports and FreshRSS's own archive files.

Why aren't my new feeds updating?

Almost always one of two things: CRON_MIN is not set (it is disabled by default, so feeds only refresh when you press the refresh button), or the 20-minute per-feed floor is still counting down after the last fetch. Set CRON_MIN in your compose file, redeploy, and press the UI refresh button to catch up immediately. Verify the cron is alive with docker compose logs freshrss | grep -i cron.

Should I use SQLite or PostgreSQL for FreshRSS?

Use SQLite if the reader is just for you — the official prerequisites list it as supported, and it means no extra database container. Use PostgreSQL when multiple people share the instance, which is what the project's docs recommend (PostgreSQL 10+). MySQL and MariaDB 10.6+ also work.