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

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

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

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

### HTTPS, TLS and self-signed certificates
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)
* 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`

### Proxies
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:
- `X-Forwarded-Proto`;
- `X-Forwarded-Host`;
- `X-Forwarded-For`.

See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues.[](.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](https://ma.ttias.be/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.pem
    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$ {
    # filter and proxy PHP requests to PHP-FPM
    fastcgi_pass   unix:/var/run/php-fpm/php-fpm.sock;
    fastcgi_index  index.php;
    include        fastcgi.conf;
}

location ~ \.php$ {
    # deny access to all other PHP scripts
    deny all;
}
```

```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
	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	## LightHttpd
	106
	107	## Nginx
	108	### Foreword
	109	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)
	110
	111	Required packages:
	112	- [nginx](http://nginx.org)[](.html)
	113	- [php-fpm](http://php-fpm.org) - PHP FastCGI Process Manager[](.html)
	114
	115	Official documentation:
	116	- [Beginner's guide](http://nginx.org/en/docs/beginners_guide.html)[](.html)
	117	- [ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)[](.html)
	118	- [Pitfalls](http://wiki.nginx.org/Pitfalls)[](.html)
	119
	120	Community resources:
	121	- [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla)[](.html)
	122	- [PHP configuration examples](http://kbeezie.com/nginx-configuration-examples/) (Karl Blessing)[](.html)
	123
	124	### Common setup
	125	Once Nginx and PHP-FPM are installed, we need to ensure:
	126	- Nginx and PHP-FPM are running using the _same user and group_
	127	- both these user and group have
	128	- `read` permissions for Shaarli resources
	129	- `execute` permissions for Shaarli directories _AND_ their parent directories
	130
	131	On a production server:
	132	- `user:group` will likely be `http:http`, `www:www` or `www-data:www-data`
	133	- files will be located under `/var/www`, `/var/http` or `/usr/share/nginx`
	134
	135	On a development server:
	136	- files may be located in a user's home directory
	137	- in this case, make sure both Nginx and PHP-FPM are running as the local user/group!
	138
	139	For all following examples, a development configuration will be used:
	140	- `user:group = john:users`,
	141
	142	which corresponds to the following service configuration:
	143
	144	```ini
	145	; /etc/php/php-fpm.conf
	146	user = john
	147	group = users
	148
	149	[...][](.html)
	150	listen.owner = john
	151	listen.group = users
	152	```
	153
	154	```nginx
	155	# /etc/nginx/nginx.conf
	156	user john users;
	157
	158	http {
	159	[...][](.html)
	160	}
	161	```
	162
	163	### Minimal
	164	_WARNING: Use for development only!_
	165
	166	```nginx
	167	user john users;
	168	worker_processes 1;
	169	events {
	170	worker_connections 1024;
	171	}
	172
	173	http {
	174	include mime.types;
	175	default_type application/octet-stream;
	176	keepalive_timeout 20;
	177
	178	index index.html index.php;
	179
	180	server {
	181	listen 80;
	182	server_name localhost;
	183	root /home/john/web;
	184
	185	access_log /var/log/nginx/access.log;
	186	error_log /var/log/nginx/error.log;
	187
	188	location /shaarli/ {
	189	access_log /var/log/nginx/shaarli.access.log;
	190	error_log /var/log/nginx/shaarli.error.log;
	191	}
	192
	193	location ~ (index)\.php$ {
	194	fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
	195	fastcgi_index index.php;
	196	include fastcgi.conf;
	197	}
	198	}
	199	}
	200	```
	201
	202	### Modular
	203	The previous setup is sufficient for development purposes, but has several major caveats:
	204	- every content that does not match the PHP rule will be sent to client browsers:
	205	- dotfiles - in our case, `.htaccess`
	206	- temporary files, e.g. Vim or Emacs files: `index.php~`
	207	- asset / static resource caching is not optimized
	208	- if serving several PHP sites, there will be a lot of duplication: `location /shaarli/`, `location /mysite/`, etc.
	209
	210	To solve this, we will split Nginx configuration in several parts, that will be included when needed:
	211
	212	```nginx
	213	# /etc/nginx/deny.conf
	214	location ~ /\. {
	215	# deny access to dotfiles
	216	access_log off;
	217	log_not_found off;
	218	deny all;
	219	}
	220
	221	location ~ ~$ {
	222	# deny access to temp editor files, e.g. "script.php~"
	223	access_log off;
	224	log_not_found off;
	225	deny all;
	226	}
	227	```
	228
	229	```nginx
	230	# /etc/nginx/php.conf
	231	location ~ (index)\.php$ {
	232	# filter and proxy PHP requests to PHP-FPM
	233	fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
	234	fastcgi_index index.php;
	235	include fastcgi.conf;
	236	}
	237
	238	location ~ \.php$ {
	239	# deny access to all other PHP scripts
	240	deny all;
	241	}
	242	```
	243
	244	```nginx
	245	# /etc/nginx/static_assets.conf
	246	location ~* \.(?:ico\|css\|js\|gif\|jpe?g\|png)$ {
	247	expires max;
	248	add_header Pragma public;
	249	add_header Cache-Control "public, must-revalidate, proxy-revalidate";
	250	}
	251	```
	252
	253	```nginx
	254	# /etc/nginx/nginx.conf
	255	[...][](.html)
	256
	257	http {
	258	[...][](.html)
	259
	260	root /home/john/web;
	261	access_log /var/log/nginx/access.log;
	262	error_log /var/log/nginx/error.log;
	263
	264	server {
	265	# virtual host for a first domain
	266	listen 80;
	267	server_name my.first.domain.org;
	268
	269	location /shaarli/ {
	270	access_log /var/log/nginx/shaarli.access.log;
	271	error_log /var/log/nginx/shaarli.error.log;
	272	}
	273
	274	include deny.conf;
	275	include static_assets.conf;
	276	include php.conf;
	277	}
	278
	279	server {
	280	# virtual host for a second domain
	281	listen 80;
	282	server_name second.domain.com;
	283
	284	location /minigal/ {
	285	access_log /var/log/nginx/minigal.access.log;
	286	error_log /var/log/nginx/minigal.error.log;
	287	}
	288
	289	include deny.conf;
	290	include static_assets.conf;
	291	include php.conf;
	292	}
	293	}
	294	```
	295
	296	### Redirect HTTP to HTTPS
	297	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.
	298
	299	```nginx
	300	# /etc/nginx/nginx.conf
	301	[...][](.html)
	302
	303	http {
	304	[...][](.html)
	305
	306	index index.html index.php;
	307
	308	root /home/john/web;
	309	access_log /var/log/nginx/access.log;
	310	error_log /var/log/nginx/error.log;
	311
	312	server {
	313	listen 80;
	314	server_name localhost;
	315
	316	return 301 https://localhost$request_uri;
	317	}
	318
	319	server {
	320	listen 443 ssl;
	321	server_name localhost;
	322
	323	ssl_certificate /home/john/ssl/localhost.crt;
	324	ssl_certificate_key /home/john/ssl/localhost.key;
	325
	326	location /shaarli/ {
	327	access_log /var/log/nginx/shaarli.access.log;
	328	error_log /var/log/nginx/shaarli.error.log;
	329	}
	330
	331	include deny.conf;
	332	include static_assets.conf;
	333	include php.conf;
	334	}
	335	}
	336	```