From 91a21c272960889afd4eaa431a3d29b7785b6efc Mon Sep 17 00:00:00 2001 From: nodiscc Date: Sat, 16 May 2020 12:54:51 +0200 Subject: **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 --- doc/md/Reverse-proxy.md | 116 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 116 insertions(+) create mode 100644 doc/md/Reverse-proxy.md (limited to 'doc/md/Reverse-proxy.md') 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 + + ServerName shaarli.mydomain.org + # Redirect HTTP to HTTPS + Redirect permanent / https://shaarli.mydomain.org + + + + 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/ + +``` + + +## 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; + } + } +} +``` + -- cgit v1.2.3 From 02117f7ea35d719351a99cd4f1c339b2ad4ef266 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Sat, 15 Aug 2020 20:03:43 +0200 Subject: doc: reverse proxy: update HTTP->HTTPS redirect configuration, remove logging options --- doc/md/Reverse-proxy.md | 17 +++++++++++------ 1 file changed, 11 insertions(+), 6 deletions(-) (limited to 'doc/md/Reverse-proxy.md') diff --git a/doc/md/Reverse-proxy.md b/doc/md/Reverse-proxy.md index 2c1c601e..77e4a04d 100644 --- a/doc/md/Reverse-proxy.md +++ b/doc/md/Reverse-proxy.md @@ -17,8 +17,17 @@ See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%9 ```apache ServerName shaarli.mydomain.org - # Redirect HTTP to HTTPS - Redirect permanent / https://shaarli.mydomain.org + DocumentRoot /var/www/shaarli.mydomain.org/ + + # Redirect HTTP requests to HTTPS, except Let's Encrypt ACME challenge requests + RewriteEngine on + RewriteRule ^.well-known/acme-challenge/ - [L] + RewriteCond %{HTTP_HOST} =shaarli.mydomain.org + RewriteRule ^ https://shaarli.mydomain.org%{REQUEST_URI} [END,NE,R=permanent] + # If you are using mod_md, use this instead + #MDCertificateAgreement accepted + #MDContactEmail admin@shaarli.mydomain.org + #MDPrivateKeys RSA 4096 @@ -28,10 +37,6 @@ See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%9 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" -- cgit v1.2.3 From f682f1b899641cde2617e6c2185d439b91d4338f Mon Sep 17 00:00:00 2001 From: nodiscc Date: Sun, 16 Aug 2020 20:12:45 +0200 Subject: doc: serve configuration/reverse proxy: fix apache mod_md configuration, move reference links to their respective sections, shorten --- doc/md/Reverse-proxy.md | 35 ++++++++++++++++++++++++++++------- 1 file changed, 28 insertions(+), 7 deletions(-) (limited to 'doc/md/Reverse-proxy.md') diff --git a/doc/md/Reverse-proxy.md b/doc/md/Reverse-proxy.md index 77e4a04d..1c55430f 100644 --- a/doc/md/Reverse-proxy.md +++ b/doc/md/Reverse-proxy.md @@ -19,23 +19,38 @@ See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%9 ServerName shaarli.mydomain.org DocumentRoot /var/www/shaarli.mydomain.org/ + # For SSL/TLS certificates acquired with certbot or self-signed certificates # Redirect HTTP requests to HTTPS, except Let's Encrypt ACME challenge requests RewriteEngine on RewriteRule ^.well-known/acme-challenge/ - [L] RewriteCond %{HTTP_HOST} =shaarli.mydomain.org RewriteRule ^ https://shaarli.mydomain.org%{REQUEST_URI} [END,NE,R=permanent] - # If you are using mod_md, use this instead - #MDCertificateAgreement accepted - #MDContactEmail admin@shaarli.mydomain.org - #MDPrivateKeys RSA 4096 +# SSL/TLS configuration for Let's Encrypt certificates managed with mod_md +#MDomain shaarli.mydomain.org +#MDCertificateAgreement accepted +#MDContactEmail admin@shaarli.mydomain.org +#MDPrivateKeys RSA 4096 + ServerName shaarli.mydomain.org - SSLEngine on - SSLCertificateFile /path/to/certificate - SSLCertificateKeyFile /path/to/private/key + # SSL/TLS configuration for Let's Encrypt certificates acquired with certbot standalone + SSLEngine on + SSLCertificateFile /etc/letsencrypt/live/shaarli.mydomain.org/fullchain.pem + SSLCertificateKeyFile /etc/letsencrypt/live/shaarli.mydomain.org/privkey.pem + # Let's Encrypt settings from https://github.com/certbot/certbot/blob/master/certbot-apache/certbot_apache/_internal/tls_configs/current-options-ssl-apache.conf + SSLProtocol all -SSLv2 -SSLv3 -TLSv1 -TLSv1.1 + SSLCipherSuite ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384 + SSLHonorCipherOrder off + SSLSessionTickets off + SSLOptions +StrictRequire + + # SSL/TLS configuration for self-signed certificates + #SSLEngine on + #SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem + #SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key # let the proxied shaarli server/container know HTTPS URLs should be served RequestHeader set X-Forwarded-Proto "https" @@ -75,6 +90,7 @@ backend shaarli server shaarli1 127.0.0.1:10080 ``` +- [HAProxy documentation](https://cbonte.github.io/haproxy-dconv/) ## Nginx @@ -119,3 +135,8 @@ http { } ``` +## References + +- [`X-Forwarded-Proto`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto) +- [`X-Forwarded-Host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host) +- [`X-Forwarded-For`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For) -- cgit v1.2.3 From 61f0c4b679f49953fa7147772354658a117a54e7 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Mon, 24 Aug 2020 21:32:44 +0200 Subject: doc: apache config: remove useless documentroot directive in HTTP-only virtualhost (only used for redirects) --- doc/md/Reverse-proxy.md | 1 - 1 file changed, 1 deletion(-) (limited to 'doc/md/Reverse-proxy.md') diff --git a/doc/md/Reverse-proxy.md b/doc/md/Reverse-proxy.md index 1c55430f..b7e347d5 100644 --- a/doc/md/Reverse-proxy.md +++ b/doc/md/Reverse-proxy.md @@ -17,7 +17,6 @@ See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%9 ```apache ServerName shaarli.mydomain.org - DocumentRoot /var/www/shaarli.mydomain.org/ # For SSL/TLS certificates acquired with certbot or self-signed certificates # Redirect HTTP requests to HTTPS, except Let's Encrypt ACME challenge requests -- cgit v1.2.3