FreshRSS self-hosted RSS reader running with Docker on a VPS
Self-hosting

FreshRSS Docker: Self-Host Your Own RSS Reader on a VPS

You probably follow more websites than you realize: a few tech blogs, a local news site, the changelog of a tool you depend on, a friend who writes once a month. Today most of that reaches you through social feeds that decide what you see, in what order, with ads squeezed in between. RSS is the old, boring, wonderful alternative: every site publishes a machine-readable list of its new articles, and a reader collects them for you in plain chronological order. In this tutorial we put that reader on your own server, with FreshRSS and Docker, so your feeds, your read history and your phone all stay in sync without anyone else in the middle.

FreshRSS is a free, open source feed aggregator, licensed AGPL-3.0 and developed by a community of volunteers. The project lives at freshrss.org , with code on github.com/FreshRSS/FreshRSS . It is light enough for the smallest VPS, handles hundreds of feeds without breaking a sweat, and speaks the same sync protocols as the big commercial readers, so you can keep using a polished mobile app.

By the end you will have FreshRSS running behind HTTPS, your existing subscriptions imported from an OPML file, a mobile app syncing read and starred status through the API, and automatic feed refreshes on a schedule you choose.

What RSS and FreshRSS actually are

An RSS feed (or its cousin, the Atom feed) is a small XML file that a website updates every time it publishes something. It contains titles, links, dates and often the full article text. Most blogs, news sites, podcasts, YouTube channels, GitHub release pages and many forums publish one, often without advertising it.

A feed reader is the program that subscribes to those files, checks them periodically and shows you what is new. You can run one on your laptop, but then your phone has no idea what you already read. A server-side reader solves that: the server does the fetching around the clock, stores everything in one place, and every device you own simply asks it “what is unread?”.

FreshRSS is that server-side reader. It is a PHP web application that stores data in SQLite by default (PostgreSQL and MySQL/MariaDB are also supported), and it comes with:

  • a fast web interface with keyboard shortcuts, several themes and reading views;
  • multi-user support, so a family or a small team can share one instance with separate subscriptions;
  • Google Reader compatible and Fever APIs, which mobile and desktop apps use to sync;
  • WebSub support, so feeds that offer it are pushed to you almost instantly;
  • web scraping with XPath, for sites that have no feed at all;
  • filters, labels, favourites, full-text search and an extensions system.

Why host it yourself instead of using a cloud reader

Commercial readers are fine, but they come with limits on the free tier, tracking, and the occasional shutdown (many of us still remember Google Reader). With your own instance there is no feed limit, no ads, no engagement algorithm and no one profiling what you read. Because everything imports and exports as OPML (a standard file listing all your subscriptions), you are never locked in, not even to FreshRSS.

What you need

  • A DreamServer VPS with Debian 13 or Ubuntu 24.04. 1 vCPU, 1 GB of RAM and 10 GB of disk are more than enough for a few users and hundreds of feeds.
  • A sudo user you can log in with over SSH, ideally using an SSH key.
  • A domain or subdomain you control, for example rss.example.com, so we can get a free TLS certificate.
  • Optionally, an OPML export from your current reader (Feedly, Inoreader, NetNewsWire and almost every other reader can produce one).
  • About 30 minutes.

A note on container types: on a KVM VPS everything below works as written. In an unprivileged LXC container, Docker only runs if nesting (and usually keyctl) is enabled for that container, and ufw may fail to load its firewall rules. If you are on LXC, ask our support team to enable nesting, or choose a KVM plan for Docker workloads.

How the pieces fit together

Before typing commands, let’s agree on a few terms.

A container is an isolated process that ships with everything it needs (here: Apache, PHP and FreshRSS), so it runs the same on any server. It is started from an image, a read-only template downloaded from Docker Hub. Containers are disposable, so anything we want to keep lives in a volume, a storage area managed by Docker that survives container upgrades. Docker Compose lets us describe several containers in one YAML file and start them with a single command.

