X-Git-Url: https://git.immae.eu/?a=blobdiff_plain;f=doc%2Fmd%2FServer-configuration.md;h=a49b60334c11526bd289ffbd982e04bfbce5ab9d;hb=7e78237fc9106f5f53802c36ce26be0b44938255;hp=73e23886909cbbfdd45de4172f5bb7644036e7ba;hpb=f3ab2616314834508c36b5e97406572ecd9af7a4;p=github%2Fshaarli%2FShaarli.git diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md index 73e23886..a49b6033 100644 --- a/doc/md/Server-configuration.md +++ b/doc/md/Server-configuration.md @@ -1,17 +1,18 @@ # Server configuration - - ## 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. +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. @@ -25,12 +26,22 @@ 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 Supported PHP versions: Version | Status | Shaarli compatibility :---:|:---:|:---: +8.0 | Supported | Yes +7.4 | Supported | Yes 7.3 | Supported | Yes 7.2 | Supported | Yes 7.1 | Supported | Yes @@ -44,7 +55,7 @@ Required PHP extensions: Extension | Required? | Usage ---|:---:|--- -[`openssl`](http://php.net/manual/en/book.openssl.php) | requires | OpenSSL, HTTPS +[`openssl`](http://php.net/manual/en/book.openssl.php) | required | 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 @@ -55,10 +66,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 @@ -97,6 +114,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) -------------------------------------------------------------------------------- @@ -105,7 +124,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/ ``` @@ -119,7 +138,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 ``` @@ -128,17 +147,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/ @@ -154,10 +176,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 @@ -174,25 +193,30 @@ sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf Require all granted - - # Prevent accessing dotfiles - RedirectMatch 404 ".*" - + # BE CAREFUL: directives order matter! + + + Require all denied + - + + Require all granted + + + # 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 - ``` ```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 @@ -202,15 +226,24 @@ 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 # 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. +- [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 @@ -237,7 +270,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; @@ -265,7 +301,7 @@ server { location / { # default index file when no file URI is requested index index.php; - try_files $uri /index.php$is_args$args; + try_files _ /index.php$is_args$args; } location ~ (index)\.php$ { @@ -278,20 +314,9 @@ server { include fastcgi.conf; } - location ~ \.php$ { - # deny access to all other PHP scripts - # disable this if you host other PHP applications on the same virtualhost - deny all; - } - - location ~ /\. { - # deny access to dotfiles - deny all; - } - - location ~ ~$ { - # deny access to temp editor files, e.g. "script.php~" - deny all; + location ~ /doc/html/ { + default_type "text/html"; + try_files $uri $uri/ $uri.html =404; } location = /favicon.ico { @@ -300,13 +325,12 @@ server { } # allow client-side caching of static files - location ~* \.(?:ico|css|js|gif|jpe?g|png)$ { + location ~* \.(?:ico|css|js|gif|jpe?g|png|ttf|oet|woff2?)$ { expires max; add_header Cache-Control "public, must-revalidate, proxy-revalidate"; # HTTP 1.0 compatibility add_header Pragma public; } - } ``` @@ -317,14 +341,37 @@ 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 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. +## Using Shaarli without URL rewriting + +By default, Shaarli uses Slim framework's URL, which requires +URL rewriting. + +If you can't use URL rewriting for any reason (not supported by +your web server, shared hosting, etc.), you *can* use Shaarli +without URL rewriting. +You just need to prefix your URL by `/index.php/`. +Example: instead of accessing `https://shaarli.mydomain.org/`, +use `https://shaarli.mydomain.org/index.php/`. + +**Recommended:** + * after installation, in the configuration page, set your header link to `/index.php/`. + * in your configuration file `config.json.php` set `general.root_url` to + `https://shaarli.mydomain.org/index.php/`. ## Allow import of large browser bookmarks export @@ -385,7 +432,7 @@ By default Shaarli already disallows indexing of your local copy of the document before = common.conf [Definition] failregex = \s-\s\s-\sLogin failed for user.*$ -ignoreregex = +ignoreregex = ``` ```ini @@ -402,33 +449,9 @@ maxretry = 3 bantime = -1 ``` -#### References +Then restart the service: `sudo systemctl restart fail2ban` -- [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)