FreshRSS: Your Own RSS Reader

RSS is the best news format most people have forgotten: you subscribe to sources directly, with no algorithm, no ads and no one watching what you read. FreshRSS gathers all your sources in one self-hosted place – and even syncs with the RSS apps on your phone.

What are we building?

Your own RSS reader with FreshRSS (v1.30.4) behind Traefik, collecting your news sources and keeping them fresh via cron in the background. By the end you read news sites, blogs and podcast feeds in one place, grouped into categories – and can connect mobile apps like Reeder or FeedMe via the built-in Google Reader API. FreshRSS is refreshingly lightweight: SQLite is enough, no separate database needed.

Prerequisites

• A server with Traefik running and Docker Compose
• A subdomain pointing at the server – YOUR_DOMAIN below (e.g. rss.YOUR_DOMAIN)

Step by step

Step 1: Create the Compose file

FreshRSS keeps everything in a data directory (SQLite database, config, cache). Create the project:

mkdir -p /opt/freshrss && cd /opt/freshrss

The compose.yaml – replace YOUR_DOMAIN:

services:
  freshrss:
    image: freshrss/freshrss:1.30.4
    restart: unless-stopped
    volumes:
      - ./data:/var/www/FreshRSS/data
      - ./extensions:/var/www/FreshRSS/extensions
    environment:
      TZ: Europe/Berlin
      CRON_MIN: '13,43'
    networks: [proxy]
    labels:
      - "traefik.enable=true"
      - "traefik.http.routers.freshrss.rule=Host(`YOUR_DOMAIN`)"
      - "traefik.http.routers.freshrss.entrypoints=websecure"
      - "traefik.http.routers.freshrss.tls.certresolver=le"
      - "traefik.http.routers.freshrss.middlewares=freshrss-only-me"
      - "traefik.http.middlewares.freshrss-only-me.ipallowlist.sourcerange=YOUR_IPV4/32,YOUR_IPV6_PREFIX::/64"
      - "traefik.http.services.freshrss.loadbalancer.server.port=80"

networks:
  proxy:
    external: true

CRON_MIN is a nice touch of the official image: the startup code turns it into a cron entry inside the container that refreshes the feeds at the given minutes (here 13 and 43 of every hour) – you need no external timer.

Do not create the data and extensions directories yourself: the container creates them on first start and sets the permissions itself (root:www-data, group writable – see Users & permissions for what that means). That holds on hardened servers with UMASK 027 as well.

freshrss-only-me lets only your own address through until the setup is finished; everyone else gets 403 Forbidden. As long as no admin account exists, the instance otherwise belongs to whoever opens the page first – and scanners sometimes find new hostnames via the public certificate logs within seconds of the start. Look up your addresses on your own computer, not on the server: curl -4 -s https://ifconfig.me for the IPv4, curl -6 -s https://ifconfig.me for the IPv6 (take the first four blocks). If you have no IPv6, drop the second entry including the comma – but only then: browsers prefer IPv6, and an IPv4-only list locks you out yourself. More on this in Hardening Traefik.

Step 2: Start

docker compose up -d

A quick look at the container status – Up, and port 80 stays inside the container because everything from outside goes through Traefik:

docker compose ps

NAME                  IMAGE                      COMMAND                  SERVICE    CREATED          STATUS          PORTS
freshrss-freshrss-1   freshrss/freshrss:1.30.4   "./Docker/entrypoint…"   freshrss   11 seconds ago   Up 10 seconds   80/tcp

From your own computer, check that FreshRSS responds with valid HTTPS (the 302 is the redirect to the install wizard; from the server, freshrss-only-me only returns 403):

curl -sI https://YOUR_DOMAIN/ | head -1

HTTP/2 302

If you get a certificate error instead of the 302, Traefik hasn’t issued the certificate yet – that takes a few seconds after the first start.

Step 3: The install wizard

Open https://YOUR_DOMAIN/ in the browser. The wizard walks you through setup in five steps – language, checks, database, general configuration, done:

Step 2 lists the PHP and file permission checks; with the official image you only get green “OK!” lines there, including the one for the data directory. Choose SQLite as the database type (no further details needed), Web form authentication and create your administrator account with a strong password. The last step confirms “Congratulations! The installation process was successful.” – only the click on Complete installation finishes setup and takes you to the login.

Once the installation is complete, remove the lock again: delete the two lines containing freshrss-only-me from the compose.yaml and apply the change:

docker compose up -d

Step 4: Subscribe to your first feeds

Click Subscription management → Add a feed or category at the top left. Enter a source’s feed URL (e.g. https://feeds.arstechnica.com/arstechnica/index) and assign it to a category. FreshRSS detects the feed format automatically. After adding several sources the management view looks like this:

Step 5: Reading

Back in the reading view, FreshRSS collects articles from all sources chronologically, grouped by category. Unread counters per feed, stars for favorites, full-text search – it’s all there:

Step 6: Connect mobile apps (optional)

FreshRSS speaks the Google Reader API, so many mobile apps can use it as a sync backend. That takes two switches, not one – and the first app login usually fails on exactly that.

First the server-wide switch: Settings → Administration → Authentication → Allow API access, then submit. FreshRSS asks for your password again before the administration pages; that reauthentication is then valid for 20 minutes.

Then the personal password: Settings → Profile → External access via API, where you set a separate API password – not your login password, because it travels in clear text and can show up in server logs. The same page links the status page https://YOUR_DOMAIN/api/, which tells you the correct API address and tests the configuration itself.

In the app (e.g. Reeder, FeedMe, NetNewsWire) choose “FreshRSS” or “Google Reader API”, enter https://YOUR_DOMAIN/api/greader.php, your username and the API password – and keep reading in sync on the go.

When things go wrong

Your problem is not listed? Search all error messages →

Maintenance & backups

• Updates. Set the image tag (freshrss/freshrss:1.30.4) to the new version, then docker compose pull && docker compose up -d; FreshRSS migrates its database automatically at start. The project announces larger jumps in the release notes – 1.30, for instance, was a security release with one deliberate tightening (see the box about local feeds). Your normal update process handles the rest.
• Backup. The entire state lives in the data folder (SQLite database + config). Add it to your Restic backup – then subscriptions, categories and read markers are safe. Copying a live SQLite file mid-write is a bad idea, though: docker compose exec -u www-data freshrss ./cli/db-backup.php writes a consistent copy to data/users/<user>/backup.sqlite first, which your backup then picks up. Additionally a regular OPML export of your feed list makes a human-readable, reader-independent backup.
• Low effort. FreshRSS is a “set it up once, then it just runs” service. The only recurring task is curating your feed list – under Statistics → Idle feeds you see at a glance which sources haven’t delivered anything for months, and can prune them.