aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/Server-configuration.md
diff options
context:
space:
mode:
authornodiscc <nodiscc@gmail.com>2017-01-26 18:52:54 +0100
committernodiscc <nodiscc@gmail.com>2017-06-18 00:19:49 +0200
commit53ed6d7d1e678d7486337ce67a2f17b30bac21ac (patch)
treef8bef0164a70bd03d2b9781951c01bdd018f1842 /doc/Server-configuration.md
parentd5d22a6d07917865c44148ad76f43c65a929a890 (diff)
downloadShaarli-53ed6d7d1e678d7486337ce67a2f17b30bac21ac.tar.gz
Shaarli-53ed6d7d1e678d7486337ce67a2f17b30bac21ac.tar.zst
Shaarli-53ed6d7d1e678d7486337ce67a2f17b30bac21ac.zip
Generate HTML documentation using MkDocs (WIP)
MkDocs is a static site generator geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML file. * http://www.mkdocs.org/ * http://www.mkdocs.org/user-guide/configuration/ Ref. #312 * remove pandoc-generated HTML documentation * move markdown doc to doc/md/, * mkdocs.yml: * generate HTML doc in doc/html * add pages TOC/ordering * use index.md as index page * Makefile: remove execute permissions from generated files * Makefile: rewrite htmlpages GFM to markdown conversion using sed: awk expression aslo matched '][' which causes invalid output on complex links with images or code blocks * Add mkdocs.yml to .gitattributes, exclude this file from release archives * Makefile: rename: htmldoc -> doc_html target * run make doc: pull latest markdown documentation from wiki * run make htmlpages: update html documentation
Diffstat (limited to 'doc/Server-configuration.md')
-rw-r--r--doc/Server-configuration.md393
1 files changed, 0 insertions, 393 deletions
diff --git a/doc/Server-configuration.md b/doc/Server-configuration.md
deleted file mode 100644
index 81cc1a72..00000000
--- a/doc/Server-configuration.md
+++ /dev/null
@@ -1,393 +0,0 @@
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
16Related 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
22If 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
27See 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!
38This configuration will log both Apache and PHP errors, which may prove useful to identify server configuration errors.
39
40See:
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)
73See [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### .htaccess
106
107Shaarli use `.htaccess` Apache files to deny access to files that shouldn't be directly accessed (datastore, config, etc.). You need the directive `AllowOverride All` in your virtual host configuration for them to work.
108
109**Warning**: If you use Apache 2.2 or lower, you need [mod_version](https://httpd.apache.org/docs/current/mod/mod_version.html) to be installed and enabled.[](.html)
110
111Apache module `mod_rewrite` **must** be enabled to use the REST API. URL rewriting rules for the Slim microframework are stated in the root `.htaccess` file.
112
113## LightHttpd
114
115## Nginx
116### Foreword
117Nginx 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)
118
119Required packages:
120- [nginx](http://nginx.org)[](.html)
121- [php-fpm](http://php-fpm.org) - PHP FastCGI Process Manager[](.html)
122
123Official documentation:
124- [Beginner's guide](http://nginx.org/en/docs/beginners_guide.html)[](.html)
125- [ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)[](.html)
126- [Pitfalls](http://wiki.nginx.org/Pitfalls)[](.html)
127
128Community resources:
129- [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla)[](.html)
130- [PHP configuration examples](http://kbeezie.com/nginx-configuration-examples/) (Karl Blessing)[](.html)
131
132### Common setup
133Once Nginx and PHP-FPM are installed, we need to ensure:
134- Nginx and PHP-FPM are running using the _same user and group_
135- both these user and group have
136 - `read` permissions for Shaarli resources
137 - `execute` permissions for Shaarli directories _AND_ their parent directories
138
139On a production server:
140- `user:group` will likely be `http:http`, `www:www` or `www-data:www-data`
141- files will be located under `/var/www`, `/var/http` or `/usr/share/nginx`
142
143On a development server:
144- files may be located in a user's home directory
145- in this case, make sure both Nginx and PHP-FPM are running as the local user/group!
146
147For all following configuration examples, this user/group pair will be used:
148- `user:group = john:users`,
149
150which corresponds to the following service configuration:
151
152```ini
153; /etc/php/php-fpm.conf
154user = john
155group = users
156
157[...][](.html)
158listen.owner = john
159listen.group = users
160```
161
162```nginx
163# /etc/nginx/nginx.conf
164user john users;
165
166http {
167 [...][](.html)
168}
169```
170
171### (Optional) Increase the maximum file upload size
172Some bookmark dumps generated by web browsers can be _huge_ due to the presence of Base64-encoded images and favicons, as well as extra verbosity when nesting links in (sub-)folders.
173
174To increase upload size, you will need to modify both nginx and PHP configuration:
175
176```nginx
177# /etc/nginx/nginx.conf
178
179http {
180 [...][](.html)
181
182 client_max_body_size 10m;
183
184 [...][](.html)
185}
186```
187
188```ini
189# /etc/php5/fpm/php.ini
190
191[...][](.html)
192post_max_size = 10M
193[...][](.html)
194upload_max_filesize = 10M
195```
196
197### Minimal
198_WARNING: Use for development only!_
199
200```nginx
201user john users;
202worker_processes 1;
203events {
204 worker_connections 1024;
205}
206
207http {
208 include mime.types;
209 default_type application/octet-stream;
210 keepalive_timeout 20;
211
212 index index.html index.php;
213
214 server {
215 listen 80;
216 server_name localhost;
217 root /home/john/web;
218
219 access_log /var/log/nginx/access.log;
220 error_log /var/log/nginx/error.log;
221
222 location /shaarli/ {
223 try_files $uri /shaarli/index.php$is_args$args;
224 access_log /var/log/nginx/shaarli.access.log;
225 error_log /var/log/nginx/shaarli.error.log;
226 }
227
228 location ~ (index)\.php$ {
229 try_files $uri =404;
230 fastcgi_split_path_info ^(.+\.php)(/.+)$;
231 fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
232 fastcgi_index index.php;
233 include fastcgi.conf;
234 }
235 }
236}
237```
238
239### Modular
240The previous setup is sufficient for development purposes, but has several major caveats:
241- every content that does not match the PHP rule will be sent to client browsers:
242 - dotfiles - in our case, `.htaccess`
243 - temporary files, e.g. Vim or Emacs files: `index.php~`
244- asset / static resource caching is not optimized
245- if serving several PHP sites, there will be a lot of duplication: `location /shaarli/`, `location /mysite/`, etc.
246
247To solve this, we will split Nginx configuration in several parts, that will be included when needed:
248
249```nginx
250# /etc/nginx/deny.conf
251location ~ /\. {
252 # deny access to dotfiles
253 access_log off;
254 log_not_found off;
255 deny all;
256}
257
258location ~ ~$ {
259 # deny access to temp editor files, e.g. "script.php~"
260 access_log off;
261 log_not_found off;
262 deny all;
263}
264```
265
266```nginx
267# /etc/nginx/php.conf
268location ~ (index)\.php$ {
269 # Slim - split URL path into (script_filename, path_info)
270 try_files $uri =404;
271 fastcgi_split_path_info ^(.+\.php)(/.+)$;
272
273 # filter and proxy PHP requests to PHP-FPM
274 fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
275 fastcgi_index index.php;
276 include fastcgi.conf;
277}
278
279location ~ \.php$ {
280 # deny access to all other PHP scripts
281 deny all;
282}
283```
284
285```nginx
286# /etc/nginx/static_assets.conf
287location ~* \.(?:ico|css|js|gif|jpe?g|png)$ {
288 expires max;
289 add_header Pragma public;
290 add_header Cache-Control "public, must-revalidate, proxy-revalidate";
291}
292```
293
294```nginx
295# /etc/nginx/nginx.conf
296[...][](.html)
297
298http {
299 [...][](.html)
300
301 root /home/john/web;
302 access_log /var/log/nginx/access.log;
303 error_log /var/log/nginx/error.log;
304
305 server {
306 # virtual host for a first domain
307 listen 80;
308 server_name my.first.domain.org;
309
310 location /shaarli/ {
311 # Slim - rewrite URLs
312 try_files $uri /shaarli/index.php$is_args$args;
313
314 access_log /var/log/nginx/shaarli.access.log;
315 error_log /var/log/nginx/shaarli.error.log;
316 }
317
318 location = /shaarli/favicon.ico {
319 # serve the Shaarli favicon from its custom location
320 alias /var/www/shaarli/images/favicon.ico;
321 }
322
323 include deny.conf;
324 include static_assets.conf;
325 include php.conf;
326 }
327
328 server {
329 # virtual host for a second domain
330 listen 80;
331 server_name second.domain.com;
332
333 location /minigal/ {
334 access_log /var/log/nginx/minigal.access.log;
335 error_log /var/log/nginx/minigal.error.log;
336 }
337
338 include deny.conf;
339 include static_assets.conf;
340 include php.conf;
341 }
342}
343```
344
345### Redirect HTTP to HTTPS
346Assuming 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.
347
348```nginx
349# /etc/nginx/nginx.conf
350[...][](.html)
351
352http {
353 [...][](.html)
354
355 index index.html index.php;
356
357 root /home/john/web;
358 access_log /var/log/nginx/access.log;
359 error_log /var/log/nginx/error.log;
360
361 server {
362 listen 80;
363 server_name localhost;
364
365 return 301 https://localhost$request_uri;
366 }
367
368 server {
369 listen 443 ssl;
370 server_name localhost;
371
372 ssl_certificate /home/john/ssl/localhost.crt;
373 ssl_certificate_key /home/john/ssl/localhost.key;
374
375 location /shaarli/ {
376 # Slim - rewrite URLs
377 try_files $uri /index.php$is_args$args;
378
379 access_log /var/log/nginx/shaarli.access.log;
380 error_log /var/log/nginx/shaarli.error.log;
381 }
382
383 location = /shaarli/favicon.ico {
384 # serve the Shaarli favicon from its custom location
385 alias /var/www/shaarli/images/favicon.ico;
386 }
387
388 include deny.conf;
389 include static_assets.conf;
390 include php.conf;
391 }
392}
393```