A port is a numbered door on the server: 22 for SSH, 80 for HTTP, 443 for HTTPS. A reverse proxy is a web server that sits on ports 80 and 443, handles TLS certificates and forwards each request to the right application behind it. We use Caddy, because it obtains and renews Let’s Encrypt certificates automatically with a configuration of a few lines.

FreshRSS on a VPS: how a request travelsMobile appWeb browserDesktop appInternetufw22, 80, 443allowedDocker on your VPSCaddyTLS on 443FreshRSSApache + PHPcron: refresh feedsFeed websitesRSS / Atomfetch feedsread / writeDocker volumesdata + extensionsOnly Caddy publishes ports. FreshRSS stays on the private Docker network.
Figure 1: the FreshRSS Docker architecture we build. Traffic passes the firewall, Caddy handles HTTPS, and FreshRSS keeps its data in Docker volumes.

The important design choice: FreshRSS itself does not publish any port. Only Caddy is reachable from outside, and it talks to FreshRSS over a private Docker network. This matters because Docker writes its own firewall (iptables) rules, and a published port can bypass ufw entirely.

Here is the whole procedure at a glance. The numbered sections below follow exactly the same eight steps, in the same order.

Installing FreshRSS with Docker: 8 steps1Prepare VPSupdates + Docker2DNS + firewallA record, ufw3Compose fileFreshRSS + Caddy4Start + installweb wizard5Import OPMLyour feeds6API + appssync read status7Schedule refreshCRON_MIN, interval8Backup + updatevolumes, pull
Figure 2: steps 1 to 4 get FreshRSS online, steps 5 to 8 make it useful every day. Each number matches a "Step" heading below.

Step 1: Prepare the VPS and install Docker

Log in over SSH and bring the system up to date:

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

This refreshes the package lists and installs all pending updates. If a new kernel was installed, reboot before continuing. On Ubuntu, a flag file tells you when that is needed:

[ -f /var/run/reboot-required ] && echo "Reboot needed" || echo "No reboot flag"

On Debian, /var/run/reboot-required is not created by default, so this check always prints “No reboot flag”. On Debian, simply reboot if you saw a linux-image package in the upgrade output:

sudo reboot

Now install Docker Engine and the Compose v2 plugin from Docker’s official repository. The distribution packages also exist, but they lag behind and have different names on Debian and Ubuntu. The block below reads /etc/os-release, so the same commands select the right repository on both systems: $ID becomes debian or ubuntu, and $VERSION_CODENAME becomes trixie or noble.

sudo apt install -y ca-certificates curl
sudo install -m 0755 -d /etc/apt/keyrings
. /etc/os-release
sudo curl -fsSL "https://download.docker.com/linux/${ID}/gpg" -o /etc/apt/keyrings/docker.asc
sudo chmod a+r /etc/apt/keyrings/docker.asc
echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/${ID} ${VERSION_CODENAME} stable" | sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
sudo apt update
sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin

The first lines download Docker’s signing key, so apt can verify the packages, then we add the repository and install the engine plus the compose plugin. Check that both pieces answer:

docker --version
docker compose version

You should see something like Docker version 28.x.x and Docker Compose version v2.x.x. The exact numbers will differ; what matters is that docker compose, with a space, works. The old docker-compose with a hyphen is not needed.

To run Docker without typing sudo every time, add your user to the docker group, then log out and back in:

sudo usermod -aG docker $USER
exit

After reconnecting, docker run --rm hello-world should print “Hello from Docker!”. Keep in mind that membership in the docker group is effectively root access, so only add users you trust.

Step 2: Point your domain and open the firewall

At your DNS provider, create an A record for rss.example.com pointing to your VPS’s public IPv4 address, plus an AAAA record if you use IPv6. Then check from the VPS that the name resolves:

getent hosts rss.example.com

The output should show your server’s IP address. If it is empty or shows another address, wait a few minutes for DNS to propagate. Caddy cannot obtain a certificate until this is correct.

Next comes the firewall, the gatekeeper that decides which ports accept connections. Ubuntu ships ufw installed but inactive; Debian 13 does not install it at all, so we install it first (the command is harmless on Ubuntu):

