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=
"Download.html">Download
</a></li>
40 <li><a href=
"Server-requirements.html">Server requirements
</a></li>
41 <li><a href=
"Server-configuration.html">Server configuration
</a></li>
42 <li><a href=
"Shaarli-configuration.html">Shaarli configuration
</a></li>
44 <li><a href=
"Usage.html">Usage
</a>
46 <li><a href=
"Sharing-button.html">Sharing button
</a> (bookmarklet)
</li>
47 <li><a href=
"Firefox-share.html">Firefox share
</a></li>
48 <li><a href=
"RSS-feeds.html">RSS feeds
</a></li>
52 <li><a href=
"Backup,-restore,-import-and-export.html">Backup, restore, import and export
</a></li>
53 <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>
54 <li><a href=
"Download-CSS-styles-from-an-OPML-list.html">Download CSS styles from an OPML list
</a></li>
55 <li><a href=
"Datastore-hacks.html">Datastore hacks
</a></li>
57 <li><a href=
"Troubleshooting.html">Troubleshooting
</a></li>
58 <li><a href=
"Development.html">Development
</a>
60 <li><a href=
"GnuPG-signature.html">GnuPG signature
</a></li>
61 <li><a href=
"Coding-guidelines.html">Coding guidelines
</a></li>
62 <li><a href=
"Directory-structure.html">Directory structure
</a></li>
63 <li><a href=
"3rd-party-libraries.html">3rd party libraries
</a></li>
64 <li><a href=
"Plugin-System.html">Plugin System
</a></li>
65 <li><a href=
"Security.html">Security
</a></li>
66 <li><a href=
"Static-analysis.html">Static analysis
</a></li>
67 <li><a href=
"Theming.html">Theming
</a></li>
68 <li><a href=
"Unit-tests.html">Unit tests
</a></li>
72 <li><a href=
"FAQ.html">FAQ
</a></li>
73 <li><a href=
"Community-&-Related-software.html">Community
& Related software
</a></li>
74 <li><a href=
"TODO.html">TODO
</a></li>
78 <h1 id=
"server-configuration">Server configuration
</h1>
79 <p><em>Example virtual host configurations for popular web servers
</em></p>
81 <li><a href=
"#apache">Apache
</a><a href=
".html"></a></li>
82 <li><a href=
"#lighthttpd">LightHttpd
</a> (empty)
<a href=
".html"></a></li>
83 <li><a href=
"#nginx">Nginx
</a><a href=
".html"></a></li>
85 <h2 id=
"prerequisites">Prerequisites
</h2>
87 <li>Shaarli is installed in a directory readable/writeable by the user
</li>
88 <li>the correct read/write permissions have been granted to the web server
<em>user and/or group
</em></li>
89 <li>for HTTPS / SSL:
</li>
90 <li>a key pair (public, private) and a certificate have been generated
</li>
91 <li>the appropriate server SSL extension is installed and active
</li>
93 <p>Related guides:
</p>
95 <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>
96 <li><a href=
"https://workaround.org/certificate-authority">How do I create my own Certificate Authority?
</a><a href=
".html"></a></li>
98 <h2 id=
"apache">Apache
</h2>
99 <h3 id=
"minimal">Minimal
</h3>
100 <pre class=
"sourceCode apache"><code class=
"sourceCode apache"><span class=
"fu"><VirtualHost
</span><span class=
"ot"> *:
80</span><span class=
"fu">></span>
101 ServerName
<span class=
"st"> shaarli.my-domain.org
</span>
102 DocumentRoot
<span class=
"st"> /absolute/path/to/shaarli/
</span>
103 <span class=
"fu"></VirtualHost
></span></code></pre>
104 <h3 id=
"debug---log-all-the-things">Debug - Log all the things!
</h3>
105 <p>This configuration will log both Apache and PHP errors, which may prove useful to identify server configuration errors.
</p>
108 <li><a href=
"http://stackoverflow.com/q/176">Apache/PHP - error log per VirtualHost
</a> (StackOverflow)
<a href=
".html"></a></li>
109 <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>
111 <pre class=
"sourceCode apache"><code class=
"sourceCode apache"><span class=
"fu"><VirtualHost
</span><span class=
"ot"> *:
80</span><span class=
"fu">></span>
112 ServerName
<span class=
"st"> shaarli.my-domain.org
</span>
113 DocumentRoot
<span class=
"st"> /absolute/path/to/shaarli/
</span>
115 <span class=
"ot">LogLevel
</span><span class=
"ch"> </span><span class=
"kw">warn
</span>
116 ErrorLog
<span class=
"st"> /var/log/apache2/shaarli-error.log
</span>
117 CustomLog
<span class=
"st"> /var/log/apache2/shaarli-access.log combined
</span>
119 php_flag log_errors on
120 php_flag display_errors on
121 php_value error_reporting
2147483647
122 php_value error_log /var/log/apache2/shaarli-php-error.log
123 <span class=
"fu"></VirtualHost
></span></code></pre>
124 <h3 id=
"standard---keep-access-and-error-logs">Standard - Keep access and error logs
</h3>
125 <pre class=
"sourceCode apache"><code class=
"sourceCode apache"><span class=
"fu"><VirtualHost
</span><span class=
"ot"> *:
80</span><span class=
"fu">></span>
126 ServerName
<span class=
"st"> shaarli.my-domain.org
</span>
127 DocumentRoot
<span class=
"st"> /absolute/path/to/shaarli/
</span>
129 <span class=
"ot">LogLevel
</span><span class=
"ch"> </span><span class=
"kw">warn
</span>
130 ErrorLog
<span class=
"st"> /var/log/apache2/shaarli-error.log
</span>
131 CustomLog
<span class=
"st"> /var/log/apache2/shaarli-access.log combined
</span>
132 <span class=
"fu"></VirtualHost
></span></code></pre>
133 <h3 id=
"paranoid---redirect-http-80-to-https-443">Paranoid - Redirect HTTP (:
80) to HTTPS (:
443)
</h3>
134 <p>See
<a href=
"https://wiki.mozilla.org/Security/Server_Side_TLS#Apache">Server-side TLS
</a> (Mozilla).
<a href=
".html"></a></p>
135 <pre class=
"sourceCode apache"><code class=
"sourceCode apache"><span class=
"fu"><VirtualHost
</span><span class=
"ot"> *:
443</span><span class=
"fu">></span>
136 ServerName
<span class=
"st"> shaarli.my-domain.org
</span>
137 DocumentRoot
<span class=
"st"> /absolute/path/to/shaarli/
</span>
139 <span class=
"ot">SSLEngine
</span><span class=
"ch"> </span><span class=
"kw">on
</span>
140 SSLCertificateFile
<span class=
"st"> /absolute/path/to/the/website/certificate.crt
</span>
141 SSLCertificateKeyFile
<span class=
"st"> /absolute/path/to/the/website/key.key
</span>
143 <span class=
"fu"><Directory
</span><span class=
"ot"> /absolute/path/to/shaarli/
</span><span class=
"fu">></span>
144 <span class=
"ot">AllowOverride
</span><span class=
"ch"> </span><span class=
"kw">All
</span>
145 <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>
146 <span class=
"ot">Order
</span><span class=
"ch"> </span><span class=
"kw">allow,deny
</span>
147 allow
<span class=
"st"> from all
</span>
148 <span class=
"fu"></Directory
></span>
150 <span class=
"ot">LogLevel
</span><span class=
"ch"> </span><span class=
"kw">warn
</span>
151 ErrorLog
<span class=
"st"> /var/log/apache2/shaarli-error.log
</span>
152 CustomLog
<span class=
"st"> /var/log/apache2/shaarli-access.log combined
</span>
153 <span class=
"fu"></VirtualHost
></span>
154 <span class=
"fu"><VirtualHost
</span><span class=
"ot"> *:
80</span><span class=
"fu">></span>
155 ServerName
<span class=
"st"> shaarli.my-domain.org
</span>
156 Redirect
<span class=
"st"> 301 / https://shaarli.my-domain.org
</span>
158 <span class=
"ot">LogLevel
</span><span class=
"ch"> </span><span class=
"kw">warn
</span>
159 ErrorLog
<span class=
"st"> /var/log/apache2/shaarli-error.log
</span>
160 CustomLog
<span class=
"st"> /var/log/apache2/shaarli-access.log combined
</span>
161 <span class=
"fu"></VirtualHost
></span></code></pre>
162 <h2 id=
"lighthttpd">LightHttpd
</h2>
163 <h2 id=
"nginx">Nginx
</h2>
164 <h3 id=
"foreword">Foreword
</h3>
165 <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>
166 <p>Required packages:
</p>
168 <li><a href=
"http://nginx.org">nginx
</a><a href=
".html"></a></li>
169 <li><a href=
"http://php-fpm.org">php-fpm
</a> - PHP FastCGI Process Manager
<a href=
".html"></a></li>
171 <p>Official documentation:
</p>
173 <li><a href=
"http://nginx.org/en/docs/beginners_guide.html">Beginner's guide
</a><a href=
".html"></a></li>
174 <li><a href=
"http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html">ngx_http_fastcgi_module
</a><a href=
".html"></a></li>
175 <li><a href=
"http://wiki.nginx.org/Pitfalls">Pitfalls
</a><a href=
".html"></a></li>
177 <p>Community resources:
</p>
179 <li><a href=
"https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx">Server-side TLS (Nginx)
</a> (Mozilla)
<a href=
".html"></a></li>
180 <li><a href=
"http://kbeezie.com/nginx-configuration-examples/">PHP configuration examples
</a> (Karl Blessing)
<a href=
".html"></a></li>
182 <h3 id=
"common-setup">Common setup
</h3>
183 <p>Once Nginx and PHP-FPM are installed, we need to ensure:
</p>
185 <li>Nginx and PHP-FPM are running using the
<em>same user and group
</em></li>
186 <li>both these user and group have
188 <li><code>read
</code> permissions for Shaarli resources
</li>
189 <li><code>execute
</code> permissions for Shaarli directories
<em>AND
</em> their parent directories
</li>
192 <p>On a production server:
</p>
194 <li><code>user:group
</code> will likely be
<code>http:http
</code>,
<code>www:www
</code> or
<code>www-data:www-data
</code></li>
195 <li>files will be located under
<code>/var/www
</code>,
<code>/var/http
</code> or
<code>/usr/share/nginx
</code></li>
197 <p>On a development server:
</p>
199 <li>files may be located in a user's home directory
</li>
200 <li>in this case, make sure both Nginx and PHP-FPM are running as the local user/group!
</li>
202 <p>For all following examples, a development configuration will be used:
</p>
204 <li><code>user:group = john:users
</code>,
</li>
206 <p>which corresponds to the following service configuration:
</p>
207 <pre class=
"sourceCode ini"><code class=
"sourceCode ini"><span class=
"co">; /etc/php/php-fpm.conf
</span>
208 <span class=
"dt">user
</span><span class=
"ot">=
</span><span class=
"st"> john
</span>
209 <span class=
"dt">group
</span><span class=
"ot">=
</span><span class=
"st"> users
</span>
211 <span class=
"kw">[...][]
</span><span class=
"dt">(.html)
</span>
212 <span class=
"dt">listen.owner
</span><span class=
"ot">=
</span><span class=
"st"> john
</span>
213 <span class=
"dt">listen.group
</span><span class=
"ot">=
</span><span class=
"st"> users
</span></code></pre>
214 <pre class=
"nginx"><code># /etc/nginx/nginx.conf
220 <h3 id=
"minimal-1">Minimal
</h3>
221 <p><em>WARNING: Use for development only!
</em></p>
222 <pre class=
"nginx"><code>user john users;
225 worker_connections
1024;
230 default_type application/octet-stream;
231 keepalive_timeout
20;
233 index index.html index.php;
237 server_name localhost;
240 access_log /var/log/nginx/access.log;
241 error_log /var/log/nginx/error.log;
244 access_log /var/log/nginx/shaarli.access.log;
245 error_log /var/log/nginx/shaarli.error.log;
248 location ~ (index)\.php$ {
249 fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
250 fastcgi_index index.php;
251 include fastcgi.conf;
255 <h3 id=
"modular">Modular
</h3>
256 <p>The previous setup is sufficient for development purposes, but has several major caveats:
</p>
258 <li>every content that does not match the PHP rule will be sent to client browsers:
260 <li>dotfiles - in our case,
<code>.htaccess
</code></li>
261 <li>temporary files, e.g. Vim or Emacs files:
<code>index.php~
</code></li>
263 <li>asset / static resource caching is not optimized
</li>
264 <li>if serving several PHP sites, there will be a lot of duplication:
<code>location /shaarli/
</code>,
<code>location /mysite/
</code>, etc.
</li>
266 <p>To solve this, we will split Nginx configuration in several parts, that will be included when needed:
</p>
267 <pre class=
"nginx"><code># /etc/nginx/deny.conf
269 # deny access to dotfiles
276 # deny access to temp editor files, e.g.
"script.php~
"
281 <pre class=
"nginx"><code># /etc/nginx/php.conf
282 location ~ (index)\.php$ {
283 # filter and proxy PHP requests to PHP-FPM
284 fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
285 fastcgi_index index.php;
286 include fastcgi.conf;
290 # deny access to all other PHP scripts
293 <pre class=
"nginx"><code># /etc/nginx/static_assets.conf
294 location ~* \.(?:ico|css|js|gif|jpe?g|png)$ {
296 add_header Pragma public;
297 add_header Cache-Control
"public, must-revalidate, proxy-revalidate
";
299 <pre class=
"nginx"><code># /etc/nginx/nginx.conf
306 access_log /var/log/nginx/access.log;
307 error_log /var/log/nginx/error.log;
310 # virtual host for a first domain
312 server_name my.first.domain.org;
315 access_log /var/log/nginx/shaarli.access.log;
316 error_log /var/log/nginx/shaarli.error.log;
320 include static_assets.conf;
325 # virtual host for a second domain
327 server_name second.domain.com;
330 access_log /var/log/nginx/minigal.access.log;
331 error_log /var/log/nginx/minigal.error.log;
335 include static_assets.conf;
339 <h3 id=
"redirect-http-to-https">Redirect HTTP to HTTPS
</h3>
340 <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>
341 <pre class=
"nginx"><code># /etc/nginx/nginx.conf
347 index index.html index.php;
350 access_log /var/log/nginx/access.log;
351 error_log /var/log/nginx/error.log;
355 server_name localhost;
357 return
301 https://localhost$request_uri;
362 server_name localhost;
364 ssl_certificate /home/john/ssl/localhost.crt;
365 ssl_certificate_key /home/john/ssl/localhost.key;
368 access_log /var/log/nginx/shaarli.access.log;
369 error_log /var/log/nginx/shaarli.error.log;
373 include static_assets.conf;