feed

README

feed.

A self-hosted, mobile-first feed reader. Subscribe to RSS/Atom/JSON feeds, get articles ranked by a model that learns from your votes, and receive push notifications for noteworthy content. Installable as a PWA; the server is a single static binary.

Features

• 📡 RSS, Atom and JSON Feed subscriptions, polled automatically
• 🎯 Relevance ranking that learns from your up/down votes (downvotes remove the article for good)
• 🔔 Push notifications for high-rank articles, with per-source rules (always / never / by rank)
• 🔖 Saved content, optionally mirrored to a Memos instance
• 📱 Installable PWA with offline app shell
• 🔐 Basic auth (htpasswd) for self-hosting behind your gateway

Install

From GitHub releases

1. Grab the binary for your platform from the latest release:

   File	Platform
   feed-linux-amd64	Linux x86-64
   feed-darwin-amd64	macOS (Intel; works on Apple Silicon via Rosetta)

2. Install it:

   sudo install -m 0755 feed-linux-amd64 /usr/local/bin/feed
   

   (On Apple Silicon you can also build natively — see “From source”.)

3. Verify:

   feed -gen-vapid    # should print a VAPID key pair
   

With Go

go install github.com/anothertijuano/feed@latest

Requires Go 1.25+.

From source

git clone git@github.com:anothertijuano/feed.git
cd feed
make build          # ./feed
sudo make install   # installs to /usr/local/bin/feed

Quick start

feed -addr :8000 -data ./data

Open http://localhost:8000, go to the Subs tab, paste a feed URL and hit Add. New articles appear ranked by relevance; vote on them to teach the ranking. Pull down at the top of the feed (or tap ↻) to refresh.

Tab	What it does
Feed	ranked infinite scroll; ♥/↓/bookmark to vote and save, double-tap to like
Saved	everything you bookmarked
Subs	add/remove feeds, refresh, per-source notification rules (bell)
Settings	Memos connection, push notifications

Configuration

Flag	Default	Meaning
-addr	:8000	address to listen on
-data	data	directory for the on-disk database
-refresh	15m	how often subscriptions are polled
-htpasswd	(empty)	htpasswd file → enables HTTP Basic auth
-push-threshold	0.3	rank threshold for push notifications
-notify-age	48h	max article age eligible for notifications
-vapid-subject	mailto:admin@localhost	VAPID subject (your email/URL)
-gen-vapid	(flag)	print a VAPID key pair and exit

Security

feed. is meant to sit behind your gateway (Caddy, nginx, Traefik) which terminates TLS — the service itself speaks plain HTTP.

htpasswd -Bc htpasswd admin        # create credentials
feed -addr :8000 -htpasswd htpasswd

• bcrypt (htpasswd -B), {SHA} and plaintext entries are supported; the file is hot-reloaded when it changes.
• Everything is protected except /api/health and the static PWA files (/manifest.json, /sw.js, /icons/*), which hold no data.
• Web Push requires HTTPS in the browser, so make sure your gateway terminates TLS.
• VAPID keys are generated into data/vapid.json (0600) on first start. Set -vapid-subject to an email you control.

Notifications

High-rank articles notify you automatically. In the Subs tab, each source has a bell: default (notify on high rank), always (every new article), never. Enable push in Settings → Notifications — on iOS, add the app to the home screen first.

Updating

Download the new binary from the releases page and replace the old one. Your data (votes, subscriptions, saved items) lives in the -data directory and is preserved across upgrades.

For developers

• API reference — endpoints for third-party clients
• Internals — database layout and architecture

make test    # run the test suite
make run     # serve on :8000 with data in ./data

Frontend assets are embedded at build time — restart to pick up changes.