From 32e9d3a5a17edd33ed19158bf567c857fb4fea78 Mon Sep 17 00:00:00 2001 From: Alexandre Alapetite Date: Sun, 12 Nov 2017 15:51:43 +0100 Subject: A bit of documentation for the API (#1689) https://github.com/FreshRSS/FreshRSS/issues/1687 https://github.com/FreshRSS/FreshRSS/issues/443#issuecomment-36666133 --- docs/en/users/01_Installation.md | 25 +++++++++++++------ docs/en/users/06_Mobile_access.md | 52 ++++++++++++++++++++++++++++++++++++++- 2 files changed, 69 insertions(+), 8 deletions(-) (limited to 'docs/en') diff --git a/docs/en/users/01_Installation.md b/docs/en/users/01_Installation.md index d0046eebe..9d012f2b1 100644 --- a/docs/en/users/01_Installation.md +++ b/docs/en/users/01_Installation.md @@ -1,6 +1,6 @@ # 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. +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. @@ -35,7 +35,7 @@ As its name suggests, it is the working release for developers. **This release i # Apache installation -This is an example Apache virtual hosts configuration file. It covers http and https configuration. +This is an example Apache virtual hosts configuration file. It covers HTTP and HTTPS configuration. ``` @@ -51,6 +51,11 @@ This is an example Apache virtual hosts configuration file. It covers http and h ServerName rss.example.net DocumentRoot /path/to/FreshRSS/p/ + + AllowOverride AuthConfig FileInfo Indexes Limit + Require all granted + + ErrorLog ${APACHE_LOG_DIR}/freshrss_error.log CustomLog ${APACHE_LOG_DIR}/freshrss_access.log combined @@ -62,6 +67,11 @@ This is an example Apache virtual hosts configuration file. It covers http and h ServerName rss.example.net DocumentRoot /path/to/FreshRSS/p/ + + AllowOverride AuthConfig FileInfo Indexes Limit + Require all granted + + ErrorLog ${APACHE_LOG_DIR}/freshrss_error.log CustomLog ${APACHE_LOG_DIR}/freshrss_access.log combined @@ -69,6 +79,7 @@ This is an example Apache virtual hosts configuration file. It covers http and h Protocols h2 http/1.1 + # For the API AllowEncodedSlashes On SSLEngine on @@ -82,7 +93,7 @@ This is an example Apache virtual hosts configuration file. It covers http and h # Nginx installation -This is an example nginx configuration file. It covers http, https and php-fpm configuration. +This is an example nginx configuration file. It covers HTTP, HTTP, and php-fpm configuration. _You can find simpler config file but they may be incompatible with FreshRSS API._ @@ -91,12 +102,12 @@ server { listen 80; listen 443 ssl; - # https configuration + # HTTPS configuration ssl on; ssl_certificate /etc/nginx/server.crt; ssl_certificate_key /etc/nginx/server.key; - # your server's url(s) + # your server’s URL(s) server_name rss.example.net; # the folder p of your FreshRSS installation @@ -114,7 +125,7 @@ server { 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 ! + # 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; @@ -126,7 +137,7 @@ server { } ``` -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/). +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 diff --git a/docs/en/users/06_Mobile_access.md b/docs/en/users/06_Mobile_access.md index e1a23c8ba..d935411eb 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](01_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](01_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) -- cgit v1.2.3