aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/Server-configuration.md
diff options
context:
space:
mode:
authorVirtualTam <virtualtam@flibidi.net>2015-07-22 05:02:10 +0200
committerVirtualTam <virtualtam@flibidi.net>2015-08-04 16:02:21 +0200
commit992af0b9d77cb4fbac2c37ef8d5896042d67a2a3 (patch)
tree4726baf18e7057eac3f9b6bdb5991fe6117814fc /doc/Server-configuration.md
parent96db105e4c0833324f7168edb5673278de8ccd54 (diff)
downloadShaarli-992af0b9d77cb4fbac2c37ef8d5896042d67a2a3.tar.gz
Shaarli-992af0b9d77cb4fbac2c37ef8d5896042d67a2a3.tar.zst
Shaarli-992af0b9d77cb4fbac2c37ef8d5896042d67a2a3.zip
Doc: sync from Wiki, generate HTML
Closes #291 Fixes #227 Modifications - HTML content: match the new Wiki structure - Makefile - generate a custom HTML sidebar - include the sidebar on all pages - infer and prepend page titles - handle relative links - add title metadata, e.g. Shaarli - <Page Name> Signed-off-by: VirtualTam <virtualtam@flibidi.net>
Diffstat (limited to 'doc/Server-configuration.md')
-rw-r--r--doc/Server-configuration.md321
1 files changed, 321 insertions, 0 deletions
diff --git a/doc/Server-configuration.md b/doc/Server-configuration.md
new file mode 100644
index 00000000..c9ec4e13
--- /dev/null
+++ b/doc/Server-configuration.md
@@ -0,0 +1,321 @@
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
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)[](.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!
28This configuration will log both Apache and PHP errors, which may prove useful to identify server configuration errors.
29
30See:
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)
63See [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
99Nginx 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
101Required packages:
102- [nginx](http://nginx.org)[](.html)
103- [php-fpm](http://php-fpm.org) - PHP FastCGI Process Manager[](.html)
104
105Official 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
110Community 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
115Once 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
121On 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
125On 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
129For all following examples, a development configuration will be used:
130- `user:group = john:users`,
131
132which corresponds to the following service configuration:
133
134```ini
135; /etc/php/php-fpm.conf
136user = john
137group = users
138
139[...][](.html)
140listen.owner = john
141listen.group = users
142```
143
144```nginx
145# /etc/nginx/nginx.conf
146user john users;
147
148http {
149 [...][](.html)
150}
151```
152
153### Minimal
154_WARNING: Use for development only!_
155
156```nginx
157user john users;
158worker_processes 1;
159events {
160 worker_connections 1024;
161}
162
163http {
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
193The 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
200To solve this, we will split Nginx configuration in several parts, that will be included when needed:
201
202```nginx
203# /etc/nginx/deny.conf
204location ~ /\. {
205 # deny access to dotfiles
206 access_log off;
207 log_not_found off;
208 deny all;
209}
210
211location ~ ~$ {
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
221location ~ (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
231location ~* \.(?: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
242http {
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
282Assuming 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
288http {
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```