Many news sites, blogs and periodicals provide notifications of new publications in the RSS format. Miniflux is a simple, open-source RSS reader. In this article I document how I have set up the Miniflux RSS reader to run locally on my computer. The official Miniflux documentation is targeted at server administrators and therefore assumes some additional knowledge that I did not have. Miniflux also offers paid hosting if you prefer not to set it up yourself.
Contents
Miniflux stores RSS entries in a PostgreSQL database. This is essentially a collection of binary files which contain both the entries themselves and some metadata that makes search and retrieval faster. PostgreSQL in particular uses a type of format called an object-relational database. I was disappointed to find that there are not many references that explain what this means both clearly and concisely, however a few paragraphs (76K PDF) written by Naman Sogani in 2015 give me some idea. The “relational” qualifier means that the database is organised into tables which are manipulated using composable operations. In this case the operations are drawn from a subset of the SQL language. The “object” qualifier means that in addition to tables, custom types of containers can also be used, which however disallows arbitrary composability of operations.
The postgresql software should be available in any Linux package repository, and is a requirement for using miniflux. Note that upgrading PostgreSQL may involve manually migrating all databases to the new format. The release notes should indicate if this is required. For example, this notice is included in the release notes for version 15, the latest at the time of writing:
A dump/restore using
pg_dumpallor use ofpg_upgradeor logical replication is required for those wishing to migrate data from any previous release.
The pg_upgrade tool is usually included with postgresql installations. It also requires the previous version of PostgreSQL to be available on the system, which on Arch Linux is provided by the package postgresql-old-upgrade. The required steps are outlined on the Arch Linux wiki article.
Because postgresql requires these manual steps during the upgrade, and I currently don't have it installed as a dependency for anything else, I have excluded this package as well as miniflux itself from Arch Linux system upgrades by adding
IgnorePkg = postgresql minifluxto my pacman configuration file. This way, if there is an update to the package, pacman will first ask if I want to apply the update or exclude it from the upgrade.
Other articles about Miniflux talk about spinning up a Docker container for the database. This may be a reasonable idea if your Miniflux service is meant to stay running on a home server, alongside a bunch of other services. In this case, I will be the only user of the service and I think a container is overkill. Also, I'm installing Miniflux on my own computer which will not be running all the time.
Manipulating PostgreSQL databases on Linux requires a custom system user called postgres. This user is created automatically when installing the Arch Linux package. Switch to the postgres user with
sudo -iu postgresInitialise a database cluster as the new user, for example in /var/lib/postgres/data, with
initdb -D /var/lib/postgres/dataReturn to your regular user account using exit. Enable and start the postgresql service, which on Arch Linux is achieved with
systemctl enable --now postgresql.serviceAs the postgres user, also create a new database user for Miniflux. While system users provide a way to manage Linux filesystem permissions, database users are registered with the PostgreSQL service itself. They allow you to manage access permissions to your PostgreSQL databases. Using the -P flag tells PostgreSQL to prompt for a password for the user:
sudo -iu postgres
createuser -P minifluxAfter setting up the password, the database can be created:
createdb -O miniflux minifluxThe -O flag assigns ownership of the database. Miniflux also requires the hstore extension for PostgreSQL, which is enabled with
psql miniflux -c 'create extension hstore'Finally, exit to the regular user again.
The Miniflux service that is installed with the miniflux package on Arch Linux reads its configuration from /etc/miniflux.conf. Editing this file requires root privileges. If you are using a different configuration file, change the path in the following commands accordingly.
To use the Miniflux reader, create (at least) an admin user for the Miniflux app. Note that this is different to both the system postgres user and the PostgreSQL miniflux user created in "Setting up the database". This will be the user that can log in to the web interface, add RSS feeds and change interface settings. In my case, it will be the only web app user. I am using sudo to allow Miniflux to read from /etc/miniflux.conf, which is owned by root.
sudo miniflux -c /etc/miniflux.conf -create-adminThe command prompts for a new username and password. Before starting the miniflux service, review the configuration and make changes if necessary. The Arch Linux package has RUN_MIGRATIONS set to 1 by default, although this is only required when upgrading to a new Miniflux version. Because I will already be performing manual maintenance when upgrading, I have removed this setting. Instead, I recommend following the official guidelines for upgrading Miniflux. I replaced it with a line to change DATABASE_URL to the appropriate value, which looks like this
DATABASE_URL=user=miniflux password="<POSTGRES_PASSWORD>" dbname=miniflux sslmode=disablewhere <POSTGRES_PASSWORD> should be replaced by the password created for the PostgreSQL miniflux user. Note that I have omitted quotes around the value (user=miniflux ...) because they resulted in errors from the library used by Miniflux to communicate with PostgreSQL. Although storing passwords in plain text files is usually not good practice, in this case the file is only readable by root and only authorises access to the RSS feed database, which I will mainly use to collect notifications of new scientific papers and blog articles. However, if you plan to run Miniflux on a server, it may be worth looking into better options for PostgreSQL authorisation.
By default, Miniflux listens on port 8080 on localhost. Because this is often used in other programming tutorials and the like, I have also added a line to change the address:
LISTEN_ADDR=127.0.0.1:8090To test the configuration, run
sudo miniflux -c /etc/miniflux.conf -debugand navigate to http://localhost:8090 in a web browser. Log in using the Miniflux administrator account. If it works, press Ctrl-C to stop running in debugging mode, and enable and start the Miniflux service with
systemctl enable --now miniflux.serviceThe news feed will now be available at that address whenever the computer is running. It may take some time after the computer is started to fetch feed updates, but if you are impatient there are “refresh” buttons in the web interface. The web interface also offers several keyboard shortcuts, which can be listed by pressing the ? key.