sudo apt install -y ufw
sudo ufw allow OpenSSH
sudo ufw allow 80/tcp
sudo ufw allow 443/tcp
sudo ufw allow 443/udp
sudo ufw enable
sudo ufw status verbose

We allow SSH first, so enabling the firewall does not lock us out. If your SSH server listens on a custom port, use sudo ufw allow 2222/tcp with your port instead. Port 80 is needed for the certificate challenge and the HTTP to HTTPS redirect, 443/tcp for HTTPS and 443/udp for HTTP/3. The status output should list these rules with ALLOW IN and show Status: active.

Step 3: Write the FreshRSS Docker Compose file

Create a project directory. Its name becomes the Compose project name, which will prefix our volume names later:

mkdir -p ~/freshrss && cd ~/freshrss
nano compose.yaml

Paste the following:

services:
  freshrss:
    image: freshrss/freshrss:1
    container_name: freshrss
    restart: unless-stopped
    logging:
      options:
        max-size: "10m"
    volumes:
      - freshrss_data:/var/www/FreshRSS/data
      - freshrss_extensions:/var/www/FreshRSS/extensions
    environment:
      TZ: "Europe/Bucharest"
      CRON_MIN: "3,23,43"
      TRUSTED_PROXY: "172.16.0.0/12 192.168.0.0/16"
    networks:
      - web

  caddy:
    image: caddy:2
    container_name: caddy
    restart: unless-stopped
    ports:
      - "80:80"
      - "443:443"
      - "443:443/udp"
    volumes:
      - ./Caddyfile:/etc/caddy/Caddyfile:ro
      - caddy_data:/data
      - caddy_config:/config
    networks:
      - web
    depends_on:
      - freshrss

volumes:
  freshrss_data:
  freshrss_extensions:
  caddy_data:
  caddy_config:

networks:
  web:

What each part does:

  • image: freshrss/freshrss:1 uses the official image and follows the newest 1.x release, so you get fixes and features but never a surprise major version. :latest also works, but pinning the major version is safer. For full control, pin an exact release such as freshrss/freshrss:1.27.1 (check the tag list on Docker Hub for the current one) and bump it by hand after reading the release notes.
  • The two volumes hold everything that matters: data contains the configuration, users and SQLite databases, extensions holds optional add-ons.
  • TZ sets the timezone for timestamps and the internal scheduler.
  • CRON_MIN turns on the scheduler inside the container and refreshes feeds at those minutes of every hour: :03, :23 and :43, which is every 20 minutes while avoiding the busy top of the hour. Step 7 covers this in depth.
  • TRUSTED_PROXY tells FreshRSS to trust the forwarded headers coming from Docker’s private address ranges, so it knows visitors arrived over HTTPS and logs their real IP addresses.
  • There is deliberately no ports: section under freshrss. Only Caddy publishes ports.
  • logging caps the log file size, so a chatty container cannot fill your disk.

Save with Ctrl+O, Enter, and exit with Ctrl+X. Now create the Caddy configuration:

nano Caddyfile
{
    email you@example.com
}

rss.example.com {
    encode zstd gzip
    reverse_proxy freshrss:80
}

Replace rss.example.com with your hostname and the email with yours; Let’s Encrypt uses it for expiry warnings. reverse_proxy freshrss:80 works because containers on the same Compose network reach each other by service name, and encode compresses responses so pages load faster on mobile data.

Step 4: Start the stack and finish the web installer

From the ~/freshrss directory, start everything:

docker compose up -d

Docker pulls both images and starts the containers in the background (-d means detached). The last lines should read Container freshrss Started and Container caddy Started. Confirm both are running:

docker compose ps

Both services should show a status of Up. Then watch Caddy obtain its certificate:

docker compose logs -f caddy

Look for a line containing certificate obtained successfully for your domain, then press Ctrl+C to stop following the log; the container keeps running.

