[github/shaarli/Shaarli.git] / doc / md / Server-configuration.md

# 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.

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).

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

Supported PHP versions:

Version | Status | Shaarli compatibility
:---:|:---:|:---:
7.2 | Supported | Yes
7.1 | Supported | Yes
7.0 | EOL: 2018-12-03 | Yes (up to Shaarli 0.10.x)
5.6 | EOL: 2018-12-31 | Yes (up to Shaarli 0.10.x)
5.5 | EOL: 2016-07-10 | Yes
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)

Required PHP extensions:

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 | 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`)
[`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)

Some [plugins](Plugins.md) may require additional configuration.


## 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.

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)
 - [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).

In short:

```bash
# install certbot
sudo apt install certbot

# 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

# 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

# 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)

--------------------------------------------------------------------------------

## 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)


### Apache

```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
<VirtualHost *:80>
    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]
</VirtualHost>

<VirtualHost *:443>
    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
    SSLCertificateKeyFile /etc/letsencrypt/live/shaarli.mydomain.org/privkey.pem
    Include /etc/letsencrypt/options-ssl-apache.conf

    # 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

    # Optional, log PHP errors, useful for debugging
    #php_flag  log_errors on
    #php_flag  display_errors on
    #php_value error_reporting 2147483647
    #php_value error_log /var/log/apache2/shaarli-php-error.log

    <Directory /var/www/shaarli.mydomain.org/>
        # Required for .htaccess support
        AllowOverride All
        Order allow,deny
        Allow from all
    </Directory>

    <LocationMatch "/\.">
        # Prevent accessing dotfiles
        RedirectMatch 404 ".*"
    </LocationMatch>

    <LocationMatch "\.(?:ico|css|js|gif|jpe?g|png)$">
        # allow client-side caching of static files
        Header set Cache-Control "max-age=2628000, public, must-revalidate, proxy-revalidate"
    </LocationMatch>

    # serve the Shaarli favicon from its custom location
    Alias favicon.ico /var/www/shaarli.mydomain.org/images/favicon.ico

</VirtualHost>
```

```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

# mod_rewrite must be enabled to use the REST API
# https://httpd.apache.org/docs/current/mod/mod_rewrite.html
sudo a2enmod rewrite

# 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
```

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

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.


```bash
# install nginx and php-fpm
sudo apt update
sudo apt install nginx php-fpm

# Edit the virtualhost configuration file with your favorite editor
sudo nano /etc/nginx/sites-available/shaarli.mydomain.org
```

```nginx
server {
    listen       80;
    server_name  shaarli.mydomain.org;

    # redirect all plain HTTP requests to HTTPS
    return 301 https://shaarli.mydomain.org$request_uri;
}

server {
    listen       443 ssl;
    server_name  shaarli.mydomain.org;
    root         /var/www/shaarli.mydomain.org;

    # 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;

    # 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;

    # 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;

    # 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;
    }

    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;
    }

    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 = /favicon.ico {
        # serve the Shaarli favicon from its custom location
        alias /var/www/shaarli/images/favicon.ico;
    }

    # 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;
    }

}
```

```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
```


## 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.


## Allow import of large browser bookmarks export

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.

- Apache: `/etc/php/<PHP_VERSION>/apache2/php.ini`
- Nginx + PHP-FPM: `/etc/php/<PHP_VERSION>/fpm/php.ini` (in addition to `client_max_body_size` in the [Nginx configuration](#nginx))

```ini
[...]
# (optional) increase the maximum file upload size:
post_max_size = 100M
[...]
# (optional) increase the maximum file upload size:
upload_max_filesize = 100M
```

To verify PHP settings currently set on the server, create a `phpinfo.php` in your webserver's document root

```bash
# example
echo '<?php phpinfo(); ?>' | 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
```

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

It is recommended to remove the `phpinfo.php` when no longer needed as it publicly discloses details about your webserver configuration.


## Robots and crawlers

To opt-out of indexing your Shaarli instance by search engines, create a `robots.txt` file at the root of your virtualhost:

```
User-agent: *
Disallow: /
```

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.

- [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)


## Fail2ban

[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:

```ini
# /etc/fail2ban/filter.d/shaarli-auth.conf
[INCLUDES]
before = common.conf
[Definition]
failregex = \s-\s<HOST>\s-\sLogin failed for user.*$
ignoreregex = 
```

```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
```

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