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