A simple and elegant feed reader.
This project is now hosted in Gitlab. If you're reading this somewhere else (e.g. in Github) be aware that it is a read-only mirror.
This project automatically builds Docker images and pushes them to Docker Hub every time a release is tagged in the main branch. You can find these images here:
All of these images are required simultaneously to run FeedBunch. For information about how to deploy to Docker using docker-compose see the installation instructions.
FeedBunch is a feed reader, a web application that allows users to subscribe and read Atom and RSS feeds. It can be self-hosted, and is fully open source.
FeedBunch aims to be as pleasant to use as possible, with a simple and uncluttered interface. It hides unnecessary complexity from users as much as possible:
You can find a simple description of what a feed reader is in this wikipedia article and a good description of the use and technology behind feeds in this Google support article.
Basically it is a way to aggregate content updates from various websites in a single place. Instead of having to visit each of your favorite websites every day to see if there's new content, anything those websites publish will appear in FeedBunch. This way you only have to visit FeedBunch to be up to date with all blogs, newspapers, webcomics etc that you follow. You will save a lot of time.
Another advantage of using a feed reader is that you can subscribe and unsubscribe from feeds as you get interested or lose your interest in them, in a way creating your own personalized newspaper. You can also organize feeds in folders to help you organize your reading efficiently and cope with information overload. Believe me, using feeds is addictive, you may soon find yourself subscribed to so many that anything that helps you organize them sounds like a great idea!
For this to work, each website has to make available a special XML document that gets updated every time new content is published in the website. This XML document is called the feed and every new piece of content that is added to it is called an entry. Entries can be news articles in a newspaper's website, new pages in a webcomic, new comments in a blog entry... Most websites nowadays have a feed (or several), in fact most blogging and CMS platforms include a feed by default in any websites they manage, without having to configure anything.
The main standards for feeds are RSS and Atom (wikipedia links). Often people speak about "RSS feeds" indistinctly, which is actually a bit of a misnomer. FeedBunch users don't have to worry about this, both standards are transparently supported.
The supported installation method uses Docker-compose. Follow these instructions.
If you follow the installation instructions you will have the credentials (username/password) for the first user, who will have administration permissions.
If you want to create users for other people in your installation, open the drop-down menu at the top right, and go
to Administration / Users / New User
(click on New User
button).
The first time you sign in take some time to follow the interactive tours, they will show you what you can do with the application. Import your subscriptions in OPML format from another feed aggregator or just start subscribing to feeds. Pretty soon you will have a personalized set of feeds that interest you.
There are two main directories in the project:
FeedBunch-app
: contains the main Ruby on Rails application. It can be tested and deployed like any other
Rails app, but the supported deployment method uses docker-compose.FeedBunch-docker
: contains the Dockerfiles and other files necessary to build Docker images for the app,
as well as a sample docker-compose.yml that can be customized and used to deploy FeedBunch as explained in the
installation instructions.Inside the FeedBunch-docker
directory there are several directories, each one with a Dockerfile and files
necessary to build a different Docker image:
FeedBunch-background
: image that runs a Sidekiq job queue and runs asynchronous jobs, most importantly
refreshing feeds periodically.FeedBunch-cron
: image that runs periodically a script to clean up old files from the cache that
accelerates refreshing feeds, so that disk usage does not grow too much.FeedBunch-redis-cache
: image that runs a Redis database that serves as backend for the Rails HTML fragment
cache, accelerating the generation of dynamic pages for users.FeedBunch-redis-sidekiq
: image that runs a Redis database that serves as a backend for the Sidekiq job
queue (see FeedBunch-background
).FeedBunch-webapp
: main Rails app that serves HTML pages to users.You can get help, inform me of bugs, suggest new features or just tell me what you think about FeedBunch through:
You can use any of them, but in general:
For a good long while the most popular feed reader was Google Reader. In fact it was probably the only feed reader that mattered for most of the Internet. However Google closed down GReader on July 1 2013, forcing users to migrate to alternative services. The development of FeedBunch was started to attempt to replace GReader and it is no coincidence that some ideas in the user interface are inspired in GReader.
The server API is written using Ruby on Rails, along with many ruby gems generously shared by the community. Sidekiq is used to process jobs asynchronously.
The client is an Ajax webpage. Bootstrap is used for the visual layout, along with FontAwesome for the icons. AngularJS is used to communicate with the server-side API and keep the page dinamically updated with feeds, entries etc. Several javascript libraries are also used like velocity.js for animations, hopscotch.js for the guided tours, favico.js to display the number of unread entries in the favicon, and others.
PostgreSQL is used for the database layer, and Redis for more transient data (Rails cache and Sidekiq data).
Licensed under the MIT license (see LICENSE.txt file in the root directory for details).
Code is hosted in the amatriain/feedbunch gitlab repo.
You can create issues in the issue tracker to discuss any bugs you find.
To contribute code:
All classes, modules and methods are commented with Rdoc.
If you add new methods, classes etc please add comments comparable to the existing ones. If you change existing methods please update the method and class comment if they no longer accurately describe the method behavior.
You can add Ruby comments wherever you think the intent is not clear from reading the code. Just don't overdo it, the best code is self-explanatory.
The project uses Rspec for its tests. The spec
folder is organized a bit different from the default Rspec layout:
unit_tests
folder has unit tests for individual classes (models, controllers, etc).acceptance_tests
folder contains what Rspec calls feature tests. They simulate a user operating the
application with a headless webkit browser, using the selenium-webdriver gem.Tests use FactoryBot object factories, instead of test fixtures. Factory definitions are in the
spec/factories
folder.
Please add new tests or update existing ones when adding or changing features.
Gitlab CI/CD is used for continuous integration/delivery. Any pull requests that have failed tests will probably not be accepted.
The rails logger (Rails.logger
) is used to write a log of events. Most methods have log statements to help with
debugging.
If you add features please consider if it's worth it adding log statements. Remember that the default log level in
production is warn
, so use lower-priority logging (debug
, info
) for log lines that are not usually
interesting, only when debugging a particular problem. Try not to clutter the logs.