Now open https://rss.example.com in your browser. Do this right away: until the installer is completed, anyone who finds the address could run it and create the admin account. The wizard has a few short screens:

  1. Language: pick the interface language.
  2. Checks: every line should be green, because the official image ships all required PHP extensions.
  3. General configuration: the base URL should already read https://rss.example.com. If it shows http:// or an internal address, see the troubleshooting section.
  4. Database: choose SQLite. No extra container and no database password to manage, perfectly fine for a personal or family instance.
  5. User: choose a username (we use alice in the examples), a strong password, and keep the “Web form” authentication method.

Click Complete installation and log in. You now have an empty, working reader.

Step 5: Import your feeds via OPML

OPML (Outline Processor Markup Language) is a small XML format that lists feeds and their categories. Export it from your old reader; in most apps it lives under settings, “Import/Export” or “Backup”.

In FreshRSS, open Subscription management (the gear icon next to the feed list), go to Import / export, choose your .opml file in the import section and press Import. Categories are preserved and the feeds appear in the sidebar. Press the refresh button at the top to fetch articles immediately instead of waiting for the scheduler.

For very large files, or if you prefer the terminal, FreshRSS has a command line importer. Copy the file into the container, then run the importer as www-data, the user that owns FreshRSS’s files:

docker compose cp feeds.opml freshrss:/tmp/feeds.opml
docker compose exec --user www-data freshrss \
  php /var/www/FreshRSS/cli/import-for-user.php --user alice --filename /tmp/feeds.opml

Replace alice with your username. Running as www-data matters: CLI tools started as root can leave root-owned files in the data volume that the web server can no longer write.

No OPML file? Paste a site’s address into Subscription management > Add a feed. For most sites FreshRSS discovers the feed link automatically, so you do not need to hunt for the exact /feed URL.

Step 6: Enable the API and connect mobile apps

The web interface works well on phones, but a native app gives you offline reading, swipe gestures and notifications. Apps talk to FreshRSS through an API (Application Programming Interface), a set of URLs designed for programs rather than people. Two switches must be turned on.

First, allow API access for the instance. As the admin, go to Administration > Authentication, tick Allow API access (required for mobile apps) and save.

Second, set an API password for your user. Open Settings > Profile, find the API management section, enter an API password and save. It is separate from your login password: apps store it, so if a phone is lost you change only the API password and your web login stays safe.

Check the setup by opening https://rss.example.com/api/ in a browser. FreshRSS shows a small test page with the endpoint addresses, and the Google Reader and Fever checks should report PASS.

In your app, choose “FreshRSS” or “Google Reader API” as the account type and enter:

SettingValue
Server URL (Google Reader API)https://rss.example.com/api/greader.php
Server URL (Fever API)https://rss.example.com/api/fever.php
Usernameyour FreshRSS username
Passwordthe API password, not the login password

Prefer the Google Reader API when an app supports both: it syncs categories, read and starred status in both directions. Some apps only ask for https://rss.example.com and add the path themselves. Apps known to work with FreshRSS include Readrops, Read You and FeedMe on Android, NetNewsWire and Reeder on iPhone and Mac, and Fluent Reader on the desktop. Mark an article as read on your phone, reload the browser, and it disappears from the unread list: that is the sync working.

Step 7: Schedule feed refreshes

A reader is only useful if it checks feeds without you clicking anything. Cron is the classic Unix scheduler that runs commands at fixed times, and the official image includes it: when CRON_MIN is set, the container runs cron and calls FreshRSS’s actualize_script.php at those minutes.

Our value "3,23,43" means three times per hour. Any valid cron minute expression works, for example "*/15" for every 15 minutes or "7" for once an hour. After editing compose.yaml, apply the change:

docker compose up -d

Compose notices the changed environment and recreates only the FreshRSS container; the data in the volume is untouched.

There is a second setting that people often miss: FreshRSS never refreshes a feed more often than its minimum interval, which defaults to one hour. Even with cron every 15 minutes, each feed is fetched at most hourly until you change it. Adjust the global default under Settings > Archiving (“Do not automatically refresh more often than”), or per feed in that feed’s settings, in the advanced section. Use short intervals for fast news sites and long ones, such as a day, for blogs that post monthly: you save bandwidth and you are kinder to small websites.

