aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/md/Server-configuration.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/md/Server-configuration.md')
-rw-r--r--doc/md/Server-configuration.md42
1 files changed, 28 insertions, 14 deletions
diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md
index 23fdbc8b..25dd49fe 100644
--- a/doc/md/Server-configuration.md
+++ b/doc/md/Server-configuration.md
@@ -5,23 +5,26 @@
5 5
6## Prerequisites 6## Prerequisites
7### Shaarli 7### Shaarli
8* Shaarli is installed in a directory readable/writeable by the user 8- Shaarli is installed in a directory readable/writeable by the user
9* the correct read/write permissions have been granted to the web server _user and/or group_ 9- the correct read/write permissions have been granted to the web server _user and/or group_
10* for HTTPS / SSL: 10- for HTTPS / SSL:
11 * a key pair (public, private) and a certificate have been generated 11 - a key pair (public, private) and a certificate have been generated
12 * the appropriate server SSL extension is installed and active 12 - the appropriate server SSL extension is installed and active
13 13
14### HTTPS, TLS and self-signed certificates 14### HTTPS, TLS and self-signed certificates
15Related guides: 15Related guides:
16* [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php) 16
17* [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority) 17- [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php)
18* 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` 18- [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority)
19- Generate a self-signed certificate (will trigger browser warnings) with apache2:
20 `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`
19 21
20### Proxies 22### Proxies
21If 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: 23If 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:
22- `X-Forwarded-Proto`; 24
23- `X-Forwarded-Host`; 25- `X-Forwarded-Proto`
24- `X-Forwarded-For`. 26- `X-Forwarded-Host`
27- `X-Forwarded-For`
25 28
26See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues. 29See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues.
27 30
@@ -37,8 +40,9 @@ See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%9
37This configuration will log both Apache and PHP errors, which may prove useful to identify server configuration errors. 40This configuration will log both Apache and PHP errors, which may prove useful to identify server configuration errors.
38 41
39See: 42See:
40* [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow) 43
41* [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/) 44- [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow)
45- [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/)
42 46
43```apache 47```apache
44<VirtualHost *:80> 48<VirtualHost *:80>
@@ -116,34 +120,41 @@ Apache module `mod_rewrite` **must** be enabled to use the REST API. URL rewriti
116Nginx 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. 120Nginx 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.
117 121
118Required packages: 122Required packages:
123
119- [nginx](http://nginx.org) 124- [nginx](http://nginx.org)
120- [php-fpm](http://php-fpm.org) - PHP FastCGI Process Manager 125- [php-fpm](http://php-fpm.org) - PHP FastCGI Process Manager
121 126
122Official documentation: 127Official documentation:
128
123- [Beginner's guide](http://nginx.org/en/docs/beginners_guide.html) 129- [Beginner's guide](http://nginx.org/en/docs/beginners_guide.html)
124- [ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html) 130- [ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)
125- [Pitfalls](http://wiki.nginx.org/Pitfalls) 131- [Pitfalls](http://wiki.nginx.org/Pitfalls)
126 132
127Community resources: 133Community resources:
134
128- [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla) 135- [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla)
129- [PHP configuration examples](http://kbeezie.com/nginx-configuration-examples/) (Karl Blessing) 136- [PHP configuration examples](http://kbeezie.com/nginx-configuration-examples/) (Karl Blessing)
130 137
131### Common setup 138### Common setup
132Once Nginx and PHP-FPM are installed, we need to ensure: 139Once Nginx and PHP-FPM are installed, we need to ensure:
140
133- Nginx and PHP-FPM are running using the _same user and group_ 141- Nginx and PHP-FPM are running using the _same user and group_
134- both these user and group have 142- both these user and group have
135 - `read` permissions for Shaarli resources 143 - `read` permissions for Shaarli resources
136 - `execute` permissions for Shaarli directories _AND_ their parent directories 144 - `execute` permissions for Shaarli directories _AND_ their parent directories
137 145
138On a production server: 146On a production server:
147
139- `user:group` will likely be `http:http`, `www:www` or `www-data:www-data` 148- `user:group` will likely be `http:http`, `www:www` or `www-data:www-data`
140- files will be located under `/var/www`, `/var/http` or `/usr/share/nginx` 149- files will be located under `/var/www`, `/var/http` or `/usr/share/nginx`
141 150
142On a development server: 151On a development server:
152
143- files may be located in a user's home directory 153- files may be located in a user's home directory
144- in this case, make sure both Nginx and PHP-FPM are running as the local user/group! 154- in this case, make sure both Nginx and PHP-FPM are running as the local user/group!
145 155
146For all following configuration examples, this user/group pair will be used: 156For all following configuration examples, this user/group pair will be used:
157
147- `user:group = john:users`, 158- `user:group = john:users`,
148 159
149which corresponds to the following service configuration: 160which corresponds to the following service configuration:
@@ -237,6 +248,7 @@ http {
237 248
238### Modular 249### Modular
239The previous setup is sufficient for development purposes, but has several major caveats: 250The previous setup is sufficient for development purposes, but has several major caveats:
251
240- every content that does not match the PHP rule will be sent to client browsers: 252- every content that does not match the PHP rule will be sent to client browsers:
241 - dotfiles - in our case, `.htaccess` 253 - dotfiles - in our case, `.htaccess`
242 - temporary files, e.g. Vim or Emacs files: `index.php~` 254 - temporary files, e.g. Vim or Emacs files: `index.php~`
@@ -342,7 +354,9 @@ http {
342``` 354```
343 355
344### Redirect HTTP to HTTPS 356### Redirect HTTP to HTTPS
345Assuming 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. 357Assuming you have generated a (self-signed) key and certificate, and they are
358located under `/home/john/ssl/localhost.{key,crt}`, it is pretty straightforward
359to set an HTTP (:80) to HTTPS (:443) redirection to force SSL/TLS usage.
346 360
347```nginx 361```nginx
348# /etc/nginx/nginx.conf 362# /etc/nginx/nginx.conf