2 - [Prerequisites](#prerequisistes)
6 - [See also](#see-also)
11 - A web server and PHP interpreter module/service have been installed.
12 - You have write access to the Shaarli installation directory.
13 - The correct read/write permissions have been granted to the web server user and group.
14 - Your PHP interpreter is compatible with supported PHP versions:
16 Version | Status | Shaarli compatibility
20 7.0 | EOL: 2018-12-03 | Yes (up to Shaarli 0.10.x)
21 5.6 | EOL: 2018-12-31 | Yes (up to Shaarli 0.10.x)
22 5.5 | EOL: 2016-07-10 | Yes
23 5.4 | EOL: 2015-09-14 | Yes (up to Shaarli 0.8.x)
24 5.3 | EOL: 2014-08-14 | Yes (up to Shaarli 0.8.x)
26 - The following PHP extensions are installed on the server:
28 Extension | Required? | Usage
30 [`openssl`](http://php.net/manual/en/book.openssl.php) | All | OpenSSL, HTTPS
31 [`php-json`](http://php.net/manual/en/book.json.php) | required | configuration parsing
32 [`php-mbstring`](http://php.net/manual/en/book.mbstring.php) | CentOS, Fedora, RHEL, Windows, some hosting providers | multibyte (Unicode) string support
33 [`php-gd`](http://php.net/manual/en/book.image.php) | optional | required to use thumbnails
34 [`php-intl`](http://php.net/manual/en/book.intl.php) | optional | localized text sorting (e.g. `e->รจ->f`)
35 [`php-curl`](http://php.net/manual/en/book.curl.php) | optional | using cURL for fetching webpages and thumbnails in a more robust way
36 [`php-gettext`](http://php.net/manual/en/book.gettext.php) | optional | Use the translation system in gettext mode (faster)
37 --------------------------------------------------------------------------------
39 ### SSL/TLS configuration
41 To setup HTTPS / SSL on your webserver (recommended), you must generate a public/private **key pair** and a **certificate**, and install, configure and activate the appropriate **webserver SSL extension**.
45 [Let's Encrypt](https://en.wikipedia.org/wiki/Let%27s_Encrypt) is a certificate authority that provides free TLS/X.509 certificates via an automated process.
47 * Install `certbot` using the appropriate method described on https://certbot.eff.org/.
49 Location of the `certbot` program and template configuration files may vary depending on which installation method was used. Change the file paths below accordingly. Here is an easy way to create a signed certificate using `certbot`, it assumes `certbot` was installed through APT on a Debian-based distribution:
51 * Stop the apache2/nginx service.
52 * Run `certbot --agree-tos --standalone --preferred-challenges tls-sni --email "youremail@example.com" --domain yourdomain.example.com`
53 * For the Apache webserver, copy `/usr/lib/python2.7/dist-packages/certbot_apache/options-ssl-apache.conf` to `/etc/letsencrypt/options-ssl-apache.conf` (paths may vary depending on installation method)
55 * Setup your webserver as described below
56 * Restart the apache2/nginx service.
58 #### Self-signed certificates
60 If you don't want to request a certificate from Let's Encrypt, or are unable to (for example, webserver on a LAN, or domain name not registered in the public DNS system), you can generate a self-signed certificate. This certificate will trigger security warnings in web browsers, unless you add it to the browser's SSL store manually.
62 * Apache: run `make-ssl-cert generate-default-snakeoil --force-overwrite`
65 --------------------------------------------------------------------------------
69 Here is a basic configuration example for the Apache web server with `mod_php`.
71 In `/etc/apache2/sites-available/shaarli.conf`:
75 ServerName shaarli.my-domain.org
76 DocumentRoot /absolute/path/to/shaarli/
79 # Possible values include: debug, info, notice, warn, error, crit, alert, emerg.
81 ErrorLog /var/log/apache2/shaarli-error.log
82 CustomLog /var/log/apache2/shaarli-access.log combined
84 # Let's Encrypt SSL configuration (recommended)
86 SSLCertificateFile /etc/letsencrypt/live/yourdomain.example.com/fullchain.pem
87 SSLCertificateKeyFile /etc/letsencrypt/live/yourdomain.example.com/privkey.pem
88 Include /etc/letsencrypt/options-ssl-apache.conf
90 # Self-signed SSL cert configuration
92 #SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem
93 #SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
95 # Optional, log PHP errors, useful for debugging
96 #php_flag log_errors on
97 #php_flag display_errors on
98 #php_value error_reporting 2147483647
99 #php_value error_log /var/log/apache2/shaarli-php-error.log
101 <Directory /absolute/path/to/shaarli/>
102 #Required for .htaccess support
107 Options Indexes FollowSymLinks MultiViews #TODO is Indexes/Multiviews required?
109 # Optional - required for playvideos plugin
110 #Header set Content-Security-Policy "script-src 'self' 'unsafe-inline' https://www.youtube.com https://s.ytimg.com 'unsafe-eval'"
116 Enable this configuration with `sudo a2ensite shaarli`
118 _Note: 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._
120 _Note: Apache module `mod_rewrite` must be enabled to use the REST API._
125 Here is a basic configuration example for the Nginx web server, using the [php-fpm](http://php-fpm.org) PHP FastCGI Process Manager, and Nginx's [FastCGI](https://en.wikipedia.org/wiki/FastCGI) module.
127 <!--- TODO refactor everything below this point --->
130 Once Nginx and PHP-FPM are installed, we need to ensure:
132 - Nginx and PHP-FPM are running using the _same user and group_
133 - both these user and group have
134 - `read` permissions for Shaarli resources
135 - `execute` permissions for Shaarli directories _AND_ their parent directories
137 On a production server:
139 - `user:group` will likely be `http:http`, `www:www` or `www-data:www-data`
140 - files will be located under `/var/www`, `/var/http` or `/usr/share/nginx`
142 On a development server:
144 - files may be located in a user's home directory
145 - in this case, make sure both Nginx and PHP-FPM are running as the local user/group!
147 For all following configuration examples, this user/group pair will be used:
149 - `user:group = john:users`,
151 which corresponds to the following service configuration:
154 ; /etc/php/php-fpm.conf
164 # /etc/nginx/nginx.conf
172 ### (Optional) Increase the maximum file upload size
173 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.
175 To increase upload size, you will need to modify both nginx and PHP configuration:
178 # /etc/nginx/nginx.conf
183 client_max_body_size 10m;
190 # /etc/php/<PHP_VERSION>/fpm/php.ini
195 upload_max_filesize = 10M
199 _WARNING: Use for development only!_
205 worker_connections 1024;
210 default_type application/octet-stream;
211 keepalive_timeout 20;
213 index index.html index.php;
217 server_name localhost;
220 access_log /var/log/nginx/access.log;
221 error_log /var/log/nginx/error.log;
224 try_files $uri /shaarli/index.php$is_args$args;
225 access_log /var/log/nginx/shaarli.access.log;
226 error_log /var/log/nginx/shaarli.error.log;
229 location ~ (index)\.php$ {
231 fastcgi_split_path_info ^(.+\.php)(/.+)$;
232 fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
233 fastcgi_index index.php;
234 include fastcgi.conf;
241 The previous setup is sufficient for development purposes, but has several major caveats:
243 - every content that does not match the PHP rule will be sent to client browsers:
244 - dotfiles - in our case, `.htaccess`
245 - temporary files, e.g. Vim or Emacs files: `index.php~`
246 - asset / static resource caching is not optimized
247 - if serving several PHP sites, there will be a lot of duplication: `location /shaarli/`, `location /mysite/`, etc.
249 To solve this, we will split Nginx configuration in several parts, that will be included when needed:
252 # /etc/nginx/deny.conf
254 # deny access to dotfiles
261 # deny access to temp editor files, e.g. "script.php~"
269 # /etc/nginx/php.conf
270 location ~ (index)\.php$ {
271 # Slim - split URL path into (script_filename, path_info)
273 fastcgi_split_path_info ^(.+\.php)(/.+)$;
275 # filter and proxy PHP requests to PHP-FPM
276 fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
277 fastcgi_index index.php;
278 include fastcgi.conf;
282 # deny access to all other PHP scripts
288 # /etc/nginx/static_assets.conf
289 location ~* \.(?:ico|css|js|gif|jpe?g|png)$ {
291 add_header Pragma public;
292 add_header Cache-Control "public, must-revalidate, proxy-revalidate";
297 # /etc/nginx/nginx.conf
304 access_log /var/log/nginx/access.log;
305 error_log /var/log/nginx/error.log;
308 # virtual host for a first domain
310 server_name my.first.domain.org;
313 # Slim - rewrite URLs
314 try_files $uri /shaarli/index.php$is_args$args;
316 access_log /var/log/nginx/shaarli.access.log;
317 error_log /var/log/nginx/shaarli.error.log;
320 location = /shaarli/favicon.ico {
321 # serve the Shaarli favicon from its custom location
322 alias /var/www/shaarli/images/favicon.ico;
326 include static_assets.conf;
331 # virtual host for a second domain
333 server_name second.domain.com;
336 access_log /var/log/nginx/minigal.access.log;
337 error_log /var/log/nginx/minigal.error.log;
341 include static_assets.conf;
347 ### Redirect HTTP to HTTPS
348 Assuming you have generated a (self-signed) key and certificate, and they are
349 located under `/home/john/ssl/localhost.{key,crt}`, it is pretty straightforward
350 to set an HTTP (:80) to HTTPS (:443) redirection to force SSL/TLS usage.
353 # /etc/nginx/nginx.conf
359 index index.html index.php;
362 access_log /var/log/nginx/access.log;
363 error_log /var/log/nginx/error.log;
367 server_name localhost;
369 return 301 https://localhost$request_uri;
374 server_name localhost;
376 ssl_certificate /home/john/ssl/localhost.crt;
377 ssl_certificate_key /home/john/ssl/localhost.key;
380 # Slim - rewrite URLs
381 try_files $uri /index.php$is_args$args;
383 access_log /var/log/nginx/shaarli.access.log;
384 error_log /var/log/nginx/shaarli.error.log;
387 location = /shaarli/favicon.ico {
388 # serve the Shaarli favicon from its custom location
389 alias /var/www/shaarli/images/favicon.ico;
393 include static_assets.conf;
401 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:
403 - `X-Forwarded-Proto`
407 In you [Shaarli configuration](Shaarli-configuration) `data/config.json.php`, add the public IP of your proxy under `security.trusted_proxies`.
409 See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues.
411 ## Robots and crawlers
413 Shaarli disallows indexing and crawling of your local documentation pages by search engines, using `<meta name="robots">` HTML tags.
414 Your Shaarli instance and other pages you host may still be indexed by various robots on the public Internet.
415 You may want to setup a robots.txt file or other crawler control mechanism on your server.
416 See [[1]](https://en.wikipedia.org/wiki/Robots_exclusion_standard), [[2]](https://support.google.com/webmasters/answer/6062608?hl=en) and [[3]](https://developers.google.com/search/reference/robots_meta_tag)
420 * [Server security](Server-security.md)
424 - [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow)
425 - [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/)
426 - [Server-side TLS (Apache)](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache) (Mozilla)
427 - [Nginx Beginner's guide](http://nginx.org/en/docs/beginners_guide.html)
428 - [Nginx ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)
429 - [Nginx Pitfalls](http://wiki.nginx.org/Pitfalls)
430 - [Nginx PHP configuration examples](http://kbeezie.com/nginx-configuration-examples/) (Karl Blessing)
431 - [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla)
432 - [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php)
433 - [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority)
437 - [Travis configuration](https://github.com/shaarli/Shaarli/blob/master/.travis.yml)
438 - [PHP: Supported versions](http://php.net/supported-versions.php)
439 - [PHP: Unsupported versions](http://php.net/eol.php) _(EOL - End Of Life)_
440 - [PHP 7 Changelog](http://php.net/ChangeLog-7.php)
441 - [PHP 5 Changelog](http://php.net/ChangeLog-5.php)
442 - [PHP: Bugs](https://bugs.php.net/)