2 *Example virtual host configurations for popular web servers*
4 - [Apache](#apache)[](.html)
5 - [LightHttpd](#lighthttpd) (empty)[](.html)
6 - [Nginx](#nginx)[](.html)
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_
12 * a key pair (public, private) and a certificate have been generated
13 * the appropriate server SSL extension is installed and active
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)
23 ServerName shaarli.my-domain.org
24 DocumentRoot /absolute/path/to/shaarli/
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.
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)
36 ServerName shaarli.my-domain.org
37 DocumentRoot /absolute/path/to/shaarli/
40 ErrorLog /var/log/apache2/shaarli-error.log
41 CustomLog /var/log/apache2/shaarli-access.log combined
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
50 ### Standard - Keep access and error logs
53 ServerName shaarli.my-domain.org
54 DocumentRoot /absolute/path/to/shaarli/
57 ErrorLog /var/log/apache2/shaarli-error.log
58 CustomLog /var/log/apache2/shaarli-access.log combined
62 ### Paranoid - Redirect HTTP (:80) to HTTPS (:443)
63 See [Server-side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache) (Mozilla).[](.html)
67 ServerName shaarli.my-domain.org
68 DocumentRoot /absolute/path/to/shaarli/
71 SSLCertificateFile /absolute/path/to/the/website/certificate.crt
72 SSLCertificateKeyFile /absolute/path/to/the/website/key.key
74 <Directory /absolute/path/to/shaarli/>
76 Options Indexes FollowSymLinks MultiViews
82 ErrorLog /var/log/apache2/shaarli-error.log
83 CustomLog /var/log/apache2/shaarli-access.log combined
86 ServerName shaarli.my-domain.org
87 Redirect 301 / https://shaarli.my-domain.org
90 ErrorLog /var/log/apache2/shaarli-error.log
91 CustomLog /var/log/apache2/shaarli-access.log combined
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)
102 - [nginx](http://nginx.org)[](.html)
103 - [php-fpm](http://php-fpm.org) - PHP FastCGI Process Manager[](.html)
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)
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)
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
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`
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!
129 For all following examples, a development configuration will be used:
130 - `user:group = john:users`,
132 which corresponds to the following service configuration:
135 ; /etc/php/php-fpm.conf
145 # /etc/nginx/nginx.conf
154 _WARNING: Use for development only!_
160 worker_connections 1024;
165 default_type application/octet-stream;
166 keepalive_timeout 20;
168 index index.html index.php;
172 server_name localhost;
175 access_log /var/log/nginx/access.log;
176 error_log /var/log/nginx/error.log;
179 access_log /var/log/nginx/shaarli.access.log;
180 error_log /var/log/nginx/shaarli.error.log;
183 location ~ (index)\.php$ {
184 fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
185 fastcgi_index index.php;
186 include fastcgi.conf;
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.
200 To solve this, we will split Nginx configuration in several parts, that will be included when needed:
203 # /etc/nginx/deny.conf
205 # deny access to dotfiles
212 # deny access to temp editor files, e.g. "script.php~"
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;
229 # deny access to all other PHP scripts
235 # /etc/nginx/static_assets.conf
236 location ~* \.(?:ico|css|js|gif|jpe?g|png)$ {
238 add_header Pragma public;
239 add_header Cache-Control "public, must-revalidate, proxy-revalidate";
244 # /etc/nginx/nginx.conf
251 access_log /var/log/nginx/access.log;
252 error_log /var/log/nginx/error.log;
255 # virtual host for a first domain
257 server_name my.first.domain.org;
260 access_log /var/log/nginx/shaarli.access.log;
261 error_log /var/log/nginx/shaarli.error.log;
265 include static_assets.conf;
270 # virtual host for a second domain
272 server_name second.domain.com;
275 access_log /var/log/nginx/minigal.access.log;
276 error_log /var/log/nginx/minigal.error.log;
280 include static_assets.conf;
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.
290 # /etc/nginx/nginx.conf
296 index index.html index.php;
299 access_log /var/log/nginx/access.log;
300 error_log /var/log/nginx/error.log;
304 server_name localhost;
306 return 301 https://localhost$request_uri;
311 server_name localhost;
313 ssl_certificate /home/john/ssl/localhost.crt;
314 ssl_certificate_key /home/john/ssl/localhost.key;
317 access_log /var/log/nginx/shaarli.access.log;
318 error_log /var/log/nginx/shaarli.error.log;
322 include static_assets.conf;