[github/shaarli/Shaarli.git] / doc / Server-configuration.md

#Server configuration
*Example virtual host configurations for popular web servers*

- [Apache](#apache)[](.html)
- [LightHttpd](#lighthttpd) (empty)[](.html)
- [Nginx](#nginx)[](.html)

## Prerequisites
* 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

Related guides:
* [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php)[](.html)
* [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority)[](.html)

## 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.

See:
* [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow)[](.html)
* [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)

```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

    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>
```

### Standard - Keep access and error logs
```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
</VirtualHost>
```

### Paranoid - Redirect HTTP (:80) to HTTPS (:443)
See [Server-side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache) (Mozilla).[](.html)

```apache
<VirtualHost *:443>
    ServerName   shaarli.my-domain.org
    DocumentRoot /absolute/path/to/shaarli/

    SSLEngine             on
    SSLCertificateFile    /absolute/path/to/the/website/certificate.crt
    SSLCertificateKeyFile /absolute/path/to/the/website/key.key

    <Directory /absolute/path/to/shaarli/>
        AllowOverride All
        Options Indexes FollowSymLinks MultiViews
        Order allow,deny
        allow from all
    </Directory>

    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

    LogLevel  warn
    ErrorLog  /var/log/apache2/shaarli-error.log
    CustomLog /var/log/apache2/shaarli-access.log combined
</VirtualHost>
```

## LightHttpd

## 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.[](.html)

Required packages:
- [nginx](http://nginx.org)[](.html)
- [php-fpm](http://php-fpm.org) - PHP FastCGI Process Manager[](.html)

Official documentation:
- [Beginner's guide](http://nginx.org/en/docs/beginners_guide.html)[](.html)
- [ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)[](.html)
- [Pitfalls](http://wiki.nginx.org/Pitfalls)[](.html)

Community resources:
- [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla)[](.html)
- [PHP configuration examples](http://kbeezie.com/nginx-configuration-examples/) (Karl Blessing)[](.html)

### 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`

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!

For all following examples, a development configuration will be used:
- `user:group = john:users`,

which corresponds to the following service configuration:

```ini
; /etc/php/php-fpm.conf
user = john
group = users

[...][](.html)
listen.owner = john
listen.group = users
```

```nginx
# /etc/nginx/nginx.conf
user john users;

http {
    [...][](.html)
}
```

### Minimal
_WARNING: Use for development only!_ 

```nginx
user john users;
worker_processes  1;
events {
    worker_connections  1024;
}

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/ {
            access_log  /var/log/nginx/shaarli.access.log;
            error_log   /var/log/nginx/shaarli.error.log;
        }

        location ~ (index)\.php$ {
            fastcgi_pass   unix:/var/run/php-fpm/php-fpm.sock;
            fastcgi_index  index.php;
            include        fastcgi.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.

To solve this, we will split Nginx configuration in several parts, that will be included when needed:

```nginx
# /etc/nginx/deny.conf
location ~ /\. {
    # deny access to dotfiles
    access_log off;
    log_not_found off;
    deny all;
}

location ~ ~$ {
    # deny access to temp editor files, e.g. "script.php~"
    access_log off;
    log_not_found off;
    deny all;
}
```

```nginx
# /etc/nginx/php.conf
location ~ (index)\.php$ {
    # proxy PHP requests to PHP-FPM
    fastcgi_pass   unix:/var/run/php-fpm/php-fpm.sock;
    fastcgi_index  index.php;
    include        fastcgi.conf;
}
```

```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";
}
```

```nginx
# /etc/nginx/nginx.conf
[...][](.html)

http {
    [...][](.html)

    root        /home/john/web;
    access_log  /var/log/nginx/access.log;
    error_log   /var/log/nginx/error.log;

    server {
        # virtual host for a first domain
        listen       80;
        server_name  my.first.domain.org;

        location /shaarli/ {
            access_log  /var/log/nginx/shaarli.access.log;
            error_log   /var/log/nginx/shaarli.error.log;
        }

        include deny.conf;
        include static_assets.conf;
        include php.conf;
    }

    server {
        # virtual host for a second domain
        listen       80;
        server_name  second.domain.com;

        location /minigal/ {
            access_log  /var/log/nginx/minigal.access.log;
            error_log   /var/log/nginx/minigal.error.log;
        }

        include deny.conf;
        include static_assets.conf;
        include php.conf;
    }
}
```

### 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.

```nginx
# /etc/nginx/nginx.conf
[...][](.html)

http {
    [...][](.html)

    index index.html index.php;

    root        /home/john/web;
    access_log  /var/log/nginx/access.log;
    error_log   /var/log/nginx/error.log;

    server {
        listen       80;
        server_name  localhost;

        return 301 https://localhost$request_uri;
    }

    server {
        listen       443 ssl;
        server_name  localhost;

        ssl_certificate      /home/john/ssl/localhost.crt;
        ssl_certificate_key  /home/john/ssl/localhost.key;

        location /shaarli/ {
            access_log  /var/log/nginx/shaarli.access.log;
            error_log   /var/log/nginx/shaarli.error.log;
        }

        include deny.conf;
        include static_assets.conf;
        include php.conf;
    }
}
```
Commit	Line	Data
992af0b9 V	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	# 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
229	```nginx
230	# /etc/nginx/static_assets.conf
231	location ~* \.(?:ico\|css\|js\|gif\|jpe?g\|png)$ {
232	expires max;
233	add_header Pragma public;
234	add_header Cache-Control "public, must-revalidate, proxy-revalidate";
235	}
236	```
237
238	```nginx
239	# /etc/nginx/nginx.conf
240	[...][](.html)
241
242	http {
243	[...][](.html)
244
245	root /home/john/web;
246	access_log /var/log/nginx/access.log;
247	error_log /var/log/nginx/error.log;
248
249	server {
250	# virtual host for a first domain
251	listen 80;
252	server_name my.first.domain.org;
253
254	location /shaarli/ {
255	access_log /var/log/nginx/shaarli.access.log;
256	error_log /var/log/nginx/shaarli.error.log;
257	}
258
259	include deny.conf;
260	include static_assets.conf;
261	include php.conf;
262	}
263
264	server {
265	# virtual host for a second domain
266	listen 80;
267	server_name second.domain.com;
268
269	location /minigal/ {
270	access_log /var/log/nginx/minigal.access.log;
271	error_log /var/log/nginx/minigal.error.log;
272	}
273
274	include deny.conf;
275	include static_assets.conf;
276	include php.conf;
277	}
278	}
279	```
280
281	### Redirect HTTP to HTTPS
282	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.
283
284	```nginx
285	# /etc/nginx/nginx.conf
286	[...][](.html)
287
288	http {
289	[...][](.html)
290
291	index index.html index.php;
292
293	root /home/john/web;
294	access_log /var/log/nginx/access.log;
295	error_log /var/log/nginx/error.log;
296
297	server {
298	listen 80;
299	server_name localhost;
300
301	return 301 https://localhost$request_uri;
302	}
303
304	server {
305	listen 443 ssl;
306	server_name localhost;
307
308	ssl_certificate /home/john/ssl/localhost.crt;
309	ssl_certificate_key /home/john/ssl/localhost.key;
310
311	location /shaarli/ {
312	access_log /var/log/nginx/shaarli.access.log;
313	error_log /var/log/nginx/shaarli.error.log;
314	}
315
316	include deny.conf;
317	include static_assets.conf;
318	include php.conf;
319	}
320	}
321	```