README.md 12 KB
- Read this document on github.com/FreshRSS/FreshRSS/ to get the correct links and pictures.
- Version française
FreshRSS
FreshRSS is a self-hosted RSS feed aggregator like Leed or Kriss Feed.
It is lightweight, easy to work with, powerful, and customizable.
It is a multi-user application with an anonymous reading mode. It supports custom tags. There is an API for (mobile) clients, and a Command-Line Interface.
Thanks to the WebSub standard (formerly PubSubHubbub), FreshRSS is able to receive instant push notifications from compatible sources, such as Mastodon, Friendica, WordPress, Blogger, FeedBurner, etc.
Finally, it supports extensions for further tuning.
Feature requests, bug reports, and other contributions are welcome. The best way to contribute is to open an issue on GitHub. We are a friendly community.
- Official website: https://freshrss.org
- Demo: https://demo.freshrss.org/
- License: GNU AGPL 3
Disclaimer
FreshRSS comes with absolutely no warranty.
Documentation
- User documentation, where you can discover all the possibilities offered by FreshRSS
- Administrator documentation for detailed installation and maintenance related tasks
- Developer documentation to guide you in the source code of FreshRSS and to help you if you want to contribute
- Contributor guidelines for those who want to help improve FreshRSS
Requirements
- A recent browser like Firefox / IceCat, Internet Explorer 11 / Edge (minus a few details), Chromium / Chrome, Opera, Safari.
- Works on mobile (except a few features)
- Light server running Linux or Windows
- It even works on Raspberry Pi 1 with response time under a second (tested with 150 feeds, 22k articles)
- A web server: Apache2 (recommended), nginx, lighttpd (not tested on others)
- PHP 5.6+ (PHP 7+ recommended for higher performance)
- Required extensions: cURL, DOM, JSON, XML, session, ctype, and PDO_MySQL or PDO_SQLite or PDO_PGSQL
- Recommended extensions: GMP (for API access on 32-bit platforms), IDN (for Internationalized Domain Names), mbstring (for Unicode strings), iconv (for charset conversion), ZIP (for import/export), zlib (for compressed feeds)
- MySQL 5.5.3+ or MariaDB equivalent, or SQLite 3.7.4+, or PostgreSQL 9.5+
Releases
See the list of releases.
About branches
- Use the master branch if you need less frequent stable versions.
- Use the dev branch if you want a rolling release with the newest features, or help testing or developing the next stable version.
Installation
Automated install
Manual install
- Get FreshRSS with git or by downloading the archive
- Put the application somewhere on your server (expose only the
./p/folder to the Web) - Add write access to the
./data/folder for the webserver user - Access FreshRSS with your browser and follow the installation process
- or use the Command-Line Interface
- Everything should be working :) If you encounter any problems, feel free to contact us.
- Advanced configuration settings can be found in config.default.php and modified in
data/config.php. - When using Apache, enable
AllowEncodedSlashesfor better compatibility with mobile clients.
More detailed information about installation and server configuration can be found in our documentation.
Example of full installation on Linux Debian/Ubuntu
# If you use an Apache Web server (otherwise you need another Web server)
sudo apt-get install apache2
sudo a2enmod headers expires rewrite ssl #Apache modules
# Example for Ubuntu >= 16.04, Debian >= 9 Stretch
sudo apt install php php-curl php-gmp php-intl php-mbstring php-sqlite3 php-xml php-zip
sudo apt install libapache2-mod-php #For Apache
sudo apt install mysql-server mysql-client php-mysql #Optional MySQL database
sudo apt install postgresql php-pgsql #Optional PostgreSQL database
# Restart Web server
sudo service apache2 restart
# For FreshRSS itself (git is optional if you manually download the installation files)
cd /usr/share/
sudo apt-get install git
sudo git clone https://github.com/FreshRSS/FreshRSS.git
cd FreshRSS
# If you want to use the development version of FreshRSS
sudo git checkout -b dev origin/dev
# Set the rights so that your Web server can access the files
sudo chown -R :www-data . && sudo chmod -R g+r . && sudo chmod -R g+w ./data/
# If you would like to allow updates from the Web interface
sudo chmod -R g+w .
# Publish FreshRSS in your public HTML directory
sudo ln -s /usr/share/FreshRSS/p /var/www/html/FreshRSS
# Navigate to http://example.net/FreshRSS to complete the installation
# (If you do it from localhost, you may have to adjust the setting of your public address later)
# or use the Command-Line Interface
# Update to a newer version of FreshRSS with git
cd /usr/share/FreshRSS
sudo git pull
sudo chown -R :www-data . && sudo chmod -R g+r . && sudo chmod -R g+w ./data/
See more commands and git commands in the Command-Line Interface documentation.
Access control
This is needed if you will be using the multi-user mode, to limit access to FreshRSS. Options Available:
- form authentication (needs JavaScript)
- HTTP authentication supported by your web server
- See Apache documentation
- In that case, create a
./p/i/.htaccessfile with a matching.htpasswdfile.
- In that case, create a
- See Apache documentation
Automatic feed update
You can add a Cron job to launch the update script. Check the Cron documentation related to your distribution (Debian/Ubuntu, Red Hat/Fedora, Slackware, Gentoo, Arch Linux…). It is a good idea to run the cron job as the webserver user (often “www-data”). For instance, if you want to run the script every hour:
9 * * * * php /usr/share/FreshRSS/app/actualize_script.php > /tmp/FreshRSS.log 2>&1
Example on Debian / Ubuntu
Create /etc/cron.d/FreshRSS with:
6,36 * * * * www-data php -f /usr/share/FreshRSS/app/actualize_script.php > /tmp/FreshRSS.log 2>&1
Advice
- For better security, expose only the
./p/folder to the Web.- Be aware that the
./data/folder contains all personal data, so it is a bad idea to expose it.
- Be aware that the
- The
./constants.phpfile defines access to the application folder. If you want to customize your installation, look here first. - If you encounter any problem, logs are accessible from the interface or manually in
./data/users/*/log*.txtfiles.- The special folder
./data/users/_/contains the part of the logs that are shared by all users.
- The special folder
F.A.Q.:
- The date and time in the right-hand column is the date declared by the feed, not the time at which the article was received by FreshRSS, and it is not used for sorting.
- In particular, when importing a new feed, all of its articles will appear at the top of the feed list regardless of their declared date.
Backup
- You need to keep
./data/config.php, and./data/users/*/config.phpfiles - You can export your feed list in OPML format either from the Web interface, or from the Command-Line Interface
To save articles, you can use phpMyAdmin or MySQL tools:
mysqldump --skip-comments --disable-keys --user=<db_user> --password --host <db_host> --result-file=freshrss.dump.sql --databases <freshrss_db>
Extensions
FreshRSS supports further customizations by adding extensions on top of its core functionality. See the repository dedicated to those extensions.
APIs & native apps
FreshRSS supports access from native apps for Linux, Android, iOS, and OS X, via two distinct APIs.
Google Reader-like API
There is more information available about our Google Reader compatible API on the page mobile access.
Supported clients are:
- Android
- News+ with News+ Google Reader extension (Closed source)
- FeedMe 3.5.3+ (Closed source)
- EasyRSS (Open source, F-Droid)
- GNU/Linux
- FeedReader 2.0+ (Open source)
- iOS
- Reeder-4 (Commercial)
- MacOS
- Vienna RSS (Open source)
Fever API
See our Fever API documentation page.
Supported clients are:
- Android
- Readably (Closed source)
- iOS
- Fiery Feeds (Closed source)
- Unread (Commercial)
- MacOS
- Readkit (Commercial)