A minimal-viable feed aggregator made for self-hosting.
headless-rss is an rss feed aggregator with a minimal feature set.
It is intended to be used in a homelab setting with a single user. It provides
a Nextcloud News compatible API,
and can serve as a back-end for compatible apps. It is tested with
Fiery Feeds.
If you are looking for a feature-complete feed aggregator back-end that supports e.g. different protocols, multiple users or databases other than sqlite, please look at Arsse or Nextcloud News.
- Can aggregate rss and atom feeds
- Can serve as a back-end for applications that speak the Nextcloud News protocol. Fiery Feeds is tested and works well.
- Can be hosted with a single unprivileged docker container.
- Low resource usage (~1/4 efficiency core, 75 MB RAM).
- Updates feeds on a dynamic schedule based on their post frequency.
Start the API with:
docker run -d --rm --user 9999 --init \
--name headless_rss \
--volume headless-rss-data:/app/data \
--publish 8000:8000 \
--env USERNAME=myuser \
--env PASSWORD=mypassword \
ghcr.io/paulstaab/headless-rss:latest
The USERNAME and PASSWORD environment variables are optional to enable authentication.
The FEED_UPDATE_FREQUENCY_MIN environment variable is optional to set the update frequency for feeds
in minutes (default is 15 minutes).
headless-rss can connect to an existing email account via IMAP and display email
newsletters send to this account as feeds.
To add email credentials for fetching newsletters, use the following CLI command:
docker exec -ti add-email-credentials --server imap.example.com --port 993 --username [email protected] --password yourpassword
Replace the placeholders with your actual email server details.
- Bugfixes are welcome.
- Please submit an issue for feature requests before creating a pull-request. I want to keep this project as small as possible.
This project is licensed under the MIT License. See the LICENSE file for details.