]> git.immae.eu Git - github/shaarli/Shaarli.git/blob - doc/md/Server-configuration.md
doc: nginx config: document ipv4 and ipv6 listen directives
[github/shaarli/Shaarli.git] / doc / md / Server-configuration.md
1 # Server configuration
2
3 ## Requirements
4
5 ### Operating system and web server
6
7 Shaarli can be hosted on dedicated/virtual servers, or shared hosting.
8
9 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).
10
11 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.
12
13 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.
14
15
16 ### Network and domain name
17
18 Try to host the server in a region that is geographically close to your users.
19
20 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.
21
22 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).
23
24 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.
25
26 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.
27
28
29 ### Screencast
30
31 Here is a screencast of the installation procedure
32
33 [![asciicast](https://asciinema.org/a/z3RXxcJIRgWk0jM2ws6EnUFgO.svg)](https://asciinema.org/a/z3RXxcJIRgWk0jM2ws6EnUFgO)
34
35 --------------------------------------------------------------------------------
36
37 ### PHP
38
39 Supported PHP versions:
40
41 Version | Status | Shaarli compatibility
42 :---:|:---:|:---:
43 7.3 | Supported | Yes
44 7.2 | Supported | Yes
45 7.1 | Supported | Yes
46 7.0 | EOL: 2018-12-03 | Yes (up to Shaarli 0.10.x)
47 5.6 | EOL: 2018-12-31 | Yes (up to Shaarli 0.10.x)
48 5.5 | EOL: 2016-07-10 | Yes
49 5.4 | EOL: 2015-09-14 | Yes (up to Shaarli 0.8.x)
50 5.3 | EOL: 2014-08-14 | Yes (up to Shaarli 0.8.x)
51
52 Required PHP extensions:
53
54 Extension | Required? | Usage
55 ---|:---:|---
56 [`openssl`](http://php.net/manual/en/book.openssl.php) | requires | OpenSSL, HTTPS
57 [`php-json`](http://php.net/manual/en/book.json.php) | required | configuration parsing
58 [`php-simplexml`](https://www.php.net/manual/en/book.simplexml.php) | required | REST API (Slim framework)
59 [`php-mbstring`](http://php.net/manual/en/book.mbstring.php) | CentOS, Fedora, RHEL, Windows, some hosting providers | multibyte (Unicode) string support
60 [`php-gd`](http://php.net/manual/en/book.image.php) | optional | required to use thumbnails
61 [`php-intl`](http://php.net/manual/en/book.intl.php) | optional | localized text sorting (e.g. `e->รจ->f`)
62 [`php-curl`](http://php.net/manual/en/book.curl.php) | optional | using cURL for fetching webpages and thumbnails in a more robust way
63 [`php-gettext`](http://php.net/manual/en/book.gettext.php) | optional | Use the translation system in gettext mode (faster)
64
65 Some [plugins](Plugins.md) may require additional configuration.
66
67 - [PHP: Supported versions](http://php.net/supported-versions.php)
68 - [PHP: Unsupported versions (EOL/End-of-life)](http://php.net/eol.php)
69 - [PHP 7 Changelog](http://php.net/ChangeLog-7.php)
70 - [PHP 5 Changelog](http://php.net/ChangeLog-5.php)
71 - [PHP: Bugs](https://bugs.php.net/)
72
73
74 ## SSL/TLS (HTTPS)
75
76 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.
77
78 ### Let's Encrypt
79
80 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.
81
82 - [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)
83 - [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)
84 - [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).
85
86 In short:
87
88 ```bash
89 # install certbot
90 sudo apt install certbot
91
92 # stop your webserver if you already have one running
93 # certbot in standalone mode needs to bind to port 80 (only needed on initial generation)
94 sudo systemctl stop apache2
95 sudo systemctl stop nginx
96
97 # generate initial certificates
98 # Let's Encrypt ACME servers must be able to access your server! port forwarding and firewall must be properly configured
99 sudo certbot certonly --standalone --noninteractive --agree-tos --email "admin@shaarli.mydomain.org" -d shaarli.mydomain.org
100 # this will generate a private key and certificate at /etc/letsencrypt/live/shaarli.mydomain.org/{privkey,fullchain}.pem
101
102 # restart the web server
103 sudo systemctl start apache2
104 sudo systemctl start nginx
105 ```
106
107 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.
108
109 ### Self-signed
110
111 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:
112
113 - [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)
114 - [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)
115 - [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php)
116 - [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority)
117
118 --------------------------------------------------------------------------------
119
120 ## Examples
121
122 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/`:
123
124 ```bash
125 # create the document root (replace with your own domain name)
126 sudo mkdir -p /var/www/shaarli.mydomain.org/
127 ```
128
129 You can install Shaarli at the root of your virtualhost, or in a subdirectory as well. See [Directory structure](Directory-structure)
130
131
132 ### Apache
133
134 ```bash
135 # Install apache + mod_php and PHP modules
136 sudo apt update
137 sudo apt install apache2 libapache2-mod-php php-json php-mbstring php-gd php-intl php-curl php-gettext
138
139 # Edit the virtualhost configuration file with your favorite editor (replace the example domain name)
140 sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf
141 ```
142
143 ```apache
144 <VirtualHost *:80>
145 ServerName shaarli.mydomain.org
146 DocumentRoot /var/www/shaarli.mydomain.org/
147
148 # For SSL/TLS certificates acquired with certbot or self-signed certificates
149 # Redirect HTTP requests to HTTPS, except Let's Encrypt ACME challenge requests
150 RewriteEngine on
151 RewriteRule ^.well-known/acme-challenge/ - [L]
152 RewriteCond %{HTTP_HOST} =shaarli.mydomain.org
153 RewriteRule ^ https://shaarli.mydomain.org%{REQUEST_URI} [END,NE,R=permanent]
154 </VirtualHost>
155
156 # SSL/TLS configuration for Let's Encrypt certificates managed with mod_md
157 #MDomain shaarli.mydomain.org
158 #MDCertificateAgreement accepted
159 #MDContactEmail admin@shaarli.mydomain.org
160 #MDPrivateKeys RSA 4096
161
162 <VirtualHost *:443>
163 ServerName shaarli.mydomain.org
164 DocumentRoot /var/www/shaarli.mydomain.org/
165
166 # SSL/TLS configuration for Let's Encrypt certificates acquired with certbot standalone
167 SSLEngine on
168 SSLCertificateFile /etc/letsencrypt/live/shaarli.mydomain.org/fullchain.pem
169 SSLCertificateKeyFile /etc/letsencrypt/live/shaarli.mydomain.org/privkey.pem
170 # Let's Encrypt settings from https://github.com/certbot/certbot/blob/master/certbot-apache/certbot_apache/_internal/tls_configs/current-options-ssl-apache.conf
171 SSLProtocol all -SSLv2 -SSLv3 -TLSv1 -TLSv1.1
172 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
173 SSLHonorCipherOrder off
174 SSLSessionTickets off
175 SSLOptions +StrictRequire
176
177 # SSL/TLS configuration for self-signed certificates
178 #SSLEngine on
179 #SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem
180 #SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
181
182 # Optional, log PHP errors, useful for debugging
183 #php_flag log_errors on
184 #php_flag display_errors on
185 #php_value error_reporting 2147483647
186 #php_value error_log /var/log/apache2/shaarli-php-error.log
187
188 <Directory /var/www/shaarli.mydomain.org/>
189 # Required for .htaccess support
190 AllowOverride All
191 Require all granted
192 </Directory>
193
194 <LocationMatch "/\.">
195 # Prevent accessing dotfiles
196 RedirectMatch 404 ".*"
197 </LocationMatch>
198
199 <LocationMatch "\.(?:ico|css|js|gif|jpe?g|png)$">
200 # allow client-side caching of static files
201 Header set Cache-Control "max-age=2628000, public, must-revalidate, proxy-revalidate"
202 </LocationMatch>
203
204 # serve the Shaarli favicon from its custom location
205 Alias favicon.ico /var/www/shaarli.mydomain.org/images/favicon.ico
206
207 </VirtualHost>
208 ```
209
210 ```bash
211 # Enable the virtualhost
212 sudo a2ensite shaarli.mydomain.org
213
214 # mod_ssl must be enabled to use TLS/SSL certificates
215 # https://httpd.apache.org/docs/current/mod/mod_ssl.html
216 sudo a2enmod ssl
217
218 # mod_rewrite must be enabled to use the REST API
219 # https://httpd.apache.org/docs/current/mod/mod_rewrite.html
220 sudo a2enmod rewrite
221
222 # mod_headers must be enabled to set custom headers from the server config
223 sudo a2enmod headers
224
225 # mod_version must only be enabled if you use Apache 2.2 or lower
226 # https://httpd.apache.org/docs/current/mod/mod_version.html
227 # sudo a2enmod version
228
229 # restart the apache service
230 sudo systemctl restart apache2
231 ```
232
233 - [How to install the Apache web server](https://www.digitalocean.com/community/tutorials/how-to-install-the-apache-web-server-on-debian-10)
234 - [Apache/PHP - error log per VirtualHost - StackOverflow](http://stackoverflow.com/q/176)
235 - [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/)
236 - [Server-side TLS (Apache) - Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache)
237 - [Apache 2.4 documentation](https://httpd.apache.org/docs/2.4/)
238 - [Apache mod_proxy](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html)
239 - [Apache Reverse Proxy Request Headers](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#x-headers)
240
241
242 ### Nginx
243
244 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`.
245
246
247 ```bash
248 # install nginx and php-fpm
249 sudo apt update
250 sudo apt install nginx php-fpm
251
252 # Edit the virtualhost configuration file with your favorite editor
253 sudo nano /etc/nginx/sites-available/shaarli.mydomain.org
254 ```
255
256 ```nginx
257 server {
258 listen 80;
259 server_name shaarli.mydomain.org;
260
261 # redirect all plain HTTP requests to HTTPS
262 return 301 https://shaarli.mydomain.org$request_uri;
263 }
264
265 server {
266 # ipv4 listening port/protocol
267 listen 443 ssl http2;
268 # ipv6 listening port/protocol
269 listen [::]:443 ssl http2;
270 server_name shaarli.mydomain.org;
271 root /var/www/shaarli.mydomain.org;
272
273 # log file locations
274 # combined log format prepends the virtualhost/domain name to log entries
275 access_log /var/log/nginx/access.log combined;
276 error_log /var/log/nginx/error.log;
277
278 # paths to private key and certificates for SSL/TLS
279 ssl_certificate /etc/ssl/shaarli.mydomain.org.crt;
280 ssl_certificate_key /etc/ssl/private/shaarli.mydomain.org.key;
281
282 # Let's Encrypt SSL settings from https://github.com/certbot/certbot/blob/master/certbot-nginx/certbot_nginx/_internal/tls_configs/options-ssl-nginx.conf
283 ssl_session_cache shared:le_nginx_SSL:10m;
284 ssl_session_timeout 1440m;
285 ssl_session_tickets off;
286 ssl_protocols TLSv1.2 TLSv1.3;
287 ssl_prefer_server_ciphers off;
288 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";
289
290 # increase the maximum file upload size if needed: by default nginx limits file upload to 1MB (413 Entity Too Large error)
291 client_max_body_size 100m;
292
293 # relative path to shaarli from the root of the webserver
294 location / {
295 # default index file when no file URI is requested
296 index index.php;
297 try_files $uri /index.php$is_args$args;
298 }
299
300 location ~ (index)\.php$ {
301 try_files $uri =404;
302 # slim API - split URL path into (script_filename, path_info)
303 fastcgi_split_path_info ^(.+\.php)(/.+)$;
304 # pass PHP requests to PHP-FPM
305 fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
306 fastcgi_index index.php;
307 include fastcgi.conf;
308 }
309
310 location ~ \.php$ {
311 # deny access to all other PHP scripts
312 # disable this if you host other PHP applications on the same virtualhost
313 deny all;
314 }
315
316 location ~ /\. {
317 # deny access to dotfiles
318 deny all;
319 }
320
321 location ~ ~$ {
322 # deny access to temp editor files, e.g. "script.php~"
323 deny all;
324 }
325
326 location = /favicon.ico {
327 # serve the Shaarli favicon from its custom location
328 alias /var/www/shaarli/images/favicon.ico;
329 }
330
331 # allow client-side caching of static files
332 location ~* \.(?:ico|css|js|gif|jpe?g|png)$ {
333 expires max;
334 add_header Cache-Control "public, must-revalidate, proxy-revalidate";
335 # HTTP 1.0 compatibility
336 add_header Pragma public;
337 }
338
339 }
340 ```
341
342 ```bash
343 # enable the configuration/virtualhost
344 sudo ln -s /etc/nginx/sites-available/shaarli.mydomain.org /etc/nginx/sites-enabled/shaarli.mydomain.org
345 # reload nginx configuration
346 sudo systemctl reload nginx
347 ```
348
349 - [How to install the Nginx web server](https://www.digitalocean.com/community/tutorials/how-to-install-nginx-on-debian-10)
350 - [Nginx Beginner's guide](http://nginx.org/en/docs/beginners_guide.html)
351 - [Nginx documentation](https://nginx.org/en/docs/)
352 - [Nginx ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)
353 - [Nginx Pitfalls](http://wiki.nginx.org/Pitfalls)
354 - [Nginx PHP configuration examples - Karl Blessing](http://kbeezie.com/nginx-configuration-examples/)
355 - [Server-side TLS (Nginx) - Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx)
356
357
358
359 ## Reverse proxies
360
361 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.
362
363
364
365 ## Allow import of large browser bookmarks export
366
367 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.
368
369 - Apache: `/etc/php/<PHP_VERSION>/apache2/php.ini`
370 - Nginx + PHP-FPM: `/etc/php/<PHP_VERSION>/fpm/php.ini` (in addition to `client_max_body_size` in the [Nginx configuration](#nginx))
371
372 ```ini
373 [...]
374 # (optional) increase the maximum file upload size:
375 post_max_size = 100M
376 [...]
377 # (optional) increase the maximum file upload size:
378 upload_max_filesize = 100M
379 ```
380
381 To verify PHP settings currently set on the server, create a `phpinfo.php` in your webserver's document root
382
383 ```bash
384 # example
385 echo '<?php phpinfo(); ?>' | sudo tee /var/www/shaarli.mydomain.org/phpinfo.php
386 #give read-only access to this file to the webserver user
387 sudo chown www-data:root /var/www/shaarli.mydomain.org/phpinfo.php
388 sudo chmod 0400 /var/www/shaarli.mydomain.org/phpinfo.php
389 ```
390
391 Access the file from a web browser (eg. <https://shaarli.mydomain.org/phpinfo.php> and look at the _Loaded Configuration File_ and _Scan this dir for additional .ini files_ entries
392
393 It is recommended to remove the `phpinfo.php` when no longer needed as it publicly discloses details about your webserver configuration.
394
395
396 ## Robots and crawlers
397
398 To opt-out of indexing your Shaarli instance by search engines, create a `robots.txt` file at the root of your virtualhost:
399
400 ```
401 User-agent: *
402 Disallow: /
403 ```
404
405 By default Shaarli already disallows indexing of your local copy of the documentation by default, using `<meta name="robots">` 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.
406
407 - [Robots exclusion standard](https://en.wikipedia.org/wiki/Robots_exclusion_standard)
408 - [Introduction to robots.txt](https://support.google.com/webmasters/answer/6062608?hl=en)
409 - [Robots meta tag, data-nosnippet, and X-Robots-Tag specifications](https://developers.google.com/search/reference/robots_meta_tag)
410 - [About robots.txt](http://www.robotstxt.org)
411 - [About the robots META tag](https://www.robotstxt.org/meta.html)
412
413
414 ## Fail2ban
415
416 [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:
417
418 ```ini
419 # /etc/fail2ban/filter.d/shaarli-auth.conf
420 [INCLUDES]
421 before = common.conf
422 [Definition]
423 failregex = \s-\s<HOST>\s-\sLogin failed for user.*$
424 ignoreregex =
425 ```
426
427 ```ini
428 # /etc/fail2ban/jail.local
429 [shaarli-auth]
430 enabled = true
431 port = https,http
432 filter = shaarli-auth
433 logpath = /var/www/shaarli.mydomain.org/data/log.txt
434 # allow 3 login attempts per IP address
435 # (over a period specified by findtime = in /etc/fail2ban/jail.conf)
436 maxretry = 3
437 # permanently ban the IP address after reaching the limit
438 bantime = -1
439 ```
440
441 Then restart the service: `sudo systemctl restart fail2ban`
442
443
444 ## What next?
445
446 [Shaarli installation](Installation.md)