5 <meta name=
"generator" content=
"pandoc">
6 <meta name=
"viewport" content=
"width=device-width, initial-scale=1.0, user-scalable=yes">
7 <title>Shaarli - Server configuration
</title>
8 <style type=
"text/css">code{white-space: pre;}
</style>
10 <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
12 <style type=
"text/css">
13 table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode {
14 margin:
0; padding:
0; vertical-align: baseline; border: none; }
15 table.sourceCode { width:
100%; line-height:
100%; }
16 td.lineNumbers { text-align: right; padding-right:
4px; padding-left:
4px; color: #aaaaaa; border-right:
1px solid #aaaaaa; }
17 td.sourceCode { padding-left:
5px; }
18 code
> span.kw { color: #
007020; font-weight: bold; }
19 code
> span.dt { color: #
902000; }
20 code
> span.dv { color: #
40a070; }
21 code
> span.bn { color: #
40a070; }
22 code
> span.fl { color: #
40a070; }
23 code
> span.ch { color: #
4070a0; }
24 code
> span.st { color: #
4070a0; }
25 code
> span.co { color: #
60a0b0; font-style: italic; }
26 code
> span.ot { color: #
007020; }
27 code
> span.al { color: #ff0000; font-weight: bold; }
28 code
> span.fu { color: #
06287e; }
29 code
> span.er { color: #ff0000; font-weight: bold; }
31 <link rel=
"stylesheet" href=
"github-markdown.css">
34 <div id=
"local-sidebar">
36 <li><a href=
"Home.html">Home
</a></li>
39 <li><a href=
"Server-requirements.html">Server requirements
</a></li>
40 <li><a href=
"Server-configuration.html">Server configuration
</a></li>
41 <li><a href=
"Shaarli-configuration.html">Shaarli configuration
</a></li>
43 <li><a href=
"Usage.html">Usage
</a>
45 <li><a href=
"Sharing-button.html">Sharing button
</a> (bookmarklet)
</li>
46 <li><a href=
"Firefox-share.html">Firefox share
</a></li>
47 <li><a href=
"RSS-feeds.html">RSS feeds
</a></li>
51 <li><a href=
"Backup,-restore,-import-and-export.html">Backup, restore, import and export
</a></li>
52 <li><a href=
"Copy-an-existing-installation-over-SSH-and-serve-it-locally.html">Copy an existing installation over SSH and serve it locally
</a></li>
53 <li><a href=
"Download-CSS-styles-from-an-OPML-list.html">Download CSS styles from an OPML list
</a></li>
54 <li><a href=
"Datastore-hacks.html">Datastore hacks
</a></li>
56 <li><a href=
"Troubleshooting.html">Troubleshooting
</a></li>
57 <li><a href=
"Development.html">Development
</a>
59 <li><a href=
"GnuPG-signature.html">GnuPG signature
</a></li>
60 <li><a href=
"Coding-guidelines.html">Coding guidelines
</a></li>
61 <li><a href=
"Directory-structure.html">Directory structure
</a></li>
62 <li><a href=
"3rd-party-libraries.html">3rd party libraries
</a></li>
63 <li><a href=
"Plugin-System.html">Plugin System
</a></li>
64 <li><a href=
"Security.html">Security
</a></li>
65 <li><a href=
"Static-analysis.html">Static analysis
</a></li>
66 <li><a href=
"Theming.html">Theming
</a></li>
67 <li><a href=
"Unit-tests.html">Unit tests
</a></li>
71 <li><a href=
"FAQ.html">FAQ
</a></li>
72 <li><a href=
"Community-&-Related-software.html">Community
& Related software
</a></li>
73 <li><a href=
"TODO.html">TODO
</a></li>
77 <h1 id=
"server-configuration">Server configuration
</h1>
78 <p><em>Example virtual host configurations for popular web servers
</em></p>
80 <li><a href=
"#apache">Apache
</a><a href=
".html"></a></li>
81 <li><a href=
"#lighthttpd">LightHttpd
</a> (empty)
<a href=
".html"></a></li>
82 <li><a href=
"#nginx">Nginx
</a><a href=
".html"></a></li>
84 <h2 id=
"prerequisites">Prerequisites
</h2>
86 <li>Shaarli is installed in a directory readable/writeable by the user
</li>
87 <li>the correct read/write permissions have been granted to the web server
<em>user and/or group
</em></li>
88 <li>for HTTPS / SSL:
</li>
89 <li>a key pair (public, private) and a certificate have been generated
</li>
90 <li>the appropriate server SSL extension is installed and active
</li>
92 <p>Related guides:
</p>
94 <li><a href=
"http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php">How to Create Self-Signed SSL Certificates with OpenSSL
</a><a href=
".html"></a></li>
95 <li><a href=
"https://workaround.org/certificate-authority">How do I create my own Certificate Authority?
</a><a href=
".html"></a></li>
97 <h2 id=
"apache">Apache
</h2>
98 <h3 id=
"minimal">Minimal
</h3>
99 <pre class=
"sourceCode apache"><code class=
"sourceCode apache"><span class=
"fu"><VirtualHost
</span><span class=
"ot"> *:
80</span><span class=
"fu">></span>
100 ServerName
<span class=
"st"> shaarli.my-domain.org
</span>
101 DocumentRoot
<span class=
"st"> /absolute/path/to/shaarli/
</span>
102 <span class=
"fu"></VirtualHost
></span></code></pre>
103 <h3 id=
"debug---log-all-the-things">Debug - Log all the things!
</h3>
104 <p>This configuration will log both Apache and PHP errors, which may prove useful to identify server configuration errors.
</p>
107 <li><a href=
"http://stackoverflow.com/q/176">Apache/PHP - error log per VirtualHost
</a> (StackOverflow)
<a href=
".html"></a></li>
108 <li><a href=
"PHP:%20php_value%20vs%20php_admin_value%20and%20the%20use%20of%20php_flag%20explained">PHP: php_value vs php_admin_value and the use of php_flag explained
</a><a href=
".html"></a></li>
110 <pre class=
"sourceCode apache"><code class=
"sourceCode apache"><span class=
"fu"><VirtualHost
</span><span class=
"ot"> *:
80</span><span class=
"fu">></span>
111 ServerName
<span class=
"st"> shaarli.my-domain.org
</span>
112 DocumentRoot
<span class=
"st"> /absolute/path/to/shaarli/
</span>
114 <span class=
"ot">LogLevel
</span><span class=
"ch"> </span><span class=
"kw">warn
</span>
115 ErrorLog
<span class=
"st"> /var/log/apache2/shaarli-error.log
</span>
116 CustomLog
<span class=
"st"> /var/log/apache2/shaarli-access.log combined
</span>
118 php_flag log_errors on
119 php_flag display_errors on
120 php_value error_reporting
2147483647
121 php_value error_log /var/log/apache2/shaarli-php-error.log
122 <span class=
"fu"></VirtualHost
></span></code></pre>
123 <h3 id=
"standard---keep-access-and-error-logs">Standard - Keep access and error logs
</h3>
124 <pre class=
"sourceCode apache"><code class=
"sourceCode apache"><span class=
"fu"><VirtualHost
</span><span class=
"ot"> *:
80</span><span class=
"fu">></span>
125 ServerName
<span class=
"st"> shaarli.my-domain.org
</span>
126 DocumentRoot
<span class=
"st"> /absolute/path/to/shaarli/
</span>
128 <span class=
"ot">LogLevel
</span><span class=
"ch"> </span><span class=
"kw">warn
</span>
129 ErrorLog
<span class=
"st"> /var/log/apache2/shaarli-error.log
</span>
130 CustomLog
<span class=
"st"> /var/log/apache2/shaarli-access.log combined
</span>
131 <span class=
"fu"></VirtualHost
></span></code></pre>
132 <h3 id=
"paranoid---redirect-http-80-to-https-443">Paranoid - Redirect HTTP (:
80) to HTTPS (:
443)
</h3>
133 <p>See
<a href=
"https://wiki.mozilla.org/Security/Server_Side_TLS#Apache">Server-side TLS
</a> (Mozilla).
<a href=
".html"></a></p>
134 <pre class=
"sourceCode apache"><code class=
"sourceCode apache"><span class=
"fu"><VirtualHost
</span><span class=
"ot"> *:
443</span><span class=
"fu">></span>
135 ServerName
<span class=
"st"> shaarli.my-domain.org
</span>
136 DocumentRoot
<span class=
"st"> /absolute/path/to/shaarli/
</span>
138 <span class=
"ot">SSLEngine
</span><span class=
"ch"> </span><span class=
"kw">on
</span>
139 SSLCertificateFile
<span class=
"st"> /absolute/path/to/the/website/certificate.crt
</span>
140 SSLCertificateKeyFile
<span class=
"st"> /absolute/path/to/the/website/key.key
</span>
142 <span class=
"fu"><Directory
</span><span class=
"ot"> /absolute/path/to/shaarli/
</span><span class=
"fu">></span>
143 <span class=
"ot">AllowOverride
</span><span class=
"ch"> </span><span class=
"kw">All
</span>
144 <span class=
"ot">Options
</span><span class=
"ch"> </span><span class=
"kw">Indexes
</span><span class=
"ch"> </span><span class=
"kw">FollowSymLinks
</span><span class=
"ch"> </span><span class=
"kw">MultiViews
</span>
145 <span class=
"ot">Order
</span><span class=
"ch"> </span><span class=
"kw">allow,deny
</span>
146 allow
<span class=
"st"> from all
</span>
147 <span class=
"fu"></Directory
></span>
149 <span class=
"ot">LogLevel
</span><span class=
"ch"> </span><span class=
"kw">warn
</span>
150 ErrorLog
<span class=
"st"> /var/log/apache2/shaarli-error.log
</span>
151 CustomLog
<span class=
"st"> /var/log/apache2/shaarli-access.log combined
</span>
152 <span class=
"fu"></VirtualHost
></span>
153 <span class=
"fu"><VirtualHost
</span><span class=
"ot"> *:
80</span><span class=
"fu">></span>
154 ServerName
<span class=
"st"> shaarli.my-domain.org
</span>
155 Redirect
<span class=
"st"> 301 / https://shaarli.my-domain.org
</span>
157 <span class=
"ot">LogLevel
</span><span class=
"ch"> </span><span class=
"kw">warn
</span>
158 ErrorLog
<span class=
"st"> /var/log/apache2/shaarli-error.log
</span>
159 CustomLog
<span class=
"st"> /var/log/apache2/shaarli-access.log combined
</span>
160 <span class=
"fu"></VirtualHost
></span></code></pre>
161 <h2 id=
"lighthttpd">LightHttpd
</h2>
162 <h2 id=
"nginx">Nginx
</h2>
163 <h3 id=
"foreword">Foreword
</h3>
164 <p>Nginx does not natively interpret PHP scripts; to this effect, we will run a
<a href=
"https://en.wikipedia.org/wiki/FastCGI">FastCGI
</a> service, to which Nginx's FastCGI module will proxy all requests to PHP resources.
<a href=
".html"></a></p>
165 <p>Required packages:
</p>
167 <li><a href=
"http://nginx.org">nginx
</a><a href=
".html"></a></li>
168 <li><a href=
"http://php-fpm.org">php-fpm
</a> - PHP FastCGI Process Manager
<a href=
".html"></a></li>
170 <p>Official documentation:
</p>
172 <li><a href=
"http://nginx.org/en/docs/beginners_guide.html">Beginner's guide
</a><a href=
".html"></a></li>
173 <li><a href=
"http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html">ngx_http_fastcgi_module
</a><a href=
".html"></a></li>
174 <li><a href=
"http://wiki.nginx.org/Pitfalls">Pitfalls
</a><a href=
".html"></a></li>
176 <p>Community resources:
</p>
178 <li><a href=
"https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx">Server-side TLS (Nginx)
</a> (Mozilla)
<a href=
".html"></a></li>
179 <li><a href=
"http://kbeezie.com/nginx-configuration-examples/">PHP configuration examples
</a> (Karl Blessing)
<a href=
".html"></a></li>
181 <h3 id=
"common-setup">Common setup
</h3>
182 <p>Once Nginx and PHP-FPM are installed, we need to ensure:
</p>
184 <li>Nginx and PHP-FPM are running using the
<em>same user and group
</em></li>
185 <li>both these user and group have
187 <li><code>read
</code> permissions for Shaarli resources
</li>
188 <li><code>execute
</code> permissions for Shaarli directories
<em>AND
</em> their parent directories
</li>
191 <p>On a production server:
</p>
193 <li><code>user:group
</code> will likely be
<code>http:http
</code>,
<code>www:www
</code> or
<code>www-data:www-data
</code></li>
194 <li>files will be located under
<code>/var/www
</code>,
<code>/var/http
</code> or
<code>/usr/share/nginx
</code></li>
196 <p>On a development server:
</p>
198 <li>files may be located in a user's home directory
</li>
199 <li>in this case, make sure both Nginx and PHP-FPM are running as the local user/group!
</li>
201 <p>For all following examples, a development configuration will be used:
</p>
203 <li><code>user:group = john:users
</code>,
</li>
205 <p>which corresponds to the following service configuration:
</p>
206 <pre class=
"sourceCode ini"><code class=
"sourceCode ini"><span class=
"co">; /etc/php/php-fpm.conf
</span>
207 <span class=
"dt">user
</span><span class=
"ot">=
</span><span class=
"st"> john
</span>
208 <span class=
"dt">group
</span><span class=
"ot">=
</span><span class=
"st"> users
</span>
210 <span class=
"kw">[...][]
</span><span class=
"dt">(.html)
</span>
211 <span class=
"dt">listen.owner
</span><span class=
"ot">=
</span><span class=
"st"> john
</span>
212 <span class=
"dt">listen.group
</span><span class=
"ot">=
</span><span class=
"st"> users
</span></code></pre>
213 <pre class=
"nginx"><code># /etc/nginx/nginx.conf
219 <h3 id=
"minimal-1">Minimal
</h3>
220 <p><em>WARNING: Use for development only!
</em></p>
221 <pre class=
"nginx"><code>user john users;
224 worker_connections
1024;
229 default_type application/octet-stream;
230 keepalive_timeout
20;
232 index index.html index.php;
236 server_name localhost;
239 access_log /var/log/nginx/access.log;
240 error_log /var/log/nginx/error.log;
243 access_log /var/log/nginx/shaarli.access.log;
244 error_log /var/log/nginx/shaarli.error.log;
247 location ~ (index)\.php$ {
248 fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
249 fastcgi_index index.php;
250 include fastcgi.conf;
254 <h3 id=
"modular">Modular
</h3>
255 <p>The previous setup is sufficient for development purposes, but has several major caveats:
</p>
257 <li>every content that does not match the PHP rule will be sent to client browsers:
259 <li>dotfiles - in our case,
<code>.htaccess
</code></li>
260 <li>temporary files, e.g. Vim or Emacs files:
<code>index.php~
</code></li>
262 <li>asset / static resource caching is not optimized
</li>
263 <li>if serving several PHP sites, there will be a lot of duplication:
<code>location /shaarli/
</code>,
<code>location /mysite/
</code>, etc.
</li>
265 <p>To solve this, we will split Nginx configuration in several parts, that will be included when needed:
</p>
266 <pre class=
"nginx"><code># /etc/nginx/deny.conf
268 # deny access to dotfiles
275 # deny access to temp editor files, e.g.
"script.php~
"
280 <pre class=
"nginx"><code># /etc/nginx/php.conf
281 location ~ (index)\.php$ {
282 # proxy PHP requests to PHP-FPM
283 fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
284 fastcgi_index index.php;
285 include fastcgi.conf;
287 <pre class=
"nginx"><code># /etc/nginx/static_assets.conf
288 location ~* \.(?:ico|css|js|gif|jpe?g|png)$ {
290 add_header Pragma public;
291 add_header Cache-Control
"public, must-revalidate, proxy-revalidate
";
293 <pre class=
"nginx"><code># /etc/nginx/nginx.conf
300 access_log /var/log/nginx/access.log;
301 error_log /var/log/nginx/error.log;
304 # virtual host for a first domain
306 server_name my.first.domain.org;
309 access_log /var/log/nginx/shaarli.access.log;
310 error_log /var/log/nginx/shaarli.error.log;
314 include static_assets.conf;
319 # virtual host for a second domain
321 server_name second.domain.com;
324 access_log /var/log/nginx/minigal.access.log;
325 error_log /var/log/nginx/minigal.error.log;
329 include static_assets.conf;
333 <h3 id=
"redirect-http-to-https">Redirect HTTP to HTTPS
</h3>
334 <p>Assuming you have generated a (self-signed) key and certificate, and they are located under
<code>/home/john/ssl/localhost.{key,crt}
</code>, it is pretty straightforward to set an HTTP (:
80) to HTTPS (:
443) redirection to force SSL/TLS usage.
</p>
335 <pre class=
"nginx"><code># /etc/nginx/nginx.conf
341 index index.html index.php;
344 access_log /var/log/nginx/access.log;
345 error_log /var/log/nginx/error.log;
349 server_name localhost;
351 return
301 https://localhost$request_uri;
356 server_name localhost;
358 ssl_certificate /home/john/ssl/localhost.crt;
359 ssl_certificate_key /home/john/ssl/localhost.key;
362 access_log /var/log/nginx/shaarli.access.log;
363 error_log /var/log/nginx/shaarli.error.log;
367 include static_assets.conf;