diff options
Diffstat (limited to 'docs/en/users')
| -rw-r--r-- | docs/en/users/01_Installation.md | 120 | ||||
| -rw-r--r-- | docs/en/users/02_First_steps.md | 4 | ||||
| -rw-r--r-- | docs/en/users/05_Configuration.md | 16 | ||||
| -rw-r--r-- | docs/en/users/06_Mobile_access.md | 52 |
4 files changed, 62 insertions, 130 deletions
diff --git a/docs/en/users/01_Installation.md b/docs/en/users/01_Installation.md deleted file mode 100644 index b2a717629..000000000 --- a/docs/en/users/01_Installation.md +++ /dev/null @@ -1,120 +0,0 @@ -# Server requirements - -FreshRSS is a web application. This means you'll need a web server to run it. FreshRSS requirements are really low, so it could run on most shared host servers. - -You need to verify that your server can run FreshRSS before installing it. If your server has the proper requirements and FreshRSS does not work, please contact us to find a solution. - -| Software | Recommended | Works also with | -| ----------- | ---------------- | ----------------------------- | -| Web server | **Apache 2** | Nginx | -| PHP | **PHP 5.5+** | PHP 5.3.8+ | -| PHP modules | Required: libxml, cURL, PDO_MySQL, PCRE and ctype. \\ Required (32-bit only): GMP \\Recommanded: JSON, Zlib, mbstring, iconv, ZipArchive | | -| Database | **MySQL 5.0.3+** | SQLite 3.7.4+ | -| Browser | **Firefox** | Chrome, Opera, Safari or IE9+ | - -## Important notice - -FreshRSS **CAN** work with PHP 5.3.8+. To do so, we are using specific functions available in the [''password_compat'' library](https://github.com/ircmaxell/password_compat#requirements) for the form authentication. - - -# Getting the appropriate version of FreshRSS - -FreshRSS has three different releases or branches. Each branch has its own release frequency. So it is better if you spend some time to understand the purpose of each release. - -## Stable release - -[Download](https://github.com/FreshRSS/FreshRSS/archive/master.zip) - -This release is done when we consider that our goal concerning the new features and the stability is reached. It could happen that we make two releases in a really short time if we have a really good coding pace. In reality, we are all working on our spare time, so we release every few months. But this version is really stable, tested thoroughly and you should not face any major bugs. - -## Development release - -[Download](https://github.com/FreshRSS/FreshRSS/archive/dev.zip) - -As its name suggests, it is the working release for developers. **This release is unstable!** If you want to keep track of enhancements on a daily basis, you can use it. But keep in mind that you need to follow the branch activity on Github (via [the branch RSS feed](https://github.com/FreshRSS/FreshRSS/commits/dev.atom) for instance). Some say that the main developers use it on a daily basis without problem. They may know what they are doing… - -# Apache installation - -This is an example Apache virtual hosts configuration file. It covers http and https configuration. - -``` -<VirtualHost *:80> - ServerName example.com - DocumentRoot /path/to/FreshRSS - - ErrorLog ${APACHE_LOG_DIR}/freshrss_error.log - CustomLog ${APACHE_LOG_DIR}/freshrss_access.log combined - - RewriteEngine on - RewriteCond %{SERVER_NAME} = example.com - RewriteRule ^ https://%{SERVER_NAME}%{REQUEST_URI} [END,QSA,R=permanent] -</VirtualHost> - -<IfModule mod_ssl.c> -<VirtualHost *:443> - ServerName example.com - DocumentRoot /path/to/FreshRSS - - ErrorLog ${APACHE_LOG_DIR}/freshrss_error.log - CustomLog ${APACHE_LOG_DIR}/freshrss_access.log combined - - SSLCertificateFile /path/to/server.crt - SSLCertificateKeyFile /path/to/server.key - - # Optional letsencrypt config (uncomment) line below - #Include /etc/letsencrypt/options-ssl-apache.conf -</VirtualHost> -</IfModule> -``` - -# Nginx installation - -This is an example nginx configuration file. It covers http, https and php-fpm configuration. - -_You can find simpler config file but they may be incompatible with FreshRSS API._ - -``` -server { - listen 80; # http on port 80 - listen 443 ssl; # https on port 443 - - # https configuration - ssl on; - ssl_certificate /etc/nginx/server.crt; - ssl_certificate_key /etc/nginx/server.key; - - # your server's url(s) - server_name example.com rss.example.com; - - # the folder p of your FreshRSS installation - root /srv/FreshRSS/p/; - - index index.php index.html index.htm; - - # nginx log files - access_log /var/log/nginx/rss.access.log; - error_log /var/log/nginx/rss.error.log; - - # php files handling - # this regex is mandatory because of the API - location ~ ^.+?\.php(/.*)?$ { - fastcgi_pass unix:/var/run/php5-fpm.sock; - fastcgi_split_path_info ^(.+\.php)(/.*)$; - # By default, the variable PATH_INFO is not set under PHP-FPM - # But FreshRSS API greader.php need it. If you have a "Bad Request" error, double check this var ! - fastcgi_param PATH_INFO $fastcgi_path_info; - include fastcgi_params; - fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name; - } - - location / { - try_files $uri $uri/ index.php; - } -} -``` - -A step-by-step tutorial is available [in french](http://www.pihomeserver.fr/2013/05/08/raspberry-pi-home-server-installer-un-agregateur-de-flux-rss-pour-remplacer-google-reader/). - -# Security - -**TODO** diff --git a/docs/en/users/02_First_steps.md b/docs/en/users/02_First_steps.md index 96ee264a6..2fb1b7256 100644 --- a/docs/en/users/02_First_steps.md +++ b/docs/en/users/02_First_steps.md @@ -2,7 +2,7 @@ Learning how to handle a new application is not always easy. We build FreshRSS t This section guides you to the pages you need as a new comer. -[After you installed the application](01_Installation.md), the first step is to add one or more feeds. You have few options: +[After installing the application](../admins/02_Installation.md), the first step is to add some feeds. You have a few options: 1. [Add a feed manually](04_Subscriptions.md#adding-a-feed) 2. [Import an OPML or JSON file](04_Subscriptions.md#import-and-export) @@ -24,3 +24,5 @@ Now that you know the basic usages, it is time to configure FreshRSS to improve * [Filter articles](03_Main_view.md#filtering-articles) for a fast access to a selection * [Search an article](03_Main_view.md#searching-articles) published some time ago * [Access your feeds on a mobile device](06_Mobile_access.md) +* [Add some extensions](https://github.com/FreshRSS/Extensions) +* [Frequently asked questions](07_Frequently_Asked_Questions.md) diff --git a/docs/en/users/05_Configuration.md b/docs/en/users/05_Configuration.md index f8ac56cd7..d0951e905 100644 --- a/docs/en/users/05_Configuration.md +++ b/docs/en/users/05_Configuration.md @@ -20,7 +20,7 @@ In matters of taste and color, there can be no disputes. This is why FreshRSS of If none of these are suitable for you, it is always possible to create your own. -To select a theme, simply scroll through the themes and select a theme that appears. After confirmation, the theme will be applied to the interface. +To select a theme, simply scroll through the themes and select one that strikes your fancy. After confirmation, the theme will be applied to the interface. ## Content width @@ -69,10 +69,10 @@ The duration of this notification can be set. By default, the value is 0. ### HTTP Authentication (Apache) - 1. User control is based on the .htaccess file - 2. It is best practice to place the .htaccess file in ./i/ subdirecotry so API and other third party services can work. - 3. If you want to limit all access to registered users only, place the file in the directory of FreshRSS or in a parent directory. Note that PubsubHubbub and API will not work! - 4. Example .htaccess file for a user "marie": + 1. User control is based on the `.htaccess` file. + 2. It is best practice to place the `.htaccess` file in the `./i/` subdirectory so the API and other third party services can work. + 3. If you want to limit all access to registered users only, place the file in the FreshRSS directory itself or in a parent directory. Note that PubsubHubbub and API will not work! + 4. Example `.htaccess` file for a user "marie": ``` AuthUserFile /home/marie/repertoire/.htpasswd @@ -82,7 +82,7 @@ AuthType Basic Require user marie ``` -More information can be found in [Apache documentation](http://httpd.apache.org/docs/trunk/howto/auth.html#gettingitworking). +More information can be found in the [Apache documentation](http://httpd.apache.org/docs/trunk/howto/auth.html#gettingitworking). # Subscription management @@ -104,7 +104,7 @@ More information can be found in [Apache documentation](http://httpd.apache.org/ The question comes up regularly, so we will try to clarify here how one can retrieve a truncated RSS feed with FreshRSS. Please note that the process is absolutely not "user friendly", but it works :) -Also know that this way you are generating much more traffic to the originating sites and that they can block you accordingly. The performance of FreshRSS is also imapcted because you have to fetch the contents of the articles one by one. So it's a feature to use sparingly! +Also know that this way you are generating much more traffic to the originating sites and that they might block you accordingly. The performance of FreshRSS is also negatively affected because you have to fetch the full article content one by one. So it's a feature to use sparingly! What is meant by "CSS path of articles on the original site" actually corresponds to the "path" consisting of IDs and classes (which in html, matches the id and class attributes) to retrieve only the interesting part that corresponds to the article. Ideally, this path starts with an id (which is unique to the page). @@ -118,4 +118,4 @@ We find here that the block that encompasses only the content of the article is * Rue89: ```#article .content``` * PCINpact: ```#actu_content``` -* Lesnumériques: ```article#body div.text.clearfix```
\ No newline at end of file +* Lesnumériques: ```article#body div.text.clearfix``` diff --git a/docs/en/users/06_Mobile_access.md b/docs/en/users/06_Mobile_access.md index e1a23c8ba..3472172b0 100644 --- a/docs/en/users/06_Mobile_access.md +++ b/docs/en/users/06_Mobile_access.md @@ -1 +1,51 @@ -**TODO** +This page assumes you have completed the [server setup](../admins/02_Installation.md). + +# Enable the API in FreshRSS + +1. Under the section “Authentication”, enable the option “Allow API access (required for mobile apps)”. +2. Under the section “Profile”, fill-in the field “API password (e.g., for mobile apps)”. + * Every user must define an API password. + * The reason for an API-specific password is that it may be used in less safe situations than the main password, and does not grant access to as many things. + + +# Testing + +3. Under the section “Profile”, click on the link like `https://rss.example.net/api/` next to the field “API password”. +4. Click on first link “Check full server configuration”: + * If you get *PASS* then you are done, all is good: you may proceed to step 6. + * If you get *Bad Request!* or *Not Found*, then your server probably does not accept slashes `/` that are escaped `%2F`. Proceed to step 5. + * If you get any other error message, proceed to step 5. + + +# Fix server configuration + +5. Click on the second link “Check partial server configuration (without `%2F` support)”: + * If you get `PASS`, then the problem is indeed that your server does not accept slashes `/` that are escaped `%2F`. + * With Apache, remember the directive [`AllowEncodedSlashes On`](http://httpd.apache.org/docs/trunk/mod/core.html#allowencodedslashes) + * Or use a client that does not escape slashes (such as EasyRSS), in which case proceed to step 6. + * If you get *Service Unavailable!*, then check from step 1 again. + * With __Apache__: + * If you get *FAIL getallheaders!*, the combination of your PHP version and your Web server does not provide access to [`getallheaders`](http://php.net/getallheaders) + * Update to PHP 5.4+, or use PHP as module instead of CGI. Otherwise turn on Apache `mod_rewrite`: + * Allow [`FileInfo` in `.htaccess`](http://httpd.apache.org/docs/trunk/mod/core.html#allowoverride): see the [server setup](../admins/02_Installation.md) again. + * Enable [`mod_rewrite`](http://httpd.apache.org/docs/trunk/mod/mod_rewrite.html): + * With Debian / Ubuntu: `sudo a2enmod rewrite` + * With __nginx__: + * If you get *Bad Request!*, check your server `PATH_INFO` configuration. + * If you get *File not found!*, check your server `fastcgi_split_path_info`. + * If you get *FAIL 64-bit or GMP extension!*, then your PHP version does not pass the requirement of being 64-bit and/or have PHP [GMP](http://php.net/gmp) extension. + * The easiest is to add the GMP extension. On Debian / Ubuntu: `sudo apt install php-gmp` + * Update and try again from step 3. + + +# Compatible clients + +6. On the same FreshRSS API page, note the adress given under “Your API address”, like `https://freshrss.example.net/api/greader.php` + * You will type it in a client, together with your FreshRSS username, and the corresponding special API password. + +7. Pick a client supporting a Google Reader-like API. Selection: + * Android + * [News+](https://play.google.com/store/apps/details?id=com.noinnion.android.newsplus) with [News+ Google Reader extension](https://play.google.com/store/apps/details?id=com.noinnion.android.newsplus.extension.google_reader) (Closed source) + * [EasyRSS](https://github.com/Alkarex/EasyRSS) (Open source, [F-Droid](https://f-droid.org/packages/org.freshrss.easyrss/)) + * Linux + * [FeedReader 2.0+](https://jangernert.github.io/FeedReader/) (Open source) |