To trigger a refresh manually, for example while testing:

docker compose exec --user www-data freshrss php /var/www/FreshRSS/app/actualize_script.php

It prints information about the feeds it processed. Feeds that support WebSub can also push new articles to FreshRSS the moment they publish, which works because your instance has a public HTTPS address.

Prefer the host’s cron? Remove CRON_MIN, run docker compose up -d again, and add this line with crontab -e on the VPS (replace youruser):

*/20 * * * * cd /home/youruser/freshrss && docker compose exec -T --user www-data freshrss php /var/www/FreshRSS/app/actualize_script.php > /dev/null 2>&1

The -T flag disables the pseudo-terminal, which cron does not provide.

Step 8: Back up and update FreshRSS

Everything important lives in the freshrss_data volume. Docker prefixes volume names with the project name, so list them first:

docker volume ls

You should see freshrss_freshrss_data, freshrss_freshrss_extensions, freshrss_caddy_data and freshrss_caddy_config. For a consistent backup, stop FreshRSS for a few seconds, archive the volume with a throwaway Alpine container, then start it again:

docker compose stop freshrss
docker run --rm -v freshrss_freshrss_data:/data:ro -v "$PWD":/backup alpine:3 \
  tar czf /backup/freshrss-data-$(date +%F).tar.gz -C /data .
docker compose start freshrss

This creates freshrss-data-YYYY-MM-DD.tar.gz in the current directory. Copy it off the server with scp or your backup tool: a backup on the same disk does not protect you from losing that disk. For a lightweight extra copy, export your subscriptions as OPML:

docker compose exec -T --user www-data freshrss \
  php /var/www/FreshRSS/cli/export-opml-for-user.php --user alice > feeds-backup.opml

Updating takes three commands. Because we pinned :1, this moves you to the newest 1.x release:

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

pull downloads newer images, up -d recreates only the containers whose image changed, and prune deletes the old, unused layers. FreshRSS migrates its database automatically on start. Take a backup and glance at the release notes on GitHub before bigger jumps.

How light is FreshRSS compared to other readers?

FreshRSS earns its place on small servers. In our experience, a single-user instance with around 100 feeds idles at roughly 50 to 70 MB of RAM, and Caddy adds about 20 MB. The chart compares typical idle memory of popular self-hosted reader stacks. The numbers are approximate and depend on settings, feed count and PHP worker configuration.

Approximate idle RAM of self-hosted RSS reader stacksFreshRSS + SQLite~60 MBMiniflux + PostgreSQL~110 MBTiny Tiny RSS + PostgreSQL~180 MBNextcloud + News~450 MB0100200300400500Idle RAM in MB (approximate)Reader stack
Figure 3: approximate idle memory for a single user with about 100 feeds, reverse proxy not included. Real values vary with configuration.

Miniflux is the other excellent lightweight option, but it requires PostgreSQL. Tiny Tiny RSS is powerful but heavier, usually deployed with PostgreSQL and separate updater processes. Nextcloud News makes sense mainly if you already run Nextcloud. For “one container, one SQLite file”, FreshRSS is hard to beat.

Troubleshooting and common mistakes

Caddy does not get a certificate. Run docker compose logs caddy. The usual causes are DNS not pointing to the VPS yet, port 80 blocked, or a typo in the hostname inside the Caddyfile. After many failed attempts Let’s Encrypt applies rate limits, so fix the cause and wait a while instead of restarting in a loop.

502 Bad Gateway. Caddy runs, but cannot reach FreshRSS. Check docker compose ps and docker compose logs freshrss, and make sure the name in reverse_proxy freshrss:80 matches the service name in compose.yaml.

Links, redirects or the login page use http:// or a strange address. Either TRUSTED_PROXY is missing, or the base URL saved during installation is wrong. Check it, and fix it if needed:

docker compose exec freshrss grep base_url /var/www/FreshRSS/data/config.php
docker compose exec --user www-data freshrss sed -i "s#'base_url' => '.*'#'base_url' => 'https://rss.example.com'#" /var/www/FreshRSS/data/config.php

