From 54b065c253ce650344004ef629a6cab1404fdd2b Mon Sep 17 00:00:00 2001 From: rfolo9li <50079896+rfolo9li@users.noreply.github.com> Date: Sat, 9 Nov 2019 15:24:10 +0100 Subject: Added php-json as required PHP module Without php-json the installation stops with a white screen and the following error: > 09-Nov-2019 14:05:46 UTC] PHP Fatal error: Uncaught Error: Call to undefined function Shaarli\Config\json_encode() in /var/www/html/shaarli/application/config/ConfigJson.php:48 > Stack trace: > #0 /var/www/html/shaarli/application/config/ConfigManager.php(239): Shaarli\Config\ConfigJson->write('data/config.jso...', Array) > #1 /var/www/html/shaarli/index.php(1835): Shaarli\Config\ConfigManager->write(false) > #2 /var/www/html/shaarli/index.php(178): install(Object(Shaarli\Config\ConfigManager), Object(Shaarli\Security\SessionManager), Object(Shaarli\Security\LoginManager)) > #3 {main} > thrown in /var/www/html/shaarli/application/config/ConfigJson.php on line 48 Tested with Shaarli 0.10.4 on CentOS 8 with Httpd 2.4.37 and PHP 7.2.11. --- doc/md/Server-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 88eed8e6..b9ac01cb 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -28,12 +28,12 @@ Version | Status | Shaarli compatibility Extension | Required? | Usage ---|:---:|--- [`openssl`](http://php.net/manual/en/book.openssl.php) | All | OpenSSL, HTTPS +[`php-json`](http://php.net/manual/en/book.json.php) | required | ? [`php-mbstring`](http://php.net/manual/en/book.mbstring.php) | CentOS, Fedora, RHEL, Windows, some hosting providers | multibyte (Unicode) string support [`php-gd`](http://php.net/manual/en/book.image.php) | optional | required to use thumbnails [`php-intl`](http://php.net/manual/en/book.intl.php) | optional | localized text sorting (e.g. `e->è->f`) [`php-curl`](http://php.net/manual/en/book.curl.php) | optional | using cURL for fetching webpages and thumbnails in a more robust way [`php-gettext`](http://php.net/manual/en/book.gettext.php) | optional | Use the translation system in gettext mode (faster) - -------------------------------------------------------------------------------- ### SSL/TLS configuration -- cgit v1.2.3 From 3575fe5bcf8910afad5cc82ed68f3d442bab1a88 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Sat, 9 Nov 2019 15:40:53 +0000 Subject: doc: add explanation of php-json requirement --- doc/md/Server-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index b9ac01cb..bd293c37 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -28,7 +28,7 @@ Version | Status | Shaarli compatibility Extension | Required? | Usage ---|:---:|--- [`openssl`](http://php.net/manual/en/book.openssl.php) | All | OpenSSL, HTTPS -[`php-json`](http://php.net/manual/en/book.json.php) | required | ? +[`php-json`](http://php.net/manual/en/book.json.php) | required | configuration parsing [`php-mbstring`](http://php.net/manual/en/book.mbstring.php) | CentOS, Fedora, RHEL, Windows, some hosting providers | multibyte (Unicode) string support [`php-gd`](http://php.net/manual/en/book.image.php) | optional | required to use thumbnails [`php-intl`](http://php.net/manual/en/book.intl.php) | optional | localized text sorting (e.g. `e->è->f`) -- cgit v1.2.3 From 04a816f648edeaeb7d1545064b87b4b2135a43e8 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Sun, 19 Jan 2020 13:52:03 +0100 Subject: doc: fix references to php5, use new directory structure --- doc/md/Server-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index bd293c37..bc6ac980 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -187,7 +187,7 @@ http { ``` ```ini -# /etc/php5/fpm/php.ini +# /etc/php/$php_version/fpm/php.ini [...] post_max_size = 10M -- cgit v1.2.3 From 273453900afd7d118c0a369971f6c1fdbdd4f51d Mon Sep 17 00:00:00 2001 From: nodiscc Date: Mon, 9 Mar 2020 17:43:45 +0000 Subject: doc: use obvious placeholder MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Co-Authored-By: Aurélien Tamisier --- doc/md/Server-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index bc6ac980..f9ea2ed2 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -187,7 +187,7 @@ http { ``` ```ini -# /etc/php/$php_version/fpm/php.ini +# /etc/php//fpm/php.ini [...] post_max_size = 10M -- cgit v1.2.3 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/Server-configuration.md | 582 ++++++++++++++++++++--------------------- 1 file changed, 278 insertions(+), 304 deletions(-) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index f9ea2ed2..5c45942c 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -1,17 +1,29 @@ +# Server configuration -- [Prerequisites](#prerequisistes) -- [Apache](#apache) -- [Nginx](#nginx) -- [Proxies](#proxies) -- [See also](#see-also) -## Prerequisites -### Shaarli -- A web server and PHP interpreter module/service have been installed. -- You have write access to the Shaarli installation directory. -- The correct read/write permissions have been granted to the web server user and group. -- Your PHP interpreter is compatible with supported PHP versions: +## Requirements + +### Operating system and web server + +Shaarli can be hosted on dedicated/virtual servers, or shared hosting. The smallest DigitalOcean VPS (Droplet with 1 CPU, 1 GiB RAM and 25 GiB SSD) costs about $5/month and will run any Shaarli installation without problems. + +You need write access to the Shaarli installation directory - you should have received instructions from your hosting provider on how to connect to the server using SSH (or FTP for shared hosts). + +Examples in this documentation are given for [Debian](https://www.debian.org/), a GNU/Linux distribution widely used in server environments. Please adapt them to your specific Linux distribution. + +### Network and domain name + +Try to host the server in a region that is geographically close to your users. + +A domain name ([DNS record](https://opensource.com/article/17/4/introduction-domain-name-system-dns)) pointing to the server's public IP address is required to obtain a SSL/TLS certificate and setup HTTPS to secure client traffic to your Shaarli instance. + +You can obtain a domain name from a [registrar](https://en.wikipedia.org/wiki/Domain_name_registrar) ([1](https://www.ovh.co.uk/domains), [2](https://www.gandi.net/en/domain)), or from free subdomain providers ([1](https://freedns.afraid.org/)). If you don't have a domain name, please set up a private domain name ([FQDN](ttps://en.wikipedia.org/wiki/Fully_qualified_domain_name) in your clients' [hosts files](https://en.wikipedia.org/wiki/Hosts_(file)) to access the server (direct access by IP address can result in unexpected behavior). + + +### PHP + +Supported PHP versions: Version | Status | Shaarli compatibility :---:|:---:|:---: @@ -23,7 +35,7 @@ Version | Status | Shaarli compatibility 5.4 | EOL: 2015-09-14 | Yes (up to Shaarli 0.8.x) 5.3 | EOL: 2014-08-14 | Yes (up to Shaarli 0.8.x) -- The following PHP extensions are installed on the server: +Required PHP extensions: Extension | Required? | Usage ---|:---:|--- @@ -34,60 +46,108 @@ Extension | Required? | Usage [`php-intl`](http://php.net/manual/en/book.intl.php) | optional | localized text sorting (e.g. `e->è->f`) [`php-curl`](http://php.net/manual/en/book.curl.php) | optional | using cURL for fetching webpages and thumbnails in a more robust way [`php-gettext`](http://php.net/manual/en/book.gettext.php) | optional | Use the translation system in gettext mode (faster) --------------------------------------------------------------------------------- -### SSL/TLS configuration +Some [plugins](Plugins.md) may require additional configuration. + + +## SSL/TLS (HTTPS) -To setup HTTPS / SSL on your webserver (recommended), you must generate a public/private **key pair** and a **certificate**, and install, configure and activate the appropriate **webserver SSL extension**. +We recommend setting up [HTTPS](https://en.wikipedia.org/wiki/HTTPS) on your webserver for secure communication between clients and the server. -#### Let's Encrypt +For public-facing web servers this can be done using free SSL/TLS certificates from [Let's Encrypt](https://en.wikipedia.org/wiki/Let's_Encrypt), a non-profit certificate authority provididing free certificates. -[Let's Encrypt](https://en.wikipedia.org/wiki/Let%27s_Encrypt) is a certificate authority that provides free TLS/X.509 certificates via an automated process. + - [How to secure Apache with Let's Encrypt](https://www.digitalocean.com/community/tutorials/how-to-secure-apache-with-let-s-encrypt-on-debian-10) + - [How to secure Nginx with Let's Encrypt](https://www.digitalocean.com/community/tutorials/how-to-secure-nginx-with-let-s-encrypt-on-debian-10) + - [How To Use Certbot Standalone Mode to Retrieve Let's Encrypt SSL Certificates](https://www.digitalocean.com/community/tutorials/how-to-use-certbot-standalone-mode-to-retrieve-let-s-encrypt-ssl-certificates-on-debian-10). - * Install `certbot` using the appropriate method described on https://certbot.eff.org/. - -Location of the `certbot` program and template configuration files may vary depending on which installation method was used. Change the file paths below accordingly. Here is an easy way to create a signed certificate using `certbot`, it assumes `certbot` was installed through APT on a Debian-based distribution: +In short: - * Stop the apache2/nginx service. - * Run `certbot --agree-tos --standalone --preferred-challenges tls-sni --email "youremail@example.com" --domain yourdomain.example.com` - * For the Apache webserver, copy `/usr/lib/python2.7/dist-packages/certbot_apache/options-ssl-apache.conf` to `/etc/letsencrypt/options-ssl-apache.conf` (paths may vary depending on installation method) - * For Nginx: TODO - * Setup your webserver as described below - * Restart the apache2/nginx service. +```bash +# install certbot +sudo apt install certbot -#### Self-signed certificates +# stop your webserver if you already have one running +# certbot in standalone mode needs to bind to port 80 (only needed on initial generation) +sudo systemctl stop apache2 +sudo systemctl stop nginx -If you don't want to request a certificate from Let's Encrypt, or are unable to (for example, webserver on a LAN, or domain name not registered in the public DNS system), you can generate a self-signed certificate. This certificate will trigger security warnings in web browsers, unless you add it to the browser's SSL store manually. +# generate initial certificates - Let's Encrypt ACME servers must be able to access your server! +# (DNS records must be correctly pointing to it, firewall/NAT on port 80/443 must be open) +sudo certbot certonly --standalone --noninteractive --agree-tos --email "admin@shaarli.mydomain.org" -d shaarli.mydomain.org +# this will generate a private key and certificate at /etc/letsencrypt/live/shaarli.mydomain.org/{privkey,fullchain}.pem -* Apache: run `make-ssl-cert generate-default-snakeoil --force-overwrite` -* Nginx: TODO +# restart the web server +sudo systemctl start apache2 +sudo systemctl start nginx +``` + +If you don't want to rely on a certificate authority, or the server can only be accessed from your own network, you can also generate self-signed certificates. Not that this will generate security warnings in web browsers/clients trying to access Shaarli: + +- [How To Create a Self-Signed SSL Certificate for Apache](https://www.digitalocean.com/community/tutorials/how-to-create-a-self-signed-ssl-certificate-for-apache-on-debian-10) +- [How To Create a Self-Signed SSL Certificate for Nginx](https://www.digitalocean.com/community/tutorials/how-to-create-a-self-signed-ssl-certificate-for-nginx-on-debian-10) -------------------------------------------------------------------------------- -## Apache +## Examples + +The following examples assume a Debian-based operating system is installed. On other distributions you may have to adapt details such as package installation procedures, configuration file locations, and webserver username/group (`www-data` or `httpd` are common values). + +In these examples we assume the document root for your web server/virtualhost is at `/var/www/shaarli.mydomain.org/`: + +```bash +sudo mkdir -p /var/www/shaarli.mydomain.org/ +``` + +You can install Shaarli at the root of your virtualhost, or in a subdirectory as well. See [Directory structure](Directory-structure) + -Here is a basic configuration example for the Apache web server with `mod_php`. +### Apache -In `/etc/apache2/sites-available/shaarli.conf`: +```bash +# Install apache + mod_php and PHP modules +sudo apt update +sudo apt install apache2 libapache2-mod-php php-json php-mbstring php-gd php-intl php-curl php-gettext + +# Edit the virtualhost configuration file with your favorite editor +sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf +``` ```apache + + ServerName shaarli.mydomain.org + DocumentRoot /var/www/shaarli.mydomain.org/ + + # Log level. Possible values include: debug, info, notice, warn, error, crit, alert, emerg. + LogLevel warn + # Log file locations + ErrorLog /var/log/apache2/error.log + CustomLog /var/log/apache2/access.log combined + + # Redirect HTTP requests to HTTPS + RewriteEngine on + RewriteRule ^.well-known/acme-challenge/ - [L] + # except for Let's Encrypt ACME challenge requests + RewriteCond %{HTTP_HOST} =shaarli.mydomain.org + RewriteRule ^ https://shaarli.mydomain.org%{REQUEST_URI} [END,NE,R=permanent] + + - ServerName shaarli.my-domain.org - DocumentRoot /absolute/path/to/shaarli/ + ServerName shaarli.mydomain.org + DocumentRoot /var/www/shaarli.mydomain.org/ - # Logging - # Possible values include: debug, info, notice, warn, error, crit, alert, emerg. + # Log level. Possible values include: debug, info, notice, warn, error, crit, alert, emerg. LogLevel warn - ErrorLog /var/log/apache2/shaarli-error.log - CustomLog /var/log/apache2/shaarli-access.log combined + # Log file locations + ErrorLog /var/log/apache2/error.log + CustomLog /var/log/apache2/access.log combined - # Let's Encrypt SSL configuration (recommended) + # SSL/TLS configuration (for Let's Encrypt certificates) SSLEngine on - SSLCertificateFile /etc/letsencrypt/live/yourdomain.example.com/fullchain.pem - SSLCertificateKeyFile /etc/letsencrypt/live/yourdomain.example.com/privkey.pem + SSLCertificateFile /etc/letsencrypt/live/shaarli.mydomain.org/fullchain.pem + SSLCertificateKeyFile /etc/letsencrypt/live/shaarli.mydomain.org/privkey.pem Include /etc/letsencrypt/options-ssl-apache.conf - # Self-signed SSL cert configuration + # 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 @@ -98,345 +158,259 @@ In `/etc/apache2/sites-available/shaarli.conf`: #php_value error_reporting 2147483647 #php_value error_log /var/log/apache2/shaarli-php-error.log - - #Required for .htaccess support + + # Required for .htaccess support AllowOverride All Order allow,deny Allow from all - - Options Indexes FollowSymLinks MultiViews #TODO is Indexes/Multiviews required? - - # Optional - required for playvideos plugin - #Header set Content-Security-Policy "script-src 'self' 'unsafe-inline' https://www.youtube.com https://s.ytimg.com 'unsafe-eval'" - -``` - -Enable this configuration with `sudo a2ensite shaarli` - -_Note: If you use Apache 2.2 or lower, you need [mod_version](https://httpd.apache.org/docs/current/mod/mod_version.html) to be installed and enabled._ + + # Prevent accessing dotfiles + RedirectMatch 404 ".*" + -_Note: Apache module `mod_rewrite` must be enabled to use the REST API._ + + # allow client-side caching of static files + Header set Cache-Control "max-age=2628000, public, must-revalidate, proxy-revalidate" + + # serve the Shaarli favicon from its custom location + Alias favicon.ico /var/www/shaarli.mydomain.org/images/favicon.ico -## Nginx + +``` -Here is a basic configuration example for the Nginx web server, using the [php-fpm](http://php-fpm.org) PHP FastCGI Process Manager, and Nginx's [FastCGI](https://en.wikipedia.org/wiki/FastCGI) module. +```bash +# Enable the virtualhost +sudo a2ensite shaarli - +# mod_ssl must be enabled to use TLS/SSL certificates +# https://httpd.apache.org/docs/current/mod/mod_ssl.html +sudo a2enmod ssl -### Common setup -Once Nginx and PHP-FPM are installed, we need to ensure: +# mod_rewrite must be enabled to use the REST API +# https://httpd.apache.org/docs/current/mod/mod_rewrite.html +sudo a2enmod rewrite -- Nginx and PHP-FPM are running using the _same user and group_ -- both these user and group have - - `read` permissions for Shaarli resources - - `execute` permissions for Shaarli directories _AND_ their parent directories +# mod_version must only be enabled if you use Apache 2.2 or lower +# https://httpd.apache.org/docs/current/mod/mod_version.html +# sudo a2enmod version -On a production server: +# restart the apache service +systemctl restart apache +``` -- `user:group` will likely be `http:http`, `www:www` or `www-data:www-data` -- files will be located under `/var/www`, `/var/http` or `/usr/share/nginx` +See [How to install the Apache web server](https://www.digitalocean.com/community/tutorials/how-to-install-the-apache-web-server-on-debian-10) for a complete guide. -On a development server: +### Nginx -- files may be located in a user's home directory -- in this case, make sure both Nginx and PHP-FPM are running as the local user/group! +Guide on setting up the Nginx web server: [How to install the Nginx web server](https://www.digitalocean.com/community/tutorials/how-to-install-nginx-on-debian-10) -For all following configuration examples, this user/group pair will be used: +You will also need to install the [PHP-FPM](http://php-fpm.org) interpreter as detailed [here](https://www.digitalocean.com/community/tutorials/how-to-install-linux-nginx-mariadb-php-lemp-stack-on-debian-10#step-3-%E2%80%94-installing-php-for-processing). Nginx and PHP-FPM must be running using the same user and group, here we assume the user/group to be `www-data:www-data` but this may vary depending on your Linux distribution. -- `user:group = john:users`, -which corresponds to the following service configuration: +```bash +# install nginx and php-fpm +sudo apt update +sudo apt install nginx php-fpm -```ini -; /etc/php/php-fpm.conf -user = john -group = users - -[...] -listen.owner = john -listen.group = users +# Edit the virtualhost configuration file with your favorite editor +sudo nano /etc/nginx/sites-available/shaarli.mydomain.org ``` ```nginx -# /etc/nginx/nginx.conf -user john users; +server { + listen 80; + server_name shaarli.mydomain.org; -http { - [...] + # redirect all plain HTTP requests to HTTPS + return 301 https://shaarli.mydomain.org$request_uri; } -``` -### (Optional) Increase the maximum file upload size -Some bookmark dumps generated by web browsers can be _huge_ due to the presence of Base64-encoded images and favicons, as well as extra verbosity when nesting links in (sub-)folders. +server { + listen 443 ssl; + server_name shaarli.mydomain.org; + root /var/www/shaarli.mydomain.org; -To increase upload size, you will need to modify both nginx and PHP configuration: - -```nginx -# /etc/nginx/nginx.conf - -http { - [...] - - client_max_body_size 10m; - - [...] -} -``` - -```ini -# /etc/php//fpm/php.ini - -[...] -post_max_size = 10M -[...] -upload_max_filesize = 10M -``` + # log file locations + # combined log format prepends the virtualhost/domain name to log entries + access_log /var/log/nginx/access.log combined; + error_log /var/log/nginx/error.log; -### Minimal -_WARNING: Use for development only!_ + # paths to private key and certificates for SSL/TLS + ssl_certificate /etc/ssl/shaarli.mydomain.org.crt; + ssl_certificate_key /etc/ssl/private/shaarli.mydomain.org.key; -```nginx -user john users; -worker_processes 1; -events { - worker_connections 1024; -} + # increase the maximum file upload size if needed: by default nginx limits file upload to 1MB (413 Entity Too Large error) + client_max_body_size 100m; -http { - include mime.types; - default_type application/octet-stream; - keepalive_timeout 20; - - index index.html index.php; - - server { - listen 80; - server_name localhost; - root /home/john/web; - - access_log /var/log/nginx/access.log; - error_log /var/log/nginx/error.log; - - location /shaarli/ { - try_files $uri /shaarli/index.php$is_args$args; - access_log /var/log/nginx/shaarli.access.log; - error_log /var/log/nginx/shaarli.error.log; - } - - location ~ (index)\.php$ { - try_files $uri =404; - fastcgi_split_path_info ^(.+\.php)(/.+)$; - fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock; - fastcgi_index index.php; - include fastcgi.conf; - } + # relative path to shaarli from the root of the webserver + location / { + # default index file when no file URI is requested + index index.php; + try_files $uri /index.php$is_args$args; } -} -``` -### Modular -The previous setup is sufficient for development purposes, but has several major caveats: + location ~ (index)\.php$ { + try_files $uri =404; + # slim API - split URL path into (script_filename, path_info) + fastcgi_split_path_info ^(.+\.php)(/.+)$; + # pass PHP requests to PHP-FPM + fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock; + fastcgi_index index.php; + include fastcgi.conf; + } -- every content that does not match the PHP rule will be sent to client browsers: - - dotfiles - in our case, `.htaccess` - - temporary files, e.g. Vim or Emacs files: `index.php~` -- asset / static resource caching is not optimized -- if serving several PHP sites, there will be a lot of duplication: `location /shaarli/`, `location /mysite/`, etc. + location ~ \.php$ { + # deny access to all other PHP scripts + # disable this if you host other PHP applications on the same virtualhost + deny all; + } -To solve this, we will split Nginx configuration in several parts, that will be included when needed: + location ~ /\. { + # deny access to dotfiles + deny all; + } -```nginx -# /etc/nginx/deny.conf -location ~ /\. { - # deny access to dotfiles - access_log off; - log_not_found off; - deny all; -} + location ~ ~$ { + # deny access to temp editor files, e.g. "script.php~" + deny all; + } -location ~ ~$ { - # deny access to temp editor files, e.g. "script.php~" - access_log off; - log_not_found off; - deny all; -} -``` + location = /favicon.ico { + # serve the Shaarli favicon from its custom location + alias /var/www/shaarli/images/favicon.ico; + } -```nginx -# /etc/nginx/php.conf -location ~ (index)\.php$ { - # Slim - split URL path into (script_filename, path_info) - try_files $uri =404; - fastcgi_split_path_info ^(.+\.php)(/.+)$; - - # filter and proxy PHP requests to PHP-FPM - fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock; - fastcgi_index index.php; - include fastcgi.conf; -} + # allow client-side caching of static files + location ~* \.(?:ico|css|js|gif|jpe?g|png)$ { + expires max; + add_header Cache-Control "public, must-revalidate, proxy-revalidate"; + # HTTP 1.0 compatibility + add_header Pragma public; + } -location ~ \.php$ { - # deny access to all other PHP scripts - deny all; } ``` -```nginx -# /etc/nginx/static_assets.conf -location ~* \.(?:ico|css|js|gif|jpe?g|png)$ { - expires max; - add_header Pragma public; - add_header Cache-Control "public, must-revalidate, proxy-revalidate"; -} +```bash +# enable the configuration/virtualhost +sudo ln -s /etc/nginx/sites-available/shaarli.mydomain.org /etc/nginx/sites-enabled/shaarli.mydomain.org +# reload nginx configuration +sudo systemctl reload nginx ``` -```nginx -# /etc/nginx/nginx.conf -[...] - -http { - [...] - - root /home/john/web; - access_log /var/log/nginx/access.log; - error_log /var/log/nginx/error.log; - server { - # virtual host for a first domain - listen 80; - server_name my.first.domain.org; +## Reverse proxies - location /shaarli/ { - # Slim - rewrite URLs - try_files $uri /shaarli/index.php$is_args$args; +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. - access_log /var/log/nginx/shaarli.access.log; - error_log /var/log/nginx/shaarli.error.log; - } - location = /shaarli/favicon.ico { - # serve the Shaarli favicon from its custom location - alias /var/www/shaarli/images/favicon.ico; - } - include deny.conf; - include static_assets.conf; - include php.conf; - } +## Allow import of large browser bookmarks export - server { - # virtual host for a second domain - listen 80; - server_name second.domain.com; +Web browser bookmark exports can be large due to the presence of base64-encoded images and favicons/long subfolder names. Edit the PHP configuration file. - location /minigal/ { - access_log /var/log/nginx/minigal.access.log; - error_log /var/log/nginx/minigal.error.log; - } +- Apache: `/etc/php//apache2/php.ini` +- Nginx + PHP-FPM: `/etc/php//fpm/php.ini` (in addition to `client_max_body_size` in the [Nginx configuration](#nginx)) - include deny.conf; - include static_assets.conf; - include php.conf; - } -} -``` - -### Redirect HTTP to HTTPS -Assuming you have generated a (self-signed) key and certificate, and they are -located under `/home/john/ssl/localhost.{key,crt}`, it is pretty straightforward -to set an HTTP (:80) to HTTPS (:443) redirection to force SSL/TLS usage. - -```nginx -# /etc/nginx/nginx.conf +```ini [...] +# (optional) increase the maximum file upload size: +post_max_size = 100M +[...] +# (optional) increase the maximum file upload size: +upload_max_filesize = 100M +``` -http { - [...] - - index index.html index.php; - - root /home/john/web; - access_log /var/log/nginx/access.log; - error_log /var/log/nginx/error.log; - - server { - listen 80; - server_name localhost; +To verify PHP settings currently set on the server, create a `phpinfo.php` in your webserver's document root - return 301 https://localhost$request_uri; - } +```bash +# example +echo '' | sudo tee /var/www/shaarli.mydomain.org/phpinfo.php +#give read-only access to this file to the webserver user +sudo chown www-data:root /var/www/shaarli.mydomain.org/phpinfo.php +sudo chmod 0400 /var/www/shaarli.mydomain.org/phpinfo.php +``` - server { - listen 443 ssl; - server_name localhost; +Access the file from a web browser (eg. and look at the _Loaded Configuration File_ and _Scan this dir for additional .ini files_ entries - ssl_certificate /home/john/ssl/localhost.crt; - ssl_certificate_key /home/john/ssl/localhost.key; +It is recommended to remove the `phpinfo.php` when no longer needed as it publicly discloses details about your webserver configuration. - location /shaarli/ { - # Slim - rewrite URLs - try_files $uri /index.php$is_args$args; - access_log /var/log/nginx/shaarli.access.log; - error_log /var/log/nginx/shaarli.error.log; - } +## Robots and crawlers - location = /shaarli/favicon.ico { - # serve the Shaarli favicon from its custom location - alias /var/www/shaarli/images/favicon.ico; - } +To opt-out of indexing your Shaarli instance by search engines, create a `robots.txt` file at the root of your virtualhost: - include deny.conf; - include static_assets.conf; - include php.conf; - } -} +``` +User-agent: * +Disallow: / ``` -## Proxies - -If Shaarli is served behind a proxy (i.e. there is a proxy server between clients and the web server hosting Shaarli), please refer to the proxy server documentation for proper configuration. In particular, you have to ensure that the following server variables are properly set: +By default Shaarli already disallows indexing of your local copy of the documentation by default, using `` HTML tags. Your Shaarli instance may still be indexed by various robots on the public Internet, that do not respect this header or the robots standard. -- `X-Forwarded-Proto` -- `X-Forwarded-Host` -- `X-Forwarded-For` +- [Robots exclusion standard](https://en.wikipedia.org/wiki/Robots_exclusion_standard) +- [Introduction to robots.txt](https://support.google.com/webmasters/answer/6062608?hl=en) +- [Robots meta tag, data-nosnippet, and X-Robots-Tag specifications](https://developers.google.com/search/reference/robots_meta_tag) +- [About robots.txt](http://www.robotstxt.org) +- [About the robots META tag](https://www.robotstxt.org/meta.html) -In you [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. +## Fail2ban -## Robots and crawlers +[fail2ban](http://www.fail2ban.org/wiki/index.php/Main_Page) is an intrusion prevention framework that reads server (Apache, SSH, etc.) and uses `iptables` profiles to block brute-force attempts. You need to create a filter to detect shaarli login failures in logs, and a jail configuation to configure the behavior when failed login attempts are detected: -Shaarli disallows indexing and crawling of your local documentation pages by search engines, using `` HTML tags. -Your Shaarli instance and other pages you host may still be indexed by various robots on the public Internet. -You may want to setup a robots.txt file or other crawler control mechanism on your server. -See [[1]](https://en.wikipedia.org/wiki/Robots_exclusion_standard), [[2]](https://support.google.com/webmasters/answer/6062608?hl=en) and [[3]](https://developers.google.com/search/reference/robots_meta_tag) - -## See also +```ini +# /etc/fail2ban/filter.d/shaarli-auth.conf +[INCLUDES] +before = common.conf +[Definition] +failregex = \s-\s\s-\sLogin failed for user.*$ +ignoreregex = +``` - * [Server security](Server-security.md) +```ini +# /etc/fail2ban/jail.local +[shaarli-auth] +enabled = true +port = https,http +filter = shaarli-auth +logpath = /var/www/shaarli.mydomain.org/data/log.txt +# allow 3 login attempts per IP address +# (over a period specified by findtime = in /etc/fail2ban/jail.conf) +maxretry = 3 +# permanently ban the IP address after reaching the limit +bantime = -1 +``` -#### Webservers +#### References -- [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow) +- [Apache/PHP - error log per VirtualHost - StackOverflow](http://stackoverflow.com/q/176) - [Apache - PHP: php_value vs php_admin_value and the use of php_flag explained](https://ma.ttias.be/php-php_value-vs-php_admin_value-and-the-use-of-php_flag-explained/) -- [Server-side TLS (Apache)](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache) (Mozilla) +- [Server-side TLS (Apache) - Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache) - [Nginx Beginner's guide](http://nginx.org/en/docs/beginners_guide.html) - [Nginx ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html) - [Nginx Pitfalls](http://wiki.nginx.org/Pitfalls) -- [Nginx PHP configuration examples](http://kbeezie.com/nginx-configuration-examples/) (Karl Blessing) -- [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla) +- [Nginx PHP configuration examples - Karl Blessing](http://kbeezie.com/nginx-configuration-examples/) +- [Apache 2.4 documentation](https://httpd.apache.org/docs/2.4/) +- [Apache mod_proxy](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html) +- [Apache Reverse Proxy Request Headers](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#x-headers) +- [HAProxy documentation](https://cbonte.github.io/haproxy-dconv/) +- [Nginx documentation](https://nginx.org/en/docs/) +- [`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) +- [Server-side TLS (Nginx) - Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) - [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php) - [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority) - -#### PHP - - [Travis configuration](https://github.com/shaarli/Shaarli/blob/master/.travis.yml) - [PHP: Supported versions](http://php.net/supported-versions.php) -- [PHP: Unsupported versions](http://php.net/eol.php) _(EOL - End Of Life)_ +- [PHP: Unsupported versions (EOL/End-of-life)](http://php.net/eol.php) - [PHP 7 Changelog](http://php.net/ChangeLog-7.php) - [PHP 5 Changelog](http://php.net/ChangeLog-5.php) - [PHP: Bugs](https://bugs.php.net/) +- [Transport Layer Security](https://en.wikipedia.org/wiki/Transport_Layer_Security) +- Hosting providers: [DigitalOcean](https://www.digitalocean.com/) ([1](https://www.digitalocean.com/docs/droplets/overview/), [2](https://www.digitalocean.com/pricing/), [3](https://www.digitalocean.com/docs/droplets/how-to/create/), [How to Add SSH Keys to Droplets](https://www.digitalocean.com/docs/droplets/how-to/add-ssh-keys/), [4](https://www.digitalocean.com/community/tutorials/initial-server-setup-with-debian-8), [5](https://www.digitalocean.com/community/tutorials/an-introduction-to-securing-your-linux-vps)), [Gandi](https://www.gandi.net/en), [OVH](https://www.ovh.co.uk/), [RackSpace](https://www.rackspace.com/), etc. + + -- cgit v1.2.3 From a32e6665d0516f0ee1958be39ed2c8f0a0389e50 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Mon, 18 May 2020 21:04:55 +0200 Subject: formatting/emphasis --- doc/md/Server-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 5c45942c..1c14e1a6 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -16,7 +16,7 @@ Examples in this documentation are given for [Debian](https://www.debian.org/), Try to host the server in a region that is geographically close to your users. -A domain name ([DNS record](https://opensource.com/article/17/4/introduction-domain-name-system-dns)) pointing to the server's public IP address is required to obtain a SSL/TLS certificate and setup HTTPS to secure client traffic to your Shaarli instance. +A **domain name** ([DNS record](https://opensource.com/article/17/4/introduction-domain-name-system-dns)) pointing to the server's public IP address is required to obtain a SSL/TLS certificate and setup HTTPS to secure client traffic to your Shaarli instance. You can obtain a domain name from a [registrar](https://en.wikipedia.org/wiki/Domain_name_registrar) ([1](https://www.ovh.co.uk/domains), [2](https://www.gandi.net/en/domain)), or from free subdomain providers ([1](https://freedns.afraid.org/)). If you don't have a domain name, please set up a private domain name ([FQDN](ttps://en.wikipedia.org/wiki/Fully_qualified_domain_name) in your clients' [hosts files](https://en.wikipedia.org/wiki/Hosts_(file)) to access the server (direct access by IP address can result in unexpected behavior). -- cgit v1.2.3 From 6384447d1d9ff8f2f58a0c6a7e901ec95691bc87 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Mon, 18 May 2020 21:05:49 +0200 Subject: fix markdown syntax --- doc/md/Server-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 1c14e1a6..89225b4f 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -18,7 +18,7 @@ Try to host the server in a region that is geographically close to your users. A **domain name** ([DNS record](https://opensource.com/article/17/4/introduction-domain-name-system-dns)) pointing to the server's public IP address is required to obtain a SSL/TLS certificate and setup HTTPS to secure client traffic to your Shaarli instance. -You can obtain a domain name from a [registrar](https://en.wikipedia.org/wiki/Domain_name_registrar) ([1](https://www.ovh.co.uk/domains), [2](https://www.gandi.net/en/domain)), or from free subdomain providers ([1](https://freedns.afraid.org/)). If you don't have a domain name, please set up a private domain name ([FQDN](ttps://en.wikipedia.org/wiki/Fully_qualified_domain_name) in your clients' [hosts files](https://en.wikipedia.org/wiki/Hosts_(file)) to access the server (direct access by IP address can result in unexpected behavior). +You can obtain a domain name from a [registrar](https://en.wikipedia.org/wiki/Domain_name_registrar) ([1](https://www.ovh.co.uk/domains), [2](https://www.gandi.net/en/domain)), or from free subdomain providers ([1](https://freedns.afraid.org/)). If you don't have a domain name, please set up a private domain name ([FQDN](ttps://en.wikipedia.org/wiki/Fully_qualified_domain_name)) in your clients' [hosts files](https://en.wikipedia.org/wiki/Hosts_(file)) to access the server (direct access by IP address can result in unexpected behavior). ### PHP -- cgit v1.2.3 From 41b93897f3acdde949eaacb63e82651a2aaa0a92 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Mon, 18 May 2020 21:06:14 +0200 Subject: server-configuration: move firewall/NAT requirements to Network section --- doc/md/Server-configuration.md | 4 ++++ 1 file changed, 4 insertions(+) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 89225b4f..3e5139e2 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -20,6 +20,10 @@ A **domain name** ([DNS record](https://opensource.com/article/17/4/introduction You can obtain a domain name from a [registrar](https://en.wikipedia.org/wiki/Domain_name_registrar) ([1](https://www.ovh.co.uk/domains), [2](https://www.gandi.net/en/domain)), or from free subdomain providers ([1](https://freedns.afraid.org/)). If you don't have a domain name, please set up a private domain name ([FQDN](ttps://en.wikipedia.org/wiki/Fully_qualified_domain_name)) in your clients' [hosts files](https://en.wikipedia.org/wiki/Hosts_(file)) to access the server (direct access by IP address can result in unexpected behavior). +Setup a **firewall** (using `iptables`, [ufw](https://www.digitalocean.com/community/tutorials/how-to-set-up-a-firewall-with-ufw-on-debian-10), [fireHOL](https://firehol.org/) or any frontend of your choice) to deny all incoming traffic except `tcp/80` and `tcp/443`, which are needed to access the web server (and any other posrts you might need, like SSH). If the server is in a private network behind a NAT, ensure these **ports are forwarded** to the server. + +Shaarli makes outbound HTTP/HTTPS connections to websites you bookmark to fetch page information (title, thumbnails), the server must then have access to the Internet as well, and a working DNS resolver. + ### PHP -- cgit v1.2.3 From 30255b794ab3ddfaf2e813d173b445800102d748 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Mon, 18 May 2020 21:06:45 +0200 Subject: doc: php compatibility: add php 7.3 --- doc/md/Server-configuration.md | 1 + 1 file changed, 1 insertion(+) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 3e5139e2..b4dfc53d 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -31,6 +31,7 @@ Supported PHP versions: Version | Status | Shaarli compatibility :---:|:---:|:---: +7.3 | Supported | Yes 7.2 | Supported | Yes 7.1 | Supported | Yes 7.0 | EOL: 2018-12-03 | Yes (up to Shaarli 0.10.x) -- cgit v1.2.3 From c84d1430472bac5c8f437f41b8e845b808acfdd2 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Mon, 18 May 2020 21:07:32 +0200 Subject: apache: fix let's encrypt configuration , copy it directly from reference file including options-ssl-apache.conf requires python3-certbot-apache which pulls a lot of dependencies --- doc/md/Server-configuration.md | 9 +++++++-- 1 file changed, 7 insertions(+), 2 deletions(-) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index b4dfc53d..70ae087a 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -77,7 +77,6 @@ sudo systemctl stop apache2 sudo systemctl stop nginx # generate initial certificates - Let's Encrypt ACME servers must be able to access your server! -# (DNS records must be correctly pointing to it, firewall/NAT on port 80/443 must be open) sudo certbot certonly --standalone --noninteractive --agree-tos --email "admin@shaarli.mydomain.org" -d shaarli.mydomain.org # this will generate a private key and certificate at /etc/letsencrypt/live/shaarli.mydomain.org/{privkey,fullchain}.pem @@ -150,7 +149,13 @@ sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf SSLEngine on SSLCertificateFile /etc/letsencrypt/live/shaarli.mydomain.org/fullchain.pem SSLCertificateKeyFile /etc/letsencrypt/live/shaarli.mydomain.org/privkey.pem - Include /etc/letsencrypt/options-ssl-apache.conf + + # 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 -- cgit v1.2.3 From 538fb324a8a8d57b7b06e30dfe2310137918f844 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Mon, 18 May 2020 21:08:36 +0200 Subject: doc: nginx: reorder --- doc/md/Server-configuration.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 70ae087a..2bb403e5 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -215,9 +215,7 @@ See [How to install the Apache web server](https://www.digitalocean.com/communit ### Nginx -Guide on setting up the Nginx web server: [How to install the Nginx web server](https://www.digitalocean.com/community/tutorials/how-to-install-nginx-on-debian-10) - -You will also need to install the [PHP-FPM](http://php-fpm.org) interpreter as detailed [here](https://www.digitalocean.com/community/tutorials/how-to-install-linux-nginx-mariadb-php-lemp-stack-on-debian-10#step-3-%E2%80%94-installing-php-for-processing). Nginx and PHP-FPM must be running using the same user and group, here we assume the user/group to be `www-data:www-data` but this may vary depending on your Linux distribution. +This examples uses nginx and the [PHP-FPM](https://www.digitalocean.com/community/tutorials/how-to-install-linux-nginx-mariadb-php-lemp-stack-on-debian-10#step-3-%E2%80%94-installing-php-for-processing) PHP interpreter. Nginx and PHP-FPM must be running using the same user and group, here we assume the user/group to be `www-data:www-data`. ```bash @@ -311,6 +309,8 @@ sudo ln -s /etc/nginx/sites-available/shaarli.mydomain.org /etc/nginx/sites-enab sudo systemctl reload nginx ``` +See [How to install the Nginx web server](https://www.digitalocean.com/community/tutorials/how-to-install-nginx-on-debian-10) for a complete guide. + ## Reverse proxies -- cgit v1.2.3 From 778add2c9cc858bcc1aa8180620bd46590b84e15 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Mon, 18 May 2020 21:08:51 +0200 Subject: doc: nginx: add let's encrypt ssl configuration --- doc/md/Server-configuration.md | 8 ++++++++ 1 file changed, 8 insertions(+) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 2bb403e5..6e21de91 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -250,6 +250,14 @@ server { ssl_certificate /etc/ssl/shaarli.mydomain.org.crt; ssl_certificate_key /etc/ssl/private/shaarli.mydomain.org.key; + # Let's Encrypt SSL settings from https://github.com/certbot/certbot/blob/master/certbot-nginx/certbot_nginx/_internal/tls_configs/options-ssl-nginx.conf + ssl_session_cache shared:le_nginx_SSL:10m; + ssl_session_timeout 1440m; + ssl_session_tickets off; + ssl_protocols TLSv1.2 TLSv1.3; + ssl_prefer_server_ciphers off; + ssl_ciphers "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"; + # increase the maximum file upload size if needed: by default nginx limits file upload to 1MB (413 Entity Too Large error) client_max_body_size 100m; -- cgit v1.2.3 From dfe14f264bf97e412794e386183189cd7cbd765a Mon Sep 17 00:00:00 2001 From: nodiscc Date: Mon, 1 Jun 2020 20:10:38 +0200 Subject: doc: server configuration: php requirements: add php-simplexml ref. https://github.com/shaarli/Shaarli/pull/1476 --- doc/md/Server-configuration.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 6e21de91..3c207acc 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -44,8 +44,9 @@ Required PHP extensions: Extension | Required? | Usage ---|:---:|--- -[`openssl`](http://php.net/manual/en/book.openssl.php) | All | OpenSSL, HTTPS +[`openssl`](http://php.net/manual/en/book.openssl.php) | requires | OpenSSL, HTTPS [`php-json`](http://php.net/manual/en/book.json.php) | required | configuration parsing +[`php-simplexml`](https://www.php.net/manual/en/book.simplexml.php) | required | REST API (Slim framework) [`php-mbstring`](http://php.net/manual/en/book.mbstring.php) | CentOS, Fedora, RHEL, Windows, some hosting providers | multibyte (Unicode) string support [`php-gd`](http://php.net/manual/en/book.image.php) | optional | required to use thumbnails [`php-intl`](http://php.net/manual/en/book.intl.php) | optional | localized text sorting (e.g. `e->è->f`) -- cgit v1.2.3 From e0fe33f90ba0bfedc50ba79982833e10c7e6c4a4 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Sat, 15 Aug 2020 19:37:24 +0200 Subject: doc: server configuration: add note on required firewall/NAT for Let's Encrypt certificates --- doc/md/Server-configuration.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 3c207acc..f14be7f3 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -77,7 +77,8 @@ sudo apt install certbot sudo systemctl stop apache2 sudo systemctl stop nginx -# generate initial certificates - Let's Encrypt ACME servers must be able to access your server! +# generate initial certificates +# Let's Encrypt ACME servers must be able to access your server! port forwarding and firewall must be properly configured sudo certbot certonly --standalone --noninteractive --agree-tos --email "admin@shaarli.mydomain.org" -d shaarli.mydomain.org # this will generate a private key and certificate at /etc/letsencrypt/live/shaarli.mydomain.org/{privkey,fullchain}.pem -- cgit v1.2.3 From 1aeefe108861e5e01c6a1067935b00d24e606dd5 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Sat, 15 Aug 2020 19:38:18 +0200 Subject: doc: server configuration: formatting/add comment --- doc/md/Server-configuration.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index f14be7f3..4164980b 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -96,11 +96,10 @@ If you don't want to rely on a certificate authority, or the server can only be ## Examples -The following examples assume a Debian-based operating system is installed. On other distributions you may have to adapt details such as package installation procedures, configuration file locations, and webserver username/group (`www-data` or `httpd` are common values). - -In these examples we assume the document root for your web server/virtualhost is at `/var/www/shaarli.mydomain.org/`: +The following examples assume a Debian-based operating system is installed. On other distributions you may have to adapt details such as package installation procedures, configuration file locations, and webserver username/group (`www-data` or `httpd` are common values). In these examples we assume the document root for your web server/virtualhost is at `/var/www/shaarli.mydomain.org/`: ```bash +# create the document root sudo mkdir -p /var/www/shaarli.mydomain.org/ ``` -- cgit v1.2.3 From 6c4cae378e87b43a793cd91a87dc1952106107f7 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Sat, 15 Aug 2020 19:39:28 +0200 Subject: doc: server configuration: remove apache logging options see https://github.com/nodiscc/xsrv/blob/master/roles/apache/templates/etc_apache2_conf-available_logging.conf.j2 for an example server-wide logging configuration --- doc/md/Server-configuration.md | 12 ------------ 1 file changed, 12 deletions(-) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 4164980b..2ee15ef6 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -122,12 +122,6 @@ sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf ServerName shaarli.mydomain.org DocumentRoot /var/www/shaarli.mydomain.org/ - # Log level. Possible values include: debug, info, notice, warn, error, crit, alert, emerg. - LogLevel warn - # Log file locations - ErrorLog /var/log/apache2/error.log - CustomLog /var/log/apache2/access.log combined - # Redirect HTTP requests to HTTPS RewriteEngine on RewriteRule ^.well-known/acme-challenge/ - [L] @@ -140,12 +134,6 @@ sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf ServerName shaarli.mydomain.org DocumentRoot /var/www/shaarli.mydomain.org/ - # Log level. Possible values include: debug, info, notice, warn, error, crit, alert, emerg. - LogLevel warn - # Log file locations - ErrorLog /var/log/apache2/error.log - CustomLog /var/log/apache2/access.log combined - # SSL/TLS configuration (for Let's Encrypt certificates) SSLEngine on SSLCertificateFile /etc/letsencrypt/live/shaarli.mydomain.org/fullchain.pem -- cgit v1.2.3 From 78f319fa6b9a2824bdc8becc88c365455b1a1aa6 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Sat, 15 Aug 2020 19:40:59 +0200 Subject: doc: troubleshooting: add procedure to clear shaarli caches --- doc/md/Server-configuration.md | 1 + 1 file changed, 1 insertion(+) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 2ee15ef6..281abb0d 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -202,6 +202,7 @@ systemctl restart apache See [How to install the Apache web server](https://www.digitalocean.com/community/tutorials/how-to-install-the-apache-web-server-on-debian-10) for a complete guide. + ### Nginx This examples uses nginx and the [PHP-FPM](https://www.digitalocean.com/community/tutorials/how-to-install-linux-nginx-mariadb-php-lemp-stack-on-debian-10#step-3-%E2%80%94-installing-php-for-processing) PHP interpreter. Nginx and PHP-FPM must be running using the same user and group, here we assume the user/group to be `www-data:www-data`. -- cgit v1.2.3 From ecdae2237f85b93bb3db436cf405a88c945e2a7a Mon Sep 17 00:00:00 2001 From: nodiscc Date: Sat, 15 Aug 2020 19:47:42 +0200 Subject: doc: server configuration: update apache configuration 2.2 -> 2.4 https://httpd.apache.org/docs/current/upgrading.html --- doc/md/Server-configuration.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 281abb0d..c22b7d9c 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -160,8 +160,7 @@ sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf # Required for .htaccess support AllowOverride All - Order allow,deny - Allow from all + Require all granted -- cgit v1.2.3 From 38d66e1a40c20678e34408a069a615928d2c244c Mon Sep 17 00:00:00 2001 From: nodiscc Date: Sat, 15 Aug 2020 19:54:18 +0200 Subject: doc: server configuration: apache: add note about mod_md --- doc/md/Server-configuration.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index c22b7d9c..d32cc786 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -60,6 +60,8 @@ Some [plugins](Plugins.md) may require additional configuration. We recommend setting up [HTTPS](https://en.wikipedia.org/wiki/HTTPS) on your webserver for secure communication between clients and the server. +### Let's Encrypt + For public-facing web servers this can be done using free SSL/TLS certificates from [Let's Encrypt](https://en.wikipedia.org/wiki/Let's_Encrypt), a non-profit certificate authority provididing free certificates. - [How to secure Apache with Let's Encrypt](https://www.digitalocean.com/community/tutorials/how-to-secure-apache-with-let-s-encrypt-on-debian-10) @@ -87,6 +89,10 @@ sudo systemctl start apache2 sudo systemctl start nginx ``` +On apache `2.4.43+`, you can also delegate LE certificate management to [mod_md](https://httpd.apache.org/docs/2.4/mod/mod_md.html) [[1](https://www.cyberciti.biz/faq/how-to-secure-apache-with-mod_md-lets-encrypt-on-ubuntu-20-04-lts/)] in which case you don't need certbot and manual SSL configuration in virtualhosts. + +### Self-signed + If you don't want to rely on a certificate authority, or the server can only be accessed from your own network, you can also generate self-signed certificates. Not that this will generate security warnings in web browsers/clients trying to access Shaarli: - [How To Create a Self-Signed SSL Certificate for Apache](https://www.digitalocean.com/community/tutorials/how-to-create-a-self-signed-ssl-certificate-for-apache-on-debian-10) @@ -135,10 +141,10 @@ sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf DocumentRoot /var/www/shaarli.mydomain.org/ # SSL/TLS configuration (for Let's Encrypt certificates) + # If certificates were acquired from 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 -- cgit v1.2.3 From f3ab2616314834508c36b5e97406572ecd9af7a4 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Sat, 15 Aug 2020 19:59:34 +0200 Subject: doc: apache: add example configuration for mod_md --- doc/md/Server-configuration.md | 13 +++++++++---- 1 file changed, 9 insertions(+), 4 deletions(-) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index d32cc786..73e23886 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -128,20 +128,22 @@ sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf ServerName shaarli.mydomain.org DocumentRoot /var/www/shaarli.mydomain.org/ - # Redirect HTTP requests to HTTPS + # Redirect HTTP requests to HTTPS, except Let's Encrypt ACME challenge requests RewriteEngine on RewriteRule ^.well-known/acme-challenge/ - [L] - # except for Let's Encrypt ACME challenge requests 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 ServerName shaarli.mydomain.org DocumentRoot /var/www/shaarli.mydomain.org/ - # SSL/TLS configuration (for Let's Encrypt certificates) - # If certificates were acquired from certbot standalone + # 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 @@ -152,6 +154,9 @@ sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf SSLSessionTickets off SSLOptions +StrictRequire + # SSL/TLS configuration for Let's Encrypt certificates acquired with mod_md + #MDomain shaarli.mydomain.org + # SSL/TLS configuration (for self-signed certificates) #SSLEngine on #SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem -- cgit v1.2.3 From e21df1e7296cc7ed33e28989b86edebe7bc85b54 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Sat, 15 Aug 2020 20:00:55 +0200 Subject: doc: fail2Ban: add note about restarting fail2ban --- doc/md/Server-configuration.md | 2 ++ 1 file changed, 2 insertions(+) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 73e23886..c63e296e 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -402,6 +402,8 @@ maxretry = 3 bantime = -1 ``` +Then restart the service: `sudo systemctl restart fail2ban` + #### References - [Apache/PHP - error log per VirtualHost - StackOverflow](http://stackoverflow.com/q/176) -- 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/Server-configuration.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index c63e296e..c1cf4310 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -1,7 +1,5 @@ # Server configuration - - ## Requirements ### Operating system and web server @@ -24,6 +22,7 @@ Setup a **firewall** (using `iptables`, [ufw](https://www.digitalocean.com/commu Shaarli makes outbound HTTP/HTTPS connections to websites you bookmark to fetch page information (title, thumbnails), the server must then have access to the Internet as well, and a working DNS resolver. +-------------------------------------------------------------------------------- ### PHP -- cgit v1.2.3 From 9417f1337eb518bd303017369fc66a074c1963bc Mon Sep 17 00:00:00 2001 From: nodiscc Date: Sun, 16 Aug 2020 19:14:40 +0200 Subject: doc: server configuration: add asciicast of server configuration procedure (asciinema) --- doc/md/Server-configuration.md | 7 +++++++ 1 file changed, 7 insertions(+) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index c1cf4310..7da7995d 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -22,6 +22,13 @@ Setup a **firewall** (using `iptables`, [ufw](https://www.digitalocean.com/commu Shaarli makes outbound HTTP/HTTPS connections to websites you bookmark to fetch page information (title, thumbnails), the server must then have access to the Internet as well, and a working DNS resolver. + +### Screencast + +Here is a screencast of the installation procedure + +[![asciicast](https://asciinema.org/a/z3RXxcJIRgWk0jM2ws6EnUFgO.svg)](https://asciinema.org/a/z3RXxcJIRgWk0jM2ws6EnUFgO) + -------------------------------------------------------------------------------- ### PHP -- cgit v1.2.3 From d8847936d4fb3faa698bee1acabf99eb7f5268ed Mon Sep 17 00:00:00 2001 From: nodiscc Date: Sun, 16 Aug 2020 19:15:11 +0200 Subject: doc: server configuration: add reminder to change the example domain name --- doc/md/Server-configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 7da7995d..bb488ef0 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -111,7 +111,7 @@ If you don't want to rely on a certificate authority, or the server can only be The following examples assume a Debian-based operating system is installed. On other distributions you may have to adapt details such as package installation procedures, configuration file locations, and webserver username/group (`www-data` or `httpd` are common values). In these examples we assume the document root for your web server/virtualhost is at `/var/www/shaarli.mydomain.org/`: ```bash -# create the document root +# create the document root (replace with your own domain name) sudo mkdir -p /var/www/shaarli.mydomain.org/ ``` @@ -125,7 +125,7 @@ You can install Shaarli at the root of your virtualhost, or in a subdirectory as sudo apt update sudo apt install apache2 libapache2-mod-php php-json php-mbstring php-gd php-intl php-curl php-gettext -# Edit the virtualhost configuration file with your favorite editor +# Edit the virtualhost configuration file with your favorite editor (replace the example domain name) sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf ``` -- cgit v1.2.3 From 5eece37b0aaa8563d6fdde394b2e828bec61b6f5 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Sun, 16 Aug 2020 19:15:56 +0200 Subject: doc: server configuration: fix apache site config file name --- doc/md/Server-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index bb488ef0..89398b44 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -198,7 +198,7 @@ sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf ```bash # Enable the virtualhost -sudo a2ensite shaarli +sudo a2ensite shaarli.mydomain.org # mod_ssl must be enabled to use TLS/SSL certificates # https://httpd.apache.org/docs/current/mod/mod_ssl.html -- cgit v1.2.3 From 19489e92d7dee3ec594432173071ddcddd79aa03 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Sun, 16 Aug 2020 19:16:01 +0200 Subject: doc: server configuration: enable mod_headers --- doc/md/Server-configuration.md | 3 +++ 1 file changed, 3 insertions(+) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 89398b44..8eeb10bd 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -208,6 +208,9 @@ sudo a2enmod ssl # https://httpd.apache.org/docs/current/mod/mod_rewrite.html sudo a2enmod rewrite +# mod_headers must be enabled to set custom headers from the server config +sudo a2enmod headers + # mod_version must only be enabled if you use Apache 2.2 or lower # https://httpd.apache.org/docs/current/mod/mod_version.html # sudo a2enmod version -- cgit v1.2.3 From 083b28021a34120778c203c85be6461a426cfa44 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Sun, 16 Aug 2020 19:16:19 +0200 Subject: doc: server configuration: fix apache restart command --- doc/md/Server-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 8eeb10bd..3eeaad70 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -216,7 +216,7 @@ sudo a2enmod headers # sudo a2enmod version # restart the apache service -systemctl restart apache +sudo systemctl restart apache2 ``` See [How to install the Apache web server](https://www.digitalocean.com/community/tutorials/how-to-install-the-apache-web-server-on-debian-10) for a complete guide. -- 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/Server-configuration.md | 78 ++++++++++++++++++++---------------------- 1 file changed, 38 insertions(+), 40 deletions(-) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 3eeaad70..bad00ac5 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -4,12 +4,15 @@ ### Operating system and web server -Shaarli can be hosted on dedicated/virtual servers, or shared hosting. The smallest DigitalOcean VPS (Droplet with 1 CPU, 1 GiB RAM and 25 GiB SSD) costs about $5/month and will run any Shaarli installation without problems. +Shaarli can be hosted on dedicated/virtual servers, or shared hosting. You need write access to the Shaarli installation directory - you should have received instructions from your hosting provider on how to connect to the server using SSH (or FTP for shared hosts). Examples in this documentation are given for [Debian](https://www.debian.org/), a GNU/Linux distribution widely used in server environments. Please adapt them to your specific Linux distribution. +A $5/month VPS (1 CPU, 1 GiB RAM and 25 GiB SSD) will run any Shaarli installation without problems. Some hosting providers: [DigitalOcean](https://www.digitalocean.com/) ([1](https://www.digitalocean.com/docs/droplets/overview/), [2](https://www.digitalocean.com/pricing/), [3](https://www.digitalocean.com/docs/droplets/how-to/create/), [4](https://www.digitalocean.com/docs/droplets/how-to/add-ssh-keys/), [5](https://www.digitalocean.com/community/tutorials/initial-server-setup-with-debian-8), [6](https://www.digitalocean.com/community/tutorials/an-introduction-to-securing-your-linux-vps)), [Gandi](https://www.gandi.net/en), [OVH](https://www.ovh.co.uk/), [RackSpace](https://www.rackspace.com/), etc. + + ### Network and domain name Try to host the server in a region that is geographically close to your users. @@ -61,10 +64,16 @@ Extension | Required? | Usage Some [plugins](Plugins.md) may require additional configuration. +- [PHP: Supported versions](http://php.net/supported-versions.php) +- [PHP: Unsupported versions (EOL/End-of-life)](http://php.net/eol.php) +- [PHP 7 Changelog](http://php.net/ChangeLog-7.php) +- [PHP 5 Changelog](http://php.net/ChangeLog-5.php) +- [PHP: Bugs](https://bugs.php.net/) + ## SSL/TLS (HTTPS) -We recommend setting up [HTTPS](https://en.wikipedia.org/wiki/HTTPS) on your webserver for secure communication between clients and the server. +We recommend setting up [HTTPS](https://en.wikipedia.org/wiki/HTTPS) (SSL/[TLS](https://en.wikipedia.org/wiki/Transport_Layer_Security)) on your webserver for secure communication between clients and the server. ### Let's Encrypt @@ -103,6 +112,8 @@ If you don't want to rely on a certificate authority, or the server can only be - [How To Create a Self-Signed SSL Certificate for Apache](https://www.digitalocean.com/community/tutorials/how-to-create-a-self-signed-ssl-certificate-for-apache-on-debian-10) - [How To Create a Self-Signed SSL Certificate for Nginx](https://www.digitalocean.com/community/tutorials/how-to-create-a-self-signed-ssl-certificate-for-nginx-on-debian-10) +- [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php) +- [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority) -------------------------------------------------------------------------------- @@ -134,17 +145,20 @@ sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf 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 DocumentRoot /var/www/shaarli.mydomain.org/ @@ -160,10 +174,7 @@ sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf SSLSessionTickets off SSLOptions +StrictRequire - # SSL/TLS configuration for Let's Encrypt certificates acquired with mod_md - #MDomain shaarli.mydomain.org - - # SSL/TLS configuration (for self-signed certificates) + # 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 @@ -219,7 +230,13 @@ sudo a2enmod headers sudo systemctl restart apache2 ``` -See [How to install the Apache web server](https://www.digitalocean.com/community/tutorials/how-to-install-the-apache-web-server-on-debian-10) for a complete guide. +- [How to install the Apache web server](https://www.digitalocean.com/community/tutorials/how-to-install-the-apache-web-server-on-debian-10) +- [Apache/PHP - error log per VirtualHost - StackOverflow](http://stackoverflow.com/q/176) +- [Apache - PHP: php_value vs php_admin_value and the use of php_flag explained](https://ma.ttias.be/php-php_value-vs-php_admin_value-and-the-use-of-php_flag-explained/) +- [Server-side TLS (Apache) - Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache) +- [Apache 2.4 documentation](https://httpd.apache.org/docs/2.4/) +- [Apache mod_proxy](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html) +- [Apache Reverse Proxy Request Headers](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#x-headers) ### Nginx @@ -326,7 +343,14 @@ sudo ln -s /etc/nginx/sites-available/shaarli.mydomain.org /etc/nginx/sites-enab sudo systemctl reload nginx ``` -See [How to install the Nginx web server](https://www.digitalocean.com/community/tutorials/how-to-install-nginx-on-debian-10) for a complete guide. +- [How to install the Nginx web server](https://www.digitalocean.com/community/tutorials/how-to-install-nginx-on-debian-10) +- [Nginx Beginner's guide](http://nginx.org/en/docs/beginners_guide.html) +- [Nginx documentation](https://nginx.org/en/docs/) +- [Nginx ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html) +- [Nginx Pitfalls](http://wiki.nginx.org/Pitfalls) +- [Nginx PHP configuration examples - Karl Blessing](http://kbeezie.com/nginx-configuration-examples/) +- [Server-side TLS (Nginx) - Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) + ## Reverse proxies @@ -413,33 +437,7 @@ bantime = -1 Then restart the service: `sudo systemctl restart fail2ban` -#### References - -- [Apache/PHP - error log per VirtualHost - StackOverflow](http://stackoverflow.com/q/176) -- [Apache - PHP: php_value vs php_admin_value and the use of php_flag explained](https://ma.ttias.be/php-php_value-vs-php_admin_value-and-the-use-of-php_flag-explained/) -- [Server-side TLS (Apache) - Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache) -- [Nginx Beginner's guide](http://nginx.org/en/docs/beginners_guide.html) -- [Nginx ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html) -- [Nginx Pitfalls](http://wiki.nginx.org/Pitfalls) -- [Nginx PHP configuration examples - Karl Blessing](http://kbeezie.com/nginx-configuration-examples/) -- [Apache 2.4 documentation](https://httpd.apache.org/docs/2.4/) -- [Apache mod_proxy](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html) -- [Apache Reverse Proxy Request Headers](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#x-headers) -- [HAProxy documentation](https://cbonte.github.io/haproxy-dconv/) -- [Nginx documentation](https://nginx.org/en/docs/) -- [`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) -- [Server-side TLS (Nginx) - Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) -- [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php) -- [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority) -- [Travis configuration](https://github.com/shaarli/Shaarli/blob/master/.travis.yml) -- [PHP: Supported versions](http://php.net/supported-versions.php) -- [PHP: Unsupported versions (EOL/End-of-life)](http://php.net/eol.php) -- [PHP 7 Changelog](http://php.net/ChangeLog-7.php) -- [PHP 5 Changelog](http://php.net/ChangeLog-5.php) -- [PHP: Bugs](https://bugs.php.net/) -- [Transport Layer Security](https://en.wikipedia.org/wiki/Transport_Layer_Security) -- Hosting providers: [DigitalOcean](https://www.digitalocean.com/) ([1](https://www.digitalocean.com/docs/droplets/overview/), [2](https://www.digitalocean.com/pricing/), [3](https://www.digitalocean.com/docs/droplets/how-to/create/), [How to Add SSH Keys to Droplets](https://www.digitalocean.com/docs/droplets/how-to/add-ssh-keys/), [4](https://www.digitalocean.com/community/tutorials/initial-server-setup-with-debian-8), [5](https://www.digitalocean.com/community/tutorials/an-introduction-to-securing-your-linux-vps)), [Gandi](https://www.gandi.net/en), [OVH](https://www.ovh.co.uk/), [RackSpace](https://www.rackspace.com/), etc. +## What next? +[Shaarli installation](Installation.md) -- cgit v1.2.3 From a5e9f2d6c927a3b7e58ac2a0747103634e4394a5 Mon Sep 17 00:00:00 2001 From: nodiscc Date: Mon, 24 Aug 2020 21:33:53 +0200 Subject: doc: nginx config: document ipv4 and ipv6 listen directives --- doc/md/Server-configuration.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) (limited to 'doc/md/Server-configuration.md') diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index bad00ac5..297d7c29 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -263,7 +263,10 @@ server { } server { - listen 443 ssl; + # ipv4 listening port/protocol + listen 443 ssl http2; + # ipv6 listening port/protocol + listen [::]:443 ssl http2; server_name shaarli.mydomain.org; root /var/www/shaarli.mydomain.org; -- cgit v1.2.3