selfoss: a PHP feed reader you host yourself

What selfoss does and who it is for

selfoss collects updates from web sites, social networks and other platforms into one place, according to the README. It is a web application, not a desktop client, so the reader is a browser pointed at your own URL. The target user is someone with a PHP server and a wish to keep their feed list under their own control rather than inside a hosted service.

The project describes itself as a multipurpose RSS reader and feed aggregation web application, and the repository topics include aggregator, mashup, news-feed, self-hosted and webbased. That combination matters: selfoss is not only a reader for feeds you subscribe to one by one. It is built to pull several kinds of source into a single stream.

It is written in PHP, which the README frames as a portability benefit: it can run basically anywhere. In practice that means the deployment unit is a directory of files plus a database, not a container image or a compiled binary. If your hosting already runs PHP, the distance between reading about selfoss and running it is short.

How selfoss moves a feed from a URL to your screen

The architecture visible in the repository is a PHP application with a separate client build. The server side lives in src/, the entry point is index.php, and the browser-facing assets are built from client/ into the public directory. Third-party PHP libraries arrive through composer, and the client-side dependencies through npm inside client/.

Feed updates are not driven by a request from your browser. The installation instructions say to create a cronjob or systemd timer that points at https://yourselfossurl.com/update using wget or curl, or to execute cliupdate.php from the command line. That is the data flow: a scheduled job fetches the feeds, the application stores the entries in the database, and the web interface reads from that store when you open it.

Storage is a database, and the schema is managed by the application rather than by you. The installation steps state that you do not need to create the database tables because they will be created automatically, with the caveat that your database user must be allowed to create triggers. The same caveat appears in the update instructions, which is a sign that triggers are part of how the schema works rather than an optional extra.

A separate detail worth noting: the README credits Graby and FullTextRSS filters among the libraries used. Those names point at full-text extraction, which is the mechanism behind turning a feed excerpt into a fuller article. The README does not document a per-feed configuration surface for that extraction, so treat it as built-in behaviour rather than something you tune from the interface.

Installing selfoss and running the first update

The README gives a five-step installation. You copy the files, including the invisible .htaccess files, into a PHP document root. You make five data directories writeable. You put database credentials in config.ini, though SQLite needs no changes. Tables are created for you. Then you schedule the update job.

The writeable directories are named explicitly, and getting this wrong is the most common way a first install fails silently. The README lists data/cache, data/favicons, data/logs, data/thumbnails and data/sqlite.

Configuration is optional at first. The README says no configuration is needed to use selfoss, and the configuration section describes renaming the example file and deleting lines you do not wish to override:

cp config-example.ini config.ini

If you want the update to run on a schedule rather than by hand, the README points at the /update URL and names wget or curl as the tools. This is that call, using the URL form the README gives:

curl https://yourselfossurl.com/update

You can also run the update from the command line instead of over HTTP, which avoids exposing the update endpoint to the network:

php cliupdate.php

If you are coming from another reader, the migration path is OPML. The README says to export OPML from the old application, usually somewhere in its settings, then visit https://yourselfossurl.com/opml and upload the file there. That is the first real use: import your existing subscriptions, run one update, and confirm entries appear.

If you obtained selfoss from Git rather than a release archive, there is an extra step. The development section says to run composer install to retrieve external sources, and npm install inside client/ for the JavaScript dependencies. There is a shortcut for both:

npm run install-dependencies

The client itself is built with Parcel. The README states that every time anything in client/ changes you need npm run build to compile it into public/, and that npm run dev watches for changes and reloads automatically.

Updating selfoss is a manual, file-level operation

There is no package manager step for the application itself. The update procedure is a sequence of file operations: back up the database and the data/ directory, delete all old files and directories except data/ and config.ini, then copy the new files in, including the .htaccess files again.

Two warnings in that list are easy to skim past. The first is that you must not delete the data/ directory. The second is that config.ini itself changes between versions: the README says new options are added and you have to update the file too, not just carry your old one forward. So an upgrade is not a drop-in replacement of code. It is code replacement plus a config merge, and the README tells you to consult NEWS.md for backwards incompatible changes.

The database migrates itself, again subject to the trigger permission. The README also says to clean your browser cache after updating, which suggests the client-side bundle can be cached in ways that make a new version look broken.

For anyone running this on a schedule, the practical consequence is that selfoss upgrades are a maintenance task with a checklist, not an unattended background process. If you want automatic upgrades, selfoss does not offer one in the documentation.

Where selfoss is the wrong choice

The clearest limitation is stated by the project itself. selfoss is currently maintained by Jan Tojnar in his free time, and the README says maintenance is prioritized over new features. That is a deliberate statement about capacity, and it should shape your expectations about response times and about how quickly a desired feature will arrive.

The release history supports a slow cadence. The most recent release listed is 2.19 from 2022-10-12, preceded by 2.18 in 2018 and 2.17 in 2017. The README header shows 2.20-SNAPSHOT, so development continues, but the gap between tagged releases is measured in years, not months. If your evaluation depends on frequent releases, selfoss is not that project.

There is also a licensing wrinkle the README does not hide. The source is GPL-3.0 or later, but the README says some parts of the source code can be licensed under version 3 only and that this is currently being resolved, linking to an issue. It also notes that the package with bundled dependencies might be distributed under version 3 only. If your organisation has rules about which licence variants are acceptable, that distinction is worth reading before you pick a download.

Finally, selfoss assumes you have a server. If you do not want to run PHP, a database and a scheduled job, the whole design is against you. There is no hosted option described in the README.

Alternatives and the actual difference in approach

The README recommends Reader For Selfoss for Android devices, which is a client rather than an alternative server: it talks to your selfoss instance. That is the intended mobile story, and it means the server remains the thing you operate.

For a different server-side approach, the honest comparison is with feed readers that ship as a single binary or a container image. selfoss is a PHP application you copy into a document root and pair with a database, with a cron job or systemd timer driving updates through /update or cliupdate.php. A compiled, container-first reader collapses those steps into an image and a volume, at the cost of running something other than PHP on the host. If your infrastructure is already PHP and Apache or nginx, selfoss fits without adding a runtime. If it is not, you are adding one.

The second axis is the client build. selfoss has a JavaScript client built with Parcel and installed into public/. Projects that serve a plain server-rendered interface avoid that build step entirely, which removes the npm run build requirement and the browser-cache note from the update procedure. selfoss accepts that complexity in exchange for a richer browser interface.

Licence and what a fork or redistribution implies

selfoss is licensed under GPL-3.0 or later, and the README states that some parts of the source can be licensed under version 3 only, with an open issue tracking the resolution. The bundled-dependency package might be version 3 only as well.

For a self-hoster running selfoss privately, this is background reading. For anyone redistributing selfoss, shipping a modified version, or bundling it into a product, the version-3-only parts are the detail to check, because GPL-3.0-or-later and GPL-3.0-only are not the same grant. The README points at the issue rather than resolving it, so the repository is the place to look for the current state. This is a description of what the project says about its own licensing, not legal advice.

Editorial conclusion

Adopt selfoss if you want a PHP feed reader on your own server, you are comfortable editing config.ini, and you accept that maintenance is described as prioritised over new features. Do not adopt it if you need a hosted service or a client that syncs across devices without a server of your own. Before installing, check that your PHP user can create triggers, that data/cache, data/favicons, data/logs, data/thumbnails and data/sqlite are writeable, and read NEWS.md for backwards incompatible changes.

Frequently asked questions

Official sources

1. fossar/selfoss on GitHub
2. License: GPL-3.0
3. Project website
4. README
5. Releases