The mobile app says the login failed. Confirm that API access is enabled in Administration, that you used the API password and not the login password, and that the URL ends in /api/greader.php (or /api/fever.php). The test page at /api/ tells you quickly which part is wrong.

Feeds do not update. Check that CRON_MIN is set and the container was recreated afterwards, then run the manual refresh command from step 7 and read its output. Remember the minimum refresh interval (one hour by default) before concluding that the scheduler is broken.

Some feeds show errors such as 403 or timeouts. Some sites block requests coming from data centers or behave badly with bots. Your setup is fine; try the site’s alternative feed URL or a lower refresh frequency.

permission denied when talking to the Docker socket. You added yourself to the docker group but did not log out and back in. Reconnect over SSH.

Files owned by root in the data volume, usually after running a CLI tool without --user www-data. Fix the ownership:

docker compose exec freshrss chown -R www-data:www-data /var/www/FreshRSS/data

Docker will not start inside an unprivileged LXC container. Nesting must be enabled for the container. A KVM VPS avoids the issue entirely.

Security notes

  • Do not publish the FreshRSS port. Docker inserts its own iptables rules, so a line like "8080:80" makes the app reachable from the whole internet even if ufw says otherwise. If you need direct access for debugging, bind it to localhost ("127.0.0.1:8080:80") and use an SSH tunnel.
  • Finish the installer immediately after the first start, before someone else does.
  • Keep registrations closed. In Administration > System configuration, the maximum number of accounts controls whether strangers can sign up; leave it at a value that does not allow new public accounts, and create users yourself.
  • Use strong, unique passwords, keep the API password separate, and switch API access off if you never use apps. Anonymous reading should stay disabled unless you deliberately want a public reader.
  • Keep everything updated: apt updates for the OS (consider unattended-upgrades) and docker compose pull for the images.
  • Harden SSH with key-based login and password authentication disabled.
  • Store backups off the server and test a restore once, so you know it works before you need it.

So, is a self-hosted RSS reader worth it?

If you read the web every day, yes. For the cost of the smallest VPS you get a calm, chronological stream of the sites you actually chose, no ads, no algorithm, read status synced across every device, and your whole subscription list portable as a single OPML file. FreshRSS with Docker makes the setup a half-hour job, and updates are a two-command routine.

You can launch this stack on a DreamServer VPS in a few minutes, from our own data center in Romania. If you prefer to skip the terminal entirely, our server administration team can install, secure, back up and maintain FreshRSS (or any other self-hosted app) for you.

FAQ

Can several people share one FreshRSS instance?

Yes. FreshRSS is multi-user: each account has its own subscriptions, categories, read status and API password. Create users from Administration > Users instead of opening public registration.

Should I use SQLite or PostgreSQL?

SQLite is the right default for one person or a family, even with several hundred feeds. Consider PostgreSQL or MariaDB when you host many users or tens of thousands of articles and want a separate, tunable database server.

Can I follow websites that have no RSS feed?

Often, yes. When adding a feed, FreshRSS lets you choose the “HTML + XPath” type, which scrapes a web page with XPath rules to build a feed. It takes a little tinkering, but it works well on simple listing pages.

Does FreshRSS work in an unprivileged LXC container?

FreshRSS itself does, but Docker inside an unprivileged LXC container needs nesting enabled, and ufw may not work there. On a KVM VPS there are no such limitations.

How many feeds can a small VPS handle?

Plenty. A 1 vCPU, 1 GB RAM VPS comfortably handles several hundred feeds refreshed every 20 minutes. Disk use grows with stored articles, so set sensible retention limits under Settings > Archiving.

Trusted By & Member Of

We are proud members of leading internet infrastructure organizations.

RIPE NCC MANRS PeeringDB RoTLD DSIX SBIX 4IXP LOCIX Euro-IX RIPE NCC MANRS PeeringDB RoTLD DSIX SBIX 4IXP LOCIX Euro-IX