freshrss_ynh/sources/README.md

• Version française

FreshRSS

FreshRSS is a self-hosted RSS feed aggregator such as Leed or Kriss Feed.

It is at the same time lightweight, easy to work with, powerful and customizable.

It is a multi-user application with an anonymous reading mode. It supports PubSubHubbub for instant notifications from compatible Web sites.

• Official website: http://freshrss.org
• Demo: http://demo.freshrss.org/
• License: GNU AGPL 3

Releases

See the list of releases.

Note on branches

This application is under continuous development! Please use the branch that suits your needs:

• Use the master branch if you need a stable version.
• The beta branch is the default branch: new features are added on a monthly basis.
• For developers and tech savvy persons willing to help testing the latest features, the dev branch is waiting for you!

Disclaimer

This application was developed to fulfil personal needs primarily, and comes with absolutely no warranty. Feature requests, bug reports, and other contributions are welcome. The best way is to open issues on GitHub. We are a friendly community.

Requirements

• Light server running Linux or Windows
  • It even works on Raspberry Pi with response time under a second (tested with 150 feeds, 22k articles, or 32Mo of compressed data)
• A web server: Apache2 (recommended), nginx, lighttpd (not tested on others)
• PHP 5.2.1+ (PHP 5.3.7+ recommended, and PHP 5.5+ for performance) (beta support for PHP 7 with even higher performance)
  • Required extensions: PDO_MySQL or PDO_SQLite, cURL, GMP (for API access on platforms < 64 bits), IDN (for Internationalized Domain Names)
  • Recommended extensions: JSON, mbstring, zlib, Zip
• MySQL 5.0.3+ (recommended) or SQLite 3.7.4+
• A recent browser like Firefox, Chrome, Opera, Safari. Internet Explorer currently not supported, but support will come back.
  • Works on mobile

Installation

1. Get FreshRSS with git or by downloading the archive
2. Dump the application on your server (expose only the ./p/ folder)
3. Add write access on ./data/ folder to the webserver user
4. Access FreshRSS with your browser and follow the installation process
5. Everything should be working :) If you encounter any problem, feel free to contact me.
6. Advanced configuration settings can be seen in config.php.

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
# (Optional) If you want a MySQL database server
sudo apt-get install mysql-server mysql-client php5-mysql
# Main components (git is optional if you manually download the installation files)
sudo apt-get install git php5 php5-curl php5-gd php5-intl php5-json php5-gmp php5-sqlite
# Restart Web server
sudo service apache2 restart

# For FreshRSS itself
cd /usr/share/
sudo git clone https://github.com/FreshRSS/FreshRSS.git
# Set the rights so that your Web browser can access the files
cd FreshRSS
sudo chown -R :www-data .
sudo chmod -R g+w ./data/
# 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)

# Update to a newer version of FreshRSS
cd /usr/share/FreshRSS
sudo git reset --hard
sudo git pull
sudo chown -R :www-data .
sudo chmod -R g+w ./data/

Access control

It is needed for the multi-user mode to limit access to FreshRSS. You can:

• use form authentication (need JavaScript and PHP 5.3.7+, works with some PHP 5.3.3+)
• use Mozilla Persona authentication included in FreshRSS
• use HTTP authentication supported by your web server
  • See Apache documentation
    • In that case, create a ./p/i/.htaccess file with a matching .htpasswd file.

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’s a good idea to use the Web server user. For example, if you want to run the script every hour:

7 * * * * php /your-path/FreshRSS/app/actualize_script.php > /tmp/FreshRSS.log 2>&1

Advices

• For a better security, expose only the ./p/ folder on the web.
  • Be aware that the ./data/ folder contains all personal data, so it is a bad idea to expose it.
• The ./constants.php file defines access to application folder. If you want to customize your installation, every thing happens here.
• If you encounter any problem, logs are accessible from the interface or manually in ./data/log/*.log files.

Backup

• You need to keep ./data/config.php, ./data/*_user.php and ./data/persona/ files
• You can export your feed list in OPML format from FreshRSS
• To save articles, you can use phpMyAdmin or MySQL tools:

mysqldump -u user -p --databases freshrss > freshrss.sql

Included libraries

• SimplePie
• MINZ
• php-http-304
• jQuery
• keyboard_shortcuts
• flotr2

Only for some options

• bcrypt.js
• phpQuery

If native functions are not available

• Services_JSON
• password_compat