doc/Server-configuration.md

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