Miniflux v2: a Go RSS reader that runs on PostgreSQL and very little else

The problem Miniflux v2 solves, and who it is for

Most feed readers accumulate features until they become small web applications: theme marketplaces, plugin APIs, sync protocols, mobile apps. Miniflux v2 goes the other way. The README calls it "minimalist and opinionated," and the repository layout backs that up. There is a main.go, an internal/ directory, a client/ directory with Go and Python client libraries, and a contrib/ folder for deployment recipes. No plugin directory, no extension registry.

The target user is someone who already operates a server and wants a reader that behaves like a Unix daemon. The README lists the constraints plainly: it works only with PostgreSQL, it does not use an ORM or complicated frameworks, and it compiles to a single static binary with all static files embedded via the Go embed package. If you are comfortable running Postgres and a reverse proxy, the operational surface is small. If you are not, the PostgreSQL requirement is the first wall you hit.

The second audience is privacy-focused. Miniflux strips tracking parameters such as utm_source, utm_medium, utm_campaign and fbclid from URLs, removes pixel trackers, and sanitizes external content before rendering. Those are defaults, not opt-ins. A reader who wants the original, unsanitized article body will find this reader working against them.

How Miniflux v2 actually works: Postgres, a scheduler, and a sanitizing pipeline

The architecture is deliberately flat. A single Go binary serves the web UI, the REST API, and the background feed poller. There is no separate worker process and no message queue. The README states that feeds update either through an internal scheduler or a traditional cron job, so you can choose which side owns the polling loop.

Persistence is entirely PostgreSQL. Full-text search is described as powered by Postgres, which means search quality is bounded by Postgres text search configuration rather than a separate index like Elasticsearch. That is a trade-off: fewer moving parts, but no fuzzy matching beyond what Postgres offers.

Content handling is where the opinion shows. When a feed's HTML is thin, Miniflux can fetch the original article and extract the relevant content using a local Readability parser. It also supports custom scraper rules based on CSS selectors and custom rewriting rules, plus a regex filter to include or exclude articles by pattern. The pipeline is: fetch, sanitize, optionally rewrite, store, render. The README notes that external JavaScript is blocked, that a Content Security Policy and Trusted Types Policy restrict scripts to application JavaScript, and that inline scripts and styles are blocked. Custom JavaScript is still permitted according to the UI section, so the CSP is not absolute.

On the network side, Miniflux respects Last-Modified, If-Modified-Since, If-None-Match, Cache-Control, Expires and ETags headers, with a default polling interval of 1h. For feeds behind bot protection, it can optionally disable HTTP/2 to mitigate fingerprinting, set a custom user agent, add custom cookies, and route through proxies. Those are the escape hatches for feeds that reject ordinary clients.

Installing Miniflux v2 with Docker and adding your first feed

The project publishes a Docker image to Docker Hub, GitHub Registry, and Quay.io, with ARM and RISC-V support. The image name in the Makefile is miniflux/miniflux. The README does not reproduce a full compose file, so the deployment shape is: a Postgres service plus the Miniflux service pointed at it. The database URL uses the postgres:// scheme, matching the DB_URL format in the Makefile.

If you build from source, the Makefile's default target produces a PIE binary:

make miniflux

That runs go build with -buildmode=pie and embeds the version from git describe. The go.mod file pins go 1.26.0, so a toolchain at least that new is required. The repository also ships a miniflux.1 man page and a packaging/ directory with Debian and RPM build targets, so if you prefer native packages, the Makefile defines debian and rpm targets rather than asking you to build by hand.

Once the service is running, the first real use is subscribing to a feed: log in, add a category, and paste a feed URL. Miniflux accepts Atom 0.3/1.0, RSS 1.0/2.0, and JSON Feed 1.0/1.1. You can also import an OPML file, which is the practical path if you are migrating from another reader. Articles land in the category you chose, and the poller picks up new items on the configured interval.

Where Miniflux v2 is the wrong tool

The PostgreSQL-only requirement is the sharpest limitation. There is no SQLite mode and no MySQL support. On a small VPS where you wanted one process and one file, Miniflux asks for a second service that needs its own backups, its own upgrade path, and its own tuning. The README's claim of a single binary is true for the application, not for the deployment.

The sanitization pipeline is a second constraint. Miniflux strips external JavaScript, blocks inline scripts and styles, and sanitizes external content. If you subscribe to a feed whose value is an embedded interactive widget, a custom video player, or a scripted chart, that content will not render. The media proxy and youtube-nocookie.com handling cover common cases, and Invidious is supported as an alternative YouTube front end, but arbitrary embedded JavaScript is out by design.

The opinionated UI is a third. The README lists six themes (light and dark, serif and sans-serif, plus system variants) and no theme marketplace. Keyboard shortcuts and optional touch gestures exist. If you want to restyle beyond a custom stylesheet, you are working against the grain. And the compatibility note is explicit: modern browsers only.

Finally, the polling model is pull-based with a default interval of 1h. For a feed that publishes breaking news, an hour is a long wait unless you change the interval or drive updates from cron. Miniflux is a reader, not a notification system; the webhooks and integrations exist to push items elsewhere, not to make the poller faster.

Miniflux v2 versus FreshRSS: two different bets

FreshRSS is the comparison people ask about, and the difference is architectural rather than cosmetic. FreshRSS is a PHP application that supports multiple database backends including SQLite and MySQL, which makes it easier to drop onto shared hosting or a machine with no Postgres. Miniflux takes the opposite bet: one database, one binary, no ORM, and a smaller dependency list. The go.mod file shows a short direct dependency set, mostly golang.org/x packages plus goquery, brotli, go-oidc, go-webauthn, lib/pq, prometheus/client_golang, and tdewolff/minify.

That difference shows up in operations. A FreshRSS upgrade is a PHP file replacement plus a database migration; a Miniflux upgrade is a binary or image swap plus migrations, and the Makefile's packaging targets exist to make that routine. Miniflux's single-binary model means no PHP runtime, no extension configuration, and no web server module to tune, but it also means you cannot run it on a host that only offers PHP hosting.

The API story differs too. Miniflux ships a REST API with Go and Python client libraries in the repository, and it is compatible with existing mobile applications using the Fever or Google Reader API. That compatibility layer matters if you already have a mobile client you like. FreshRSS also exposes Google Reader-compatible endpoints, so this is not a clean win for either side; it is a reason to check your specific client against the documented compatibility list rather than assume.

Maintenance cost, releases, and the Apache-2.0 licence

The repository is not archived, and the most recent push recorded is 2026-09-16. Releases have been frequent: 2.3.3 on 2026-07-24, 2.3.2 on 2026-06-27, and 2.3.1 on 2026-05-29. That cadence suggests a project that ships minor versions regularly, though the README does not document a support window or a backport policy for older releases, so an operator pinning to an older tag has no stated guarantee of fixes.

Upgrade cost is dominated by database migrations, which are bundled with the application. The Makefile's integration-test target points at a DB_URL of postgres://postgres:postgres@localhost/miniflux_test?sslmode=disable, which tells you the project maintains a test database path, but it says nothing about rollback. The README does not document rollback, so a migration that changes schema is a one-way step unless you have a database backup. Back up Postgres before upgrading; that is the only rollback mechanism the documentation supports.

The licence is Apache-2.0. That is a permissive licence with an explicit patent grant, and it does not impose copyleft obligations on your own code. It also does not give you trademark rights to the Miniflux name. If you plan to redistribute a modified build, the Apache-2.0 notice and attribution requirements apply. This is a description of the licence text, not legal advice; consult a lawyer for your specific distribution scenario.

Editorial conclusion

Adopt Miniflux v2 if you already run PostgreSQL, want a small static binary, and accept its opinionated defaults around tracker stripping and sanitized content. Do not adopt it if you need SQLite, MySQL, or a plugin system, or if you expect the reader to render whatever a feed's HTML contains. Before committing, verify your PostgreSQL version supports full-text search the way the project relies on it, confirm that your reverse proxy passes the headers the authentication mode you chose needs, and check whether the integrations you depend on appear in the documented list.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. miniflux/v2 on GitHub
3. Project website
4. README
5. Releases