doc/Server-configuration.md

   1 #Server configuration
   2 *Example virtual host configurations for popular web servers*
   3
   4 - [Apache](#apache)[](.html)
   5 - [Nginx](#nginx)[](.html)
   6
   7 ## Prerequisites
   8 ### Shaarli
   9 * Shaarli is installed in a directory readable/writeable by the user
  10 * the correct read/write permissions have been granted to the web server _user and/or group_
  11 * for HTTPS / SSL:
  12  * a key pair (public, private) and a certificate have been generated
  13  * the appropriate server SSL extension is installed and active
  14
  15 ### HTTPS, TLS and self-signed certificates
  16 Related guides:
  17 * [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php)[](.html)
  18 * [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority)[](.html)
  19 * 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`
  20
  21 ### Proxies
  22 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:
  23 - `X-Forwarded-Proto`;
  24 - `X-Forwarded-Host`;
  25 - `X-Forwarded-For`.
  26
  27 See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues.[](.html)
  28
  29 ## Apache
  30 ### Minimal
  31 ```apache
  32 <VirtualHost *:80>
  33     ServerName   shaarli.my-domain.org
  34     DocumentRoot /absolute/path/to/shaarli/
  35 </VirtualHost>
  36 ```
  37 ### Debug - Log all the things!
  38 This configuration will log both Apache and PHP errors, which may prove useful to identify server configuration errors.
  39
  40 See:
  41 * [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow)[](.html)
  42 * [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/)[](.html)
  43
  44 ```apache
  45 <VirtualHost *:80>
  46     ServerName   shaarli.my-domain.org
  47     DocumentRoot /absolute/path/to/shaarli/
  48
  49     LogLevel  warn
  50     ErrorLog  /var/log/apache2/shaarli-error.log
  51     CustomLog /var/log/apache2/shaarli-access.log combined
  52
  53     php_flag  log_errors on
  54     php_flag  display_errors on
  55     php_value error_reporting 2147483647
  56     php_value error_log /var/log/apache2/shaarli-php-error.log
  57 </VirtualHost>
  58 ```
  59
  60 ### Standard - Keep access and error logs
  61 ```apache
  62 <VirtualHost *:80>
  63     ServerName   shaarli.my-domain.org
  64     DocumentRoot /absolute/path/to/shaarli/
  65
  66     LogLevel  warn
  67     ErrorLog  /var/log/apache2/shaarli-error.log
  68     CustomLog /var/log/apache2/shaarli-access.log combined
  69 </VirtualHost>
  70 ```
  71
  72 ### Paranoid - Redirect HTTP (:80) to HTTPS (:443)
  73 See [Server-side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache) (Mozilla).[](.html)
  74
  75 ```apache
  76 <VirtualHost *:443>
  77     ServerName   shaarli.my-domain.org
  78     DocumentRoot /absolute/path/to/shaarli/
  79
  80     SSLEngine             on
  81     SSLCertificateFile    /absolute/path/to/the/website/certificate.pem
  82     SSLCertificateKeyFile /absolute/path/to/the/website/key.key
  83
  84     <Directory /absolute/path/to/shaarli/>
  85         AllowOverride All
  86         Options Indexes FollowSymLinks MultiViews
  87         Order allow,deny
  88         allow from all
  89     </Directory>
  90
  91     LogLevel  warn
  92     ErrorLog  /var/log/apache2/shaarli-error.log
  93     CustomLog /var/log/apache2/shaarli-access.log combined
  94 </VirtualHost>
  95 <VirtualHost *:80>
  96     ServerName   shaarli.my-domain.org
  97     Redirect 301 / https://shaarli.my-domain.org
  98
  99     LogLevel  warn
 100     ErrorLog  /var/log/apache2/shaarli-error.log
 101     CustomLog /var/log/apache2/shaarli-access.log combined
 102 </VirtualHost>
 103 ```
 104
 105 ### .htaccess
 106
 107 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.
 108
 109 **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.[](.html)
 110
 111 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.
 112
 113 ## LightHttpd
 114
 115 ## Nginx
 116 ### Foreword
 117 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.[](.html)
 118
 119 Required packages:
 120 - [nginx](http://nginx.org)[](.html)
 121 - [php-fpm](http://php-fpm.org) - PHP FastCGI Process Manager[](.html)
 122
 123 Official documentation:
 124 - [Beginner's guide](http://nginx.org/en/docs/beginners_guide.html)[](.html)
 125 - [ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)[](.html)
 126 - [Pitfalls](http://wiki.nginx.org/Pitfalls)[](.html)
 127
 128 Community resources:
 129 - [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla)[](.html)
 130 - [PHP configuration examples](http://kbeezie.com/nginx-configuration-examples/) (Karl Blessing)[](.html)
 131
 132 ### Common setup
 133 Once Nginx and PHP-FPM are installed, we need to ensure:
 134 - Nginx and PHP-FPM are running using the _same user and group_
 135 - both these user and group have
 136     - `read` permissions for Shaarli resources
 137     - `execute` permissions for Shaarli directories _AND_ their parent directories
 138
 139 On a production server:
 140 - `user:group` will likely be `http:http`, `www:www` or `www-data:www-data`
 141 - files will be located under `/var/www`, `/var/http` or `/usr/share/nginx`
 142
 143 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!
 146
 147 For all following configuration examples, this user/group pair will be used:
 148 - `user:group = john:users`,
 149
 150 which corresponds to the following service configuration:
 151
 152 ```ini
 153 ; /etc/php/php-fpm.conf
 154 user = john
 155 group = users
 156
 157 [...][](.html)
 158 listen.owner = john
 159 listen.group = users
 160 ```
 161
 162 ```nginx
 163 # /etc/nginx/nginx.conf
 164 user john users;
 165
 166 http {
 167     [...][](.html)
 168 }
 169 ```
 170
 171 ### (Optional) Increase the maximum file upload size
 172 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.
 173
 174 To increase upload size, you will need to modify both nginx and PHP configuration:
 175
 176 ```nginx
 177 # /etc/nginx/nginx.conf
 178
 179 http {
 180     [...][](.html)
 181
 182     client_max_body_size 10m;
 183
 184     [...][](.html)
 185 }
 186 ```
 187
 188 ```ini
 189 # /etc/php5/fpm/php.ini
 190
 191 [...][](.html)
 192 post_max_size = 10M
 193 [...][](.html)
 194 upload_max_filesize = 10M
 195 ```
 196
 197 ### Minimal
 198 _WARNING: Use for development only!_
 199
 200 ```nginx
 201 user john users;
 202 worker_processes  1;
 203 events {
 204     worker_connections  1024;
 205 }
 206
 207 http {
 208     include            mime.types;
 209     default_type       application/octet-stream;
 210     keepalive_timeout  20;
 211
 212     index index.html index.php;
 213
 214     server {
 215         listen       80;
 216         server_name  localhost;
 217         root         /home/john/web;
 218
 219         access_log  /var/log/nginx/access.log;
 220         error_log   /var/log/nginx/error.log;
 221
 222         location /shaarli/ {
 223             try_files $uri /shaarli/index.php$is_args$args;
 224             access_log  /var/log/nginx/shaarli.access.log;
 225             error_log   /var/log/nginx/shaarli.error.log;
 226         }
 227
 228         location ~ (index)\.php$ {
 229             try_files $uri =404;
 230             fastcgi_split_path_info ^(.+\.php)(/.+)$;
 231             fastcgi_pass   unix:/var/run/php-fpm/php-fpm.sock;
 232             fastcgi_index  index.php;
 233             include        fastcgi.conf;
 234         }
 235     }
 236 }
 237 ```
 238
 239 ### Modular
 240 The previous setup is sufficient for development purposes, but has several major caveats:
 241 - every content that does not match the PHP rule will be sent to client browsers:
 242     - dotfiles - in our case, `.htaccess`
 243     - temporary files, e.g. Vim or Emacs files: `index.php~`
 244 - asset / static resource caching is not optimized
 245 - if serving several PHP sites, there will be a lot of duplication: `location /shaarli/`, `location /mysite/`, etc.
 246
 247 To solve this, we will split Nginx configuration in several parts, that will be included when needed:
 248
 249 ```nginx
 250 # /etc/nginx/deny.conf
 251 location ~ /\. {
 252     # deny access to dotfiles
 253     access_log off;
 254     log_not_found off;
 255     deny all;
 256 }
 257
 258 location ~ ~$ {
 259     # deny access to temp editor files, e.g. "script.php~"
 260     access_log off;
 261     log_not_found off;
 262     deny all;
 263 }
 264 ```
 265
 266 ```nginx
 267 # /etc/nginx/php.conf
 268 location ~ (index)\.php$ {
 269     # Slim - split URL path into (script_filename, path_info)
 270     try_files $uri =404;
 271     fastcgi_split_path_info ^(.+\.php)(/.+)$;
 272
 273     # filter and proxy PHP requests to PHP-FPM
 274     fastcgi_pass   unix:/var/run/php-fpm/php-fpm.sock;
 275     fastcgi_index  index.php;
 276     include        fastcgi.conf;
 277 }
 278
 279 location ~ \.php$ {
 280     # deny access to all other PHP scripts
 281     deny all;
 282 }
 283 ```
 284
 285 ```nginx
 286 # /etc/nginx/static_assets.conf
 287 location ~* \.(?:ico|css|js|gif|jpe?g|png)$ {
 288     expires    max;
 289     add_header Pragma public;
 290     add_header Cache-Control "public, must-revalidate, proxy-revalidate";
 291 }
 292 ```
 293
 294 ```nginx
 295 # /etc/nginx/nginx.conf
 296 [...][](.html)
 297
 298 http {
 299     [...][](.html)
 300
 301     root        /home/john/web;
 302     access_log  /var/log/nginx/access.log;
 303     error_log   /var/log/nginx/error.log;
 304
 305     server {
 306         # virtual host for a first domain
 307         listen       80;
 308         server_name  my.first.domain.org;
 309
 310         location /shaarli/ {
 311             # Slim - rewrite URLs
 312             try_files $uri /shaarli/index.php$is_args$args;
 313
 314             access_log  /var/log/nginx/shaarli.access.log;
 315             error_log   /var/log/nginx/shaarli.error.log;
 316         }
 317
 318         location = /shaarli/favicon.ico {
 319             # serve the Shaarli favicon from its custom location
 320             alias /var/www/shaarli/images/favicon.ico;
 321         }
 322
 323         include deny.conf;
 324         include static_assets.conf;
 325         include php.conf;
 326     }
 327
 328     server {
 329         # virtual host for a second domain
 330         listen       80;
 331         server_name  second.domain.com;
 332
 333         location /minigal/ {
 334             access_log  /var/log/nginx/minigal.access.log;
 335             error_log   /var/log/nginx/minigal.error.log;
 336         }
 337
 338         include deny.conf;
 339         include static_assets.conf;
 340         include php.conf;
 341     }
 342 }
 343 ```
 344
 345 ### Redirect HTTP to HTTPS
 346 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.
 347
 348 ```nginx
 349 # /etc/nginx/nginx.conf
 350 [...][](.html)
 351
 352 http {
 353     [...][](.html)
 354
 355     index index.html index.php;
 356
 357     root        /home/john/web;
 358     access_log  /var/log/nginx/access.log;
 359     error_log   /var/log/nginx/error.log;
 360
 361     server {
 362         listen       80;
 363         server_name  localhost;
 364
 365         return 301 https://localhost$request_uri;
 366     }
 367
 368     server {
 369         listen       443 ssl;
 370         server_name  localhost;
 371
 372         ssl_certificate      /home/john/ssl/localhost.crt;
 373         ssl_certificate_key  /home/john/ssl/localhost.key;
 374
 375         location /shaarli/ {
 376             # Slim - rewrite URLs
 377             try_files $uri /index.php$is_args$args;
 378
 379             access_log  /var/log/nginx/shaarli.access.log;
 380             error_log   /var/log/nginx/shaarli.error.log;
 381         }
 382
 383         location = /shaarli/favicon.ico {
 384             # serve the Shaarli favicon from its custom location
 385             alias /var/www/shaarli/images/favicon.ico;
 386         }
 387
 388         include deny.conf;
 389         include static_assets.conf;
 390         include php.conf;
 391     }
 392 }
 393 ```