5 ### Operating system and web server
7 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.
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).
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.
13 ### Network and domain name
15 Try to host the server in a region that is geographically close to your users.
17 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.
19 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).
21 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.
23 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.
28 Here is a screencast of the installation procedure
30 [![asciicast](https://asciinema.org/a/z3RXxcJIRgWk0jM2ws6EnUFgO.svg)](https://asciinema.org/a/z3RXxcJIRgWk0jM2ws6EnUFgO)
32 --------------------------------------------------------------------------------
36 Supported PHP versions:
38 Version | Status | Shaarli compatibility
43 7.0 | EOL: 2018-12-03 | Yes (up to Shaarli 0.10.x)
44 5.6 | EOL: 2018-12-31 | Yes (up to Shaarli 0.10.x)
45 5.5 | EOL: 2016-07-10 | Yes
46 5.4 | EOL: 2015-09-14 | Yes (up to Shaarli 0.8.x)
47 5.3 | EOL: 2014-08-14 | Yes (up to Shaarli 0.8.x)
49 Required PHP extensions:
51 Extension | Required? | Usage
53 [`openssl`](http://php.net/manual/en/book.openssl.php) | requires | OpenSSL, HTTPS
54 [`php-json`](http://php.net/manual/en/book.json.php) | required | configuration parsing
55 [`php-simplexml`](https://www.php.net/manual/en/book.simplexml.php) | required | REST API (Slim framework)
56 [`php-mbstring`](http://php.net/manual/en/book.mbstring.php) | CentOS, Fedora, RHEL, Windows, some hosting providers | multibyte (Unicode) string support
57 [`php-gd`](http://php.net/manual/en/book.image.php) | optional | required to use thumbnails
58 [`php-intl`](http://php.net/manual/en/book.intl.php) | optional | localized text sorting (e.g. `e->รจ->f`)
59 [`php-curl`](http://php.net/manual/en/book.curl.php) | optional | using cURL for fetching webpages and thumbnails in a more robust way
60 [`php-gettext`](http://php.net/manual/en/book.gettext.php) | optional | Use the translation system in gettext mode (faster)
62 Some [plugins](Plugins.md) may require additional configuration.
67 We recommend setting up [HTTPS](https://en.wikipedia.org/wiki/HTTPS) on your webserver for secure communication between clients and the server.
71 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.
73 - [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)
74 - [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)
75 - [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).
81 sudo apt install certbot
83 # stop your webserver if you already have one running
84 # certbot in standalone mode needs to bind to port 80 (only needed on initial generation)
85 sudo systemctl stop apache2
86 sudo systemctl stop nginx
88 # generate initial certificates
89 # Let's Encrypt ACME servers must be able to access your server! port forwarding and firewall must be properly configured
90 sudo certbot certonly --standalone --noninteractive --agree-tos --email "admin@shaarli.mydomain.org" -d shaarli.mydomain.org
91 # this will generate a private key and certificate at /etc/letsencrypt/live/shaarli.mydomain.org/{privkey,fullchain}.pem
93 # restart the web server
94 sudo systemctl start apache2
95 sudo systemctl start nginx
98 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.
102 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:
104 - [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)
105 - [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)
107 --------------------------------------------------------------------------------
111 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/`:
114 # create the document root (replace with your own domain name)
115 sudo mkdir -p /var/www/shaarli.mydomain.org/
118 You can install Shaarli at the root of your virtualhost, or in a subdirectory as well. See [Directory structure](Directory-structure)
124 # Install apache + mod_php and PHP modules
126 sudo apt install apache2 libapache2-mod-php php-json php-mbstring php-gd php-intl php-curl php-gettext
128 # Edit the virtualhost configuration file with your favorite editor (replace the example domain name)
129 sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf
134 ServerName shaarli.mydomain.org
135 DocumentRoot /var/www/shaarli.mydomain.org/
137 # Redirect HTTP requests to HTTPS, except Let's Encrypt ACME challenge requests
139 RewriteRule ^.well-known/acme-challenge/ - [L]
140 RewriteCond %{HTTP_HOST} =shaarli.mydomain.org
141 RewriteRule ^ https://shaarli.mydomain.org%{REQUEST_URI} [END,NE,R=permanent]
142 # If you are using mod_md, use this instead
143 #MDCertificateAgreement accepted
144 #MDContactEmail admin@shaarli.mydomain.org
145 #MDPrivateKeys RSA 4096
149 ServerName shaarli.mydomain.org
150 DocumentRoot /var/www/shaarli.mydomain.org/
152 # SSL/TLS configuration for Let's Encrypt certificates acquired with certbot standalone
154 SSLCertificateFile /etc/letsencrypt/live/shaarli.mydomain.org/fullchain.pem
155 SSLCertificateKeyFile /etc/letsencrypt/live/shaarli.mydomain.org/privkey.pem
156 # Let's Encrypt settings from https://github.com/certbot/certbot/blob/master/certbot-apache/certbot_apache/_internal/tls_configs/current-options-ssl-apache.conf
157 SSLProtocol all -SSLv2 -SSLv3 -TLSv1 -TLSv1.1
158 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
159 SSLHonorCipherOrder off
160 SSLSessionTickets off
161 SSLOptions +StrictRequire
163 # SSL/TLS configuration for Let's Encrypt certificates acquired with mod_md
164 #MDomain shaarli.mydomain.org
166 # SSL/TLS configuration (for self-signed certificates)
168 #SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem
169 #SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
171 # Optional, log PHP errors, useful for debugging
172 #php_flag log_errors on
173 #php_flag display_errors on
174 #php_value error_reporting 2147483647
175 #php_value error_log /var/log/apache2/shaarli-php-error.log
177 <Directory /var/www/shaarli.mydomain.org/>
178 # Required for .htaccess support
183 <LocationMatch "/\.">
184 # Prevent accessing dotfiles
185 RedirectMatch 404 ".*"
188 <LocationMatch "\.(?:ico|css|js|gif|jpe?g|png)$">
189 # allow client-side caching of static files
190 Header set Cache-Control "max-age=2628000, public, must-revalidate, proxy-revalidate"
193 # serve the Shaarli favicon from its custom location
194 Alias favicon.ico /var/www/shaarli.mydomain.org/images/favicon.ico
200 # Enable the virtualhost
201 sudo a2ensite shaarli.mydomain.org
203 # mod_ssl must be enabled to use TLS/SSL certificates
204 # https://httpd.apache.org/docs/current/mod/mod_ssl.html
207 # mod_rewrite must be enabled to use the REST API
208 # https://httpd.apache.org/docs/current/mod/mod_rewrite.html
211 # mod_headers must be enabled to set custom headers from the server config
214 # mod_version must only be enabled if you use Apache 2.2 or lower
215 # https://httpd.apache.org/docs/current/mod/mod_version.html
216 # sudo a2enmod version
218 # restart the apache service
219 sudo systemctl restart apache2
222 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.
227 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`.
231 # install nginx and php-fpm
233 sudo apt install nginx php-fpm
235 # Edit the virtualhost configuration file with your favorite editor
236 sudo nano /etc/nginx/sites-available/shaarli.mydomain.org
242 server_name shaarli.mydomain.org;
244 # redirect all plain HTTP requests to HTTPS
245 return 301 https://shaarli.mydomain.org$request_uri;
250 server_name shaarli.mydomain.org;
251 root /var/www/shaarli.mydomain.org;
254 # combined log format prepends the virtualhost/domain name to log entries
255 access_log /var/log/nginx/access.log combined;
256 error_log /var/log/nginx/error.log;
258 # paths to private key and certificates for SSL/TLS
259 ssl_certificate /etc/ssl/shaarli.mydomain.org.crt;
260 ssl_certificate_key /etc/ssl/private/shaarli.mydomain.org.key;
262 # Let's Encrypt SSL settings from https://github.com/certbot/certbot/blob/master/certbot-nginx/certbot_nginx/_internal/tls_configs/options-ssl-nginx.conf
263 ssl_session_cache shared:le_nginx_SSL:10m;
264 ssl_session_timeout 1440m;
265 ssl_session_tickets off;
266 ssl_protocols TLSv1.2 TLSv1.3;
267 ssl_prefer_server_ciphers off;
268 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";
270 # increase the maximum file upload size if needed: by default nginx limits file upload to 1MB (413 Entity Too Large error)
271 client_max_body_size 100m;
273 # relative path to shaarli from the root of the webserver
275 # default index file when no file URI is requested
277 try_files $uri /index.php$is_args$args;
280 location ~ (index)\.php$ {
282 # slim API - split URL path into (script_filename, path_info)
283 fastcgi_split_path_info ^(.+\.php)(/.+)$;
284 # pass PHP requests to PHP-FPM
285 fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
286 fastcgi_index index.php;
287 include fastcgi.conf;
291 # deny access to all other PHP scripts
292 # disable this if you host other PHP applications on the same virtualhost
297 # deny access to dotfiles
302 # deny access to temp editor files, e.g. "script.php~"
306 location = /favicon.ico {
307 # serve the Shaarli favicon from its custom location
308 alias /var/www/shaarli/images/favicon.ico;
311 # allow client-side caching of static files
312 location ~* \.(?:ico|css|js|gif|jpe?g|png)$ {
314 add_header Cache-Control "public, must-revalidate, proxy-revalidate";
315 # HTTP 1.0 compatibility
316 add_header Pragma public;
323 # enable the configuration/virtualhost
324 sudo ln -s /etc/nginx/sites-available/shaarli.mydomain.org /etc/nginx/sites-enabled/shaarli.mydomain.org
325 # reload nginx configuration
326 sudo systemctl reload nginx
329 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.
334 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.
338 ## Allow import of large browser bookmarks export
340 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.
342 - Apache: `/etc/php/<PHP_VERSION>/apache2/php.ini`
343 - Nginx + PHP-FPM: `/etc/php/<PHP_VERSION>/fpm/php.ini` (in addition to `client_max_body_size` in the [Nginx configuration](#nginx))
347 # (optional) increase the maximum file upload size:
350 # (optional) increase the maximum file upload size:
351 upload_max_filesize = 100M
354 To verify PHP settings currently set on the server, create a `phpinfo.php` in your webserver's document root
358 echo '<?php phpinfo(); ?>' | sudo tee /var/www/shaarli.mydomain.org/phpinfo.php
359 #give read-only access to this file to the webserver user
360 sudo chown www-data:root /var/www/shaarli.mydomain.org/phpinfo.php
361 sudo chmod 0400 /var/www/shaarli.mydomain.org/phpinfo.php
364 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
366 It is recommended to remove the `phpinfo.php` when no longer needed as it publicly discloses details about your webserver configuration.
369 ## Robots and crawlers
371 To opt-out of indexing your Shaarli instance by search engines, create a `robots.txt` file at the root of your virtualhost:
378 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.
380 - [Robots exclusion standard](https://en.wikipedia.org/wiki/Robots_exclusion_standard)
381 - [Introduction to robots.txt](https://support.google.com/webmasters/answer/6062608?hl=en)
382 - [Robots meta tag, data-nosnippet, and X-Robots-Tag specifications](https://developers.google.com/search/reference/robots_meta_tag)
383 - [About robots.txt](http://www.robotstxt.org)
384 - [About the robots META tag](https://www.robotstxt.org/meta.html)
389 [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:
392 # /etc/fail2ban/filter.d/shaarli-auth.conf
396 failregex = \s-\s<HOST>\s-\sLogin failed for user.*$
401 # /etc/fail2ban/jail.local
405 filter = shaarli-auth
406 logpath = /var/www/shaarli.mydomain.org/data/log.txt
407 # allow 3 login attempts per IP address
408 # (over a period specified by findtime = in /etc/fail2ban/jail.conf)
410 # permanently ban the IP address after reaching the limit
414 Then restart the service: `sudo systemctl restart fail2ban`
418 - [Apache/PHP - error log per VirtualHost - StackOverflow](http://stackoverflow.com/q/176)
419 - [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/)
420 - [Server-side TLS (Apache) - Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache)
421 - [Nginx Beginner's guide](http://nginx.org/en/docs/beginners_guide.html)
422 - [Nginx ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)
423 - [Nginx Pitfalls](http://wiki.nginx.org/Pitfalls)
424 - [Nginx PHP configuration examples - Karl Blessing](http://kbeezie.com/nginx-configuration-examples/)
425 - [Apache 2.4 documentation](https://httpd.apache.org/docs/2.4/)
426 - [Apache mod_proxy](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html)
427 - [Apache Reverse Proxy Request Headers](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#x-headers)
428 - [HAProxy documentation](https://cbonte.github.io/haproxy-dconv/)
429 - [Nginx documentation](https://nginx.org/en/docs/)
430 - [`X-Forwarded-Proto`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Proto)
431 - [`X-Forwarded-Host`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-Host)
432 - [`X-Forwarded-For`](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/X-Forwarded-For)
433 - [Server-side TLS (Nginx) - Mozilla](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx)
434 - [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php)
435 - [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority)
436 - [Travis configuration](https://github.com/shaarli/Shaarli/blob/master/.travis.yml)
437 - [PHP: Supported versions](http://php.net/supported-versions.php)
438 - [PHP: Unsupported versions (EOL/End-of-life)](http://php.net/eol.php)
439 - [PHP 7 Changelog](http://php.net/ChangeLog-7.php)
440 - [PHP 5 Changelog](http://php.net/ChangeLog-5.php)
441 - [PHP: Bugs](https://bugs.php.net/)
442 - [Transport Layer Security](https://en.wikipedia.org/wiki/Transport_Layer_Security)
443 - 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.