**General rewording, proof-reading, deduplication, shortening, reordering, simplification, cleanup/formatting/standardization**

- standardize page names, rework documentation structure, update TOC
- use same example paths everywhere
- level 1 titles on all pages
- fix broken links
- .md suffix on all page links (works both from readthedocs and github repository views)

**Server:**

A full and concise installation guide with examples is a frequent request. The documentation should provide such a guide for basic installation needs, while explaining alternative/advanced configuration at the end. Links to reference guides and documentation should be used more frequently to avoid recommending an outdated or excessively complex configuration.

- server: move most server-related info to server-configuration.md, cleanup/shorten
- server: update list of php dependencies/libraries, link to composer.json
- server: installation: support 3 install methods (from release zip, from sources, using docker)
- server: installation: use rsync instead of mv as mv results will change depending of taget directory already existing or not
- server: add example/basic usage of certbot
- server, upgrade, installation: update file permissions setup, use sudo for upgrade operations in webserver document root
- server: apache: add comments to configuration, fix and factorize file permissions setup, set cache-control header, deny access to dotfiles, add missing apache config steps, add http->https redirect example
- server: nginx: refactor nginx configuration, add comments, DO log access to denied/protected files
- server: add links to MDN for x-forwarded-* http headers explanation, cleanup/clarify robots.txt and crawlers section
- server: bump file upload size limit to 100MB we have reports of bookmark exports weighing +40MB - i have a 13MB one here
- server: simplify phpinfo documentation
- server: move backup and restore information to dedicated page
- docker: move all docker docs to Docker.md, simplify/ docker setup, add docker-compose.yml example, replace docker-101 with docker cheatsheet
- troubleshooting: move all troubleshooting documentation to troubleshooting.md

**Usage:**

- index: add getting started section on index page
- features/usage: move all usage-related documentation to usage.md, add links from the main feature list to corresponding usage docs, clarify/reword features list
- shaarli configuration: add note about configuring from web interface

**Removed:**

- remove obsolete/orphan images
- remove obsolete shaarchiver example
- remove outdated "decode datastore content" snippet

**Development:**

- development: move development-related docs (static analysis, CI, unit tests, 3rd party libs, link structure/directory, guidelines, security....) to dev/ directory
- development: Merge several pages to development.md
- **Breaking change?:** remove mentions of 'stable' branch, switch to new branch/release model (master=latest commit, release=latest tag)
- **Breaking change?:** refer to base sharing unit as "Shaare" everywhere (TODO: reflect changes in the code?) doc: update featues list/link to usage.md for details
- development: directory structure: add note about required file permissions
- .travis-ci.yml: add comments
- .htaccess: add comment

1 files changed, 116 insertions, 0 deletions

diff --git a/doc/md/Reverse-proxy.md b/doc/md/Reverse-proxy.md
new file mode 100644
index 00000000..2c1c601e
--- /dev/null
+++ b/doc/md/Reverse-proxy.md
@@ -0,0 +1,116 @@
+# Reverse proxy
+
+If Shaarli is hosted on a server behind a [reverse proxy](https://en.wikipedia.org/wiki/Reverse_proxy) (i.e. there is a proxy server between clients and the web server hosting Shaarli), configure it accordingly. See [Reverse proxy](Reverse-proxy.md) configuration. In this example:
+
+- The Shaarli application server exposes port `10080` to the proxy (for example docker container started with `--publish 127.0.0.1:10080:80`).
+- The Shaarli application server runs at `127.0.0.1` (container). Replace with the server's IP address if running on a different machine.
+- Shaarli's Fully Qualified Domain Name (FQDN) is `shaarli.mydomain.org`.
+- No HTTPS is setup on the application server, SSL termination is done at the reverse proxy.
+
+In your [Shaarli configuration](Shaarli-configuration) `data/config.json.php`, add the public IP of your proxy under `security.trusted_proxies`.
+
+See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues.
+
+
+## Apache
+
+```apache
+<VirtualHost *:80>
+    ServerName shaarli.mydomain.org
+    # Redirect HTTP to HTTPS
+    Redirect permanent / https://shaarli.mydomain.org
+</VirtualHost>
+
+<VirtualHost *:443>
+    ServerName shaarli.mydomain.org
+
+    SSLEngine on
+    SSLCertificateFile    /path/to/certificate
+    SSLCertificateKeyFile /path/to/private/key
+
+    LogLevel warn
+    ErrorLog  /var/log/apache2/error.log
+    CustomLog /var/log/apache2/access.log combined
+
+    # let the proxied shaarli server/container know HTTPS URLs should be served
+    RequestHeader set X-Forwarded-Proto "https"
+
+    # send the original SERVER_NAME to the proxied host
+    ProxyPreserveHost On
+    
+    # pass requests to the proxied host
+    # sets X-Forwarded-For, X-Forwarded-Host and X-Forwarded-Server headers
+    ProxyPass        / http://127.0.0.1:10080/
+    ProxyPassReverse / http://127.0.0.1:10080/
+</VirtualHost>
+```
+
+
+## HAProxy
+
+
+```conf
+global
+    [...]
+
+defaults
+    [...]
+
+frontend http-in
+    bind :80
+    redirect scheme https code 301 if !{ ssl_fc }
+    bind :443 ssl crt /path/to/cert.pem
+    default_backend shaarli
+
+backend shaarli
+    mode http
+    option http-server-close
+    option forwardfor
+    reqadd X-Forwarded-Proto: https
+    server shaarli1 127.0.0.1:10080
+```
+
+
+## Nginx
+
+
+```nginx
+http {
+    [...]
+
+    index index.html index.php;
+
+    root        /home/john/web;
+    access_log  /var/log/nginx/access.log combined;
+    error_log   /var/log/nginx/error.log;
+
+    server {
+        listen       80;
+        server_name  shaarli.mydomain.org;
+        # redirect HTTP to HTTPS
+        return       301 https://shaarli.mydomain.org$request_uri;
+    }
+
+    server {
+        listen       443 ssl http2;
+        server_name  shaarli.mydomain.org;
+
+        ssl_certificate       /path/to/certificate
+        ssl_certificate_key   /path/to/private/key
+
+        location / {
+            proxy_set_header  X-Real-IP         $remote_addr;
+            proxy_set_header  X-Forwarded-For   $proxy_add_x_forwarded_for;
+            proxy_set_header  X-Forwarded-Proto $scheme;
+            proxy_set_header  X-Forwarded-Host  $host;
+
+            # pass requests to the proxied host
+            proxy_pass             http://localhost:10080/;
+            proxy_set_header Host  $host;
+            proxy_connect_timeout  30s;
+            proxy_read_timeout     120s;
+        }
+    }
+}
+```
+