-*Example virtual host configurations for popular web servers*
-
-- [Apache](#apache)
-- [Nginx](#nginx)
-
-## Prerequisites
-### Shaarli
-* Shaarli is installed in a directory readable/writeable by the user
-* the correct read/write permissions have been granted to the web server _user and/or group_
-* for HTTPS / SSL:
- * a key pair (public, private) and a certificate have been generated
- * the appropriate server SSL extension is installed and active
-
-### HTTPS, TLS and self-signed certificates
-Related guides:
-* [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)
-* Generate a self-signed certificate (will trigger browser warnings) with apache2: `make-ssl-cert generate-default-snakeoil --force-overwrite` will create `/etc/ssl/certs/ssl-cert-snakeoil.pem` and `/etc/ssl/private/ssl-cert-snakeoil.key`
-
-### Proxies
-If Shaarli is served behind a proxy (i.e. there is a proxy server between clients and the web server hosting Shaarli), please refer to the proxy server documentation for proper configuration. In particular, you have to ensure that the following server variables are properly set:
-- `X-Forwarded-Proto`;
-- `X-Forwarded-Host`;
-- `X-Forwarded-For`.
-
-See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues.
-
-## Apache
-### Minimal
-```apache
-<VirtualHost *:80>
- ServerName shaarli.my-domain.org
- DocumentRoot /absolute/path/to/shaarli/
-</VirtualHost>
-```
-### Debug - Log all the things!
-This configuration will log both Apache and PHP errors, which may prove useful to identify server configuration errors.
+# Server configuration
-See:
-* [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow)
-* [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/)
-```apache
-<VirtualHost *:80>
- ServerName shaarli.my-domain.org
- DocumentRoot /absolute/path/to/shaarli/
- LogLevel warn
- ErrorLog /var/log/apache2/shaarli-error.log
- CustomLog /var/log/apache2/shaarli-access.log combined
+## Requirements
- 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
-</VirtualHost>
-```
+### Operating system and web server
-### Standard - Keep access and error logs
-```apache
-<VirtualHost *:80>
- ServerName shaarli.my-domain.org
- DocumentRoot /absolute/path/to/shaarli/
+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.
- LogLevel warn
- ErrorLog /var/log/apache2/shaarli-error.log
- CustomLog /var/log/apache2/shaarli-access.log combined
-</VirtualHost>
-```
+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).
-### Paranoid - Redirect HTTP (:80) to HTTPS (:443)
-See [Server-side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache) (Mozilla).
+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.
-```apache
-<VirtualHost *:443>
- ServerName shaarli.my-domain.org
- DocumentRoot /absolute/path/to/shaarli/
+### Network and domain name
- SSLEngine on
- SSLCertificateFile /absolute/path/to/the/website/certificate.pem
- SSLCertificateKeyFile /absolute/path/to/the/website/key.key
+Try to host the server in a region that is geographically close to your users.
- <Directory /absolute/path/to/shaarli/>
- AllowOverride All
- Options Indexes FollowSymLinks MultiViews
- Order allow,deny
- allow from all
- </Directory>
+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.
- LogLevel warn
- ErrorLog /var/log/apache2/shaarli-error.log
- CustomLog /var/log/apache2/shaarli-access.log combined
-</VirtualHost>
-<VirtualHost *:80>
- ServerName shaarli.my-domain.org
- Redirect 301 / https://shaarli.my-domain.org
+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).
- LogLevel warn
- ErrorLog /var/log/apache2/shaarli-error.log
- CustomLog /var/log/apache2/shaarli-access.log combined
-</VirtualHost>
-```
+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.
-### .htaccess
+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.
-Shaarli use `.htaccess` Apache files to deny access to files that shouldn't be directly accessed (datastore, config, etc.). You need the directive `AllowOverride All` in your virtual host configuration for them to work.
-**Warning**: If you use Apache 2.2 or lower, you need [mod_version](https://httpd.apache.org/docs/current/mod/mod_version.html) to be installed and enabled.
-
-Apache module `mod_rewrite` **must** be enabled to use the REST API. URL rewriting rules for the Slim microframework are stated in the root `.htaccess` file.
+### PHP
-## LightHttpd
+Supported PHP versions:
-## Nginx
-### Foreword
-Nginx does not natively interpret PHP scripts; to this effect, we will run a [FastCGI](https://en.wikipedia.org/wiki/FastCGI) service, to which Nginx's FastCGI module will proxy all requests to PHP resources.
+Version | Status | Shaarli compatibility
+:---:|:---:|:---:
+7.3 | Supported | Yes
+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 packages:
-- [nginx](http://nginx.org)
-- [php-fpm](http://php-fpm.org) - PHP FastCGI Process Manager
+Required PHP extensions:
-Official documentation:
-- [Beginner's guide](http://nginx.org/en/docs/beginners_guide.html)
-- [ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)
-- [Pitfalls](http://wiki.nginx.org/Pitfalls)
+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)
-Community resources:
-- [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla)
-- [PHP configuration examples](http://kbeezie.com/nginx-configuration-examples/) (Karl Blessing)
+Some [plugins](Plugins.md) may require additional configuration.
-### Common setup
-Once Nginx and PHP-FPM are installed, we need to ensure:
-- Nginx and PHP-FPM are running using the _same user and group_
-- both these user and group have
- - `read` permissions for Shaarli resources
- - `execute` permissions for Shaarli directories _AND_ their parent directories
-On a production server:
-- `user:group` will likely be `http:http`, `www:www` or `www-data:www-data`
-- files will be located under `/var/www`, `/var/http` or `/usr/share/nginx`
+## SSL/TLS (HTTPS)
-On a development server:
-- files may be located in a user's home directory
-- in this case, make sure both Nginx and PHP-FPM are running as the local user/group!
+We recommend setting up [HTTPS](https://en.wikipedia.org/wiki/HTTPS) on your webserver for secure communication between clients and the server.
-For all following configuration examples, this user/group pair will be used:
-- `user:group = john:users`,
+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.
-which corresponds to the following service configuration:
+ - [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).
-```ini
-; /etc/php/php-fpm.conf
-user = john
-group = users
+In short:
-[...]
-listen.owner = john
-listen.group = users
-```
+```bash
+# install certbot
+sudo apt install certbot
-```nginx
-# /etc/nginx/nginx.conf
-user john users;
+# 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
-http {
- [...]
-}
+# generate initial certificates - Let's Encrypt ACME servers must be able to access your server!
+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
```
-### (Optional) Increase the maximum file upload size
-Some bookmark dumps generated by web browsers can be _huge_ due to the presence of Base64-encoded images and favicons, as well as extra verbosity when nesting links in (sub-)folders.
+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:
-To increase upload size, you will need to modify both nginx and PHP configuration:
+- [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)
-```nginx
-# /etc/nginx/nginx.conf
+--------------------------------------------------------------------------------
-http {
- [...]
+## Examples
- client_max_body_size 10m;
+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/
```
-```ini
-# /etc/php5/fpm/php.ini
+You can install Shaarli at the root of your virtualhost, or in a subdirectory as well. See [Directory structure](Directory-structure)
-[...]
-post_max_size = 10M
-[...]
-upload_max_filesize = 10M
-```
-### Minimal
-_WARNING: Use for development only!_
+### Apache
-```nginx
-user john users;
-worker_processes 1;
-events {
- worker_connections 1024;
-}
+```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
-http {
- include mime.types;
- default_type application/octet-stream;
- keepalive_timeout 20;
-
- index index.html index.php;
-
- server {
- listen 80;
- server_name localhost;
- root /home/john/web;
-
- access_log /var/log/nginx/access.log;
- error_log /var/log/nginx/error.log;
-
- location /shaarli/ {
- try_files $uri /shaarli/index.php$is_args$args;
- access_log /var/log/nginx/shaarli.access.log;
- error_log /var/log/nginx/shaarli.error.log;
- }
-
- location ~ (index)\.php$ {
- try_files $uri =404;
- fastcgi_split_path_info ^(.+\.php)(/.+)$;
- fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
- fastcgi_index index.php;
- include fastcgi.conf;
- }
- }
-}
+# Edit the virtualhost configuration file with your favorite editor
+sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf
```
-### Modular
-The previous setup is sufficient for development purposes, but has several major caveats:
-- every content that does not match the PHP rule will be sent to client browsers:
- - dotfiles - in our case, `.htaccess`
- - temporary files, e.g. Vim or Emacs files: `index.php~`
-- asset / static resource caching is not optimized
-- if serving several PHP sites, there will be a lot of duplication: `location /shaarli/`, `location /mysite/`, etc.
+```apache
+<VirtualHost *:80>
+ ServerName shaarli.mydomain.org
+ DocumentRoot /var/www/shaarli.mydomain.org/
-To solve this, we will split Nginx configuration in several parts, that will be included when needed:
+ # 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>
-```nginx
-# /etc/nginx/deny.conf
-location ~ /\. {
- # deny access to dotfiles
- access_log off;
- log_not_found off;
- deny all;
-}
+<VirtualHost *:443>
+ ServerName shaarli.mydomain.org
+ DocumentRoot /var/www/shaarli.mydomain.org/
-location ~ ~$ {
- # deny access to temp editor files, e.g. "script.php~"
- access_log off;
- log_not_found off;
- deny all;
-}
+ # 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
+
+ # Let's Encrypt settings from https://github.com/certbot/certbot/blob/master/certbot-apache/certbot_apache/_internal/tls_configs/current-options-ssl-apache.conf
+ SSLProtocol all -SSLv2 -SSLv3 -TLSv1 -TLSv1.1
+ 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
+ SSLHonorCipherOrder off
+ SSLSessionTickets off
+ SSLOptions +StrictRequire
+
+ # 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>
```
-```nginx
-# /etc/nginx/php.conf
-location ~ (index)\.php$ {
- # Slim - split URL path into (script_filename, path_info)
- try_files $uri =404;
- fastcgi_split_path_info ^(.+\.php)(/.+)$;
-
- # filter and proxy PHP requests to PHP-FPM
- fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
- fastcgi_index index.php;
- include fastcgi.conf;
-}
+```bash
+# Enable the virtualhost
+sudo a2ensite shaarli
-location ~ \.php$ {
- # deny access to all other PHP scripts
- deny all;
-}
+# 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
```
-```nginx
-# /etc/nginx/static_assets.conf
-location ~* \.(?:ico|css|js|gif|jpe?g|png)$ {
- expires max;
- add_header Pragma public;
- add_header Cache-Control "public, must-revalidate, proxy-revalidate";
-}
+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
-# /etc/nginx/nginx.conf
-[...]
+server {
+ listen 80;
+ server_name shaarli.mydomain.org;
-http {
- [...]
+ # 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;
- root /home/john/web;
- access_log /var/log/nginx/access.log;
+ # 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;
- server {
- # virtual host for a first domain
- listen 80;
- server_name my.first.domain.org;
+ # 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;
- location /shaarli/ {
- # Slim - rewrite URLs
- try_files $uri /shaarli/index.php$is_args$args;
+ # 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;
+ }
- access_log /var/log/nginx/shaarli.access.log;
- error_log /var/log/nginx/shaarli.error.log;
- }
+ 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 = /shaarli/favicon.ico {
- # serve the Shaarli favicon from its custom location
- alias /var/www/shaarli/images/favicon.ico;
- }
+ location ~ \.php$ {
+ # deny access to all other PHP scripts
+ # disable this if you host other PHP applications on the same virtualhost
+ deny all;
+ }
- include deny.conf;
- include static_assets.conf;
- include php.conf;
+ location ~ /\. {
+ # deny access to dotfiles
+ deny all;
}
- server {
- # virtual host for a second domain
- listen 80;
- server_name second.domain.com;
+ location ~ ~$ {
+ # deny access to temp editor files, e.g. "script.php~"
+ deny all;
+ }
- location /minigal/ {
- access_log /var/log/nginx/minigal.access.log;
- error_log /var/log/nginx/minigal.error.log;
- }
+ location = /favicon.ico {
+ # serve the Shaarli favicon from its custom location
+ alias /var/www/shaarli/images/favicon.ico;
+ }
- include deny.conf;
- include static_assets.conf;
- include php.conf;
+ # 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;
}
+
}
```
-### Redirect HTTP to HTTPS
-Assuming you have generated a (self-signed) key and certificate, and they are located under `/home/john/ssl/localhost.{key,crt}`, it is pretty straightforward to set an HTTP (:80) to HTTPS (:443) redirection to force SSL/TLS usage.
+```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
+```
+
-```nginx
-# /etc/nginx/nginx.conf
+## 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
+```
-http {
- [...]
+To verify PHP settings currently set on the server, create a `phpinfo.php` in your webserver's document root
- index index.html index.php;
+```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
+```
- root /home/john/web;
- access_log /var/log/nginx/access.log;
- error_log /var/log/nginx/error.log;
+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
- server {
- listen 80;
- server_name localhost;
+It is recommended to remove the `phpinfo.php` when no longer needed as it publicly discloses details about your webserver configuration.
- return 301 https://localhost$request_uri;
- }
- server {
- listen 443 ssl;
- server_name localhost;
+## Robots and crawlers
- ssl_certificate /home/john/ssl/localhost.crt;
- ssl_certificate_key /home/john/ssl/localhost.key;
+To opt-out of indexing your Shaarli instance by search engines, create a `robots.txt` file at the root of your virtualhost:
- location /shaarli/ {
- # Slim - rewrite URLs
- try_files $uri /index.php$is_args$args;
+```
+User-agent: *
+Disallow: /
+```
- access_log /var/log/nginx/shaarli.access.log;
- error_log /var/log/nginx/shaarli.error.log;
- }
+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.
- location = /shaarli/favicon.ico {
- # serve the Shaarli favicon from its custom location
- alias /var/www/shaarli/images/favicon.ico;
- }
+- [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)
- include deny.conf;
- include static_assets.conf;
- include php.conf;
- }
-}
+
+## 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.
+
+
projects / github / shaarli / Shaarli.git / blobdiff