aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/Server-configuration.html
diff options
context:
space:
mode:
authorArthurHoaro <arthur@hoa.ro>2016-04-14 14:20:23 +0200
committerArthurHoaro <arthur@hoa.ro>2016-04-14 15:18:25 +0200
commit5409ade28c5f0acf99dbadd4d95e6f8efda5d395 (patch)
tree4c8b55010ad02d91b524b0cb8cc02ddf318fcaa2 /doc/Server-configuration.html
parent9f400b0dad68b82d65692bd6ab6190f6a787fa89 (diff)
downloadShaarli-5409ade28c5f0acf99dbadd4d95e6f8efda5d395.tar.gz
Shaarli-5409ade28c5f0acf99dbadd4d95e6f8efda5d395.tar.zst
Shaarli-5409ade28c5f0acf99dbadd4d95e6f8efda5d395.zip
Update docs from Wiki
Diffstat (limited to 'doc/Server-configuration.html')
-rw-r--r--doc/Server-configuration.html100
1 files changed, 71 insertions, 29 deletions
diff --git a/doc/Server-configuration.html b/doc/Server-configuration.html
index 3aa89722..e1edf557 100644
--- a/doc/Server-configuration.html
+++ b/doc/Server-configuration.html
@@ -4,31 +4,49 @@
4 <meta charset="utf-8"> 4 <meta charset="utf-8">
5 <meta name="generator" content="pandoc"> 5 <meta name="generator" content="pandoc">
6 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes"> 6 <meta name="viewport" content="width=device-width, initial-scale=1.0, user-scalable=yes">
7 <title>Shaarli - Server configuration</title> 7 <title>Shaarli – Server configuration</title>
8 <style type="text/css">code{white-space: pre;}</style> 8 <style type="text/css">code{white-space: pre;}</style>
9 <!--[if lt IE 9]>
10 <script src="http://html5shim.googlecode.com/svn/trunk/html5.js"></script>
11 <![endif]-->
12 <style type="text/css"> 9 <style type="text/css">
10div.sourceCode { overflow-x: auto; }
13table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode { 11table.sourceCode, tr.sourceCode, td.lineNumbers, td.sourceCode {
14 margin: 0; padding: 0; vertical-align: baseline; border: none; } 12 margin: 0; padding: 0; vertical-align: baseline; border: none; }
15table.sourceCode { width: 100%; line-height: 100%; } 13table.sourceCode { width: 100%; line-height: 100%; }
16td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; } 14td.lineNumbers { text-align: right; padding-right: 4px; padding-left: 4px; color: #aaaaaa; border-right: 1px solid #aaaaaa; }
17td.sourceCode { padding-left: 5px; } 15td.sourceCode { padding-left: 5px; }
18code > span.kw { color: #007020; font-weight: bold; } 16code > span.kw { color: #007020; font-weight: bold; } /* Keyword */
19code > span.dt { color: #902000; } 17code > span.dt { color: #902000; } /* DataType */
20code > span.dv { color: #40a070; } 18code > span.dv { color: #40a070; } /* DecVal */
21code > span.bn { color: #40a070; } 19code > span.bn { color: #40a070; } /* BaseN */
22code > span.fl { color: #40a070; } 20code > span.fl { color: #40a070; } /* Float */
23code > span.ch { color: #4070a0; } 21code > span.ch { color: #4070a0; } /* Char */
24code > span.st { color: #4070a0; } 22code > span.st { color: #4070a0; } /* String */
25code > span.co { color: #60a0b0; font-style: italic; } 23code > span.co { color: #60a0b0; font-style: italic; } /* Comment */
26code > span.ot { color: #007020; } 24code > span.ot { color: #007020; } /* Other */
27code > span.al { color: #ff0000; font-weight: bold; } 25code > span.al { color: #ff0000; font-weight: bold; } /* Alert */
28code > span.fu { color: #06287e; } 26code > span.fu { color: #06287e; } /* Function */
29code > span.er { color: #ff0000; font-weight: bold; } 27code > span.er { color: #ff0000; font-weight: bold; } /* Error */
28code > span.wa { color: #60a0b0; font-weight: bold; font-style: italic; } /* Warning */
29code > span.cn { color: #880000; } /* Constant */
30code > span.sc { color: #4070a0; } /* SpecialChar */
31code > span.vs { color: #4070a0; } /* VerbatimString */
32code > span.ss { color: #bb6688; } /* SpecialString */
33code > span.im { } /* Import */
34code > span.va { color: #19177c; } /* Variable */
35code > span.cf { color: #007020; font-weight: bold; } /* ControlFlow */
36code > span.op { color: #666666; } /* Operator */
37code > span.bu { } /* BuiltIn */
38code > span.ex { } /* Extension */
39code > span.pp { color: #bc7a00; } /* Preprocessor */
40code > span.at { color: #7d9029; } /* Attribute */
41code > span.do { color: #ba2121; font-style: italic; } /* Documentation */
42code > span.an { color: #60a0b0; font-weight: bold; font-style: italic; } /* Annotation */
43code > span.cv { color: #60a0b0; font-weight: bold; font-style: italic; } /* CommentVar */
44code > span.in { color: #60a0b0; font-weight: bold; font-style: italic; } /* Information */
30 </style> 45 </style>
31 <link rel="stylesheet" href="github-markdown.css"> 46 <link rel="stylesheet" href="github-markdown.css">
47 <!--[if lt IE 9]>
48 <script src="//cdnjs.cloudflare.com/ajax/libs/html5shiv/3.7.3/html5shiv-printshiv.min.js"></script>
49 <![endif]-->
32</head> 50</head>
33<body> 51<body>
34<div id="local-sidebar"> 52<div id="local-sidebar">
@@ -39,18 +57,26 @@ code > span.er { color: #ff0000; font-weight: bold; }
39<li><a href="Download.html">Download</a></li> 57<li><a href="Download.html">Download</a></li>
40<li><a href="Server-requirements.html">Server requirements</a></li> 58<li><a href="Server-requirements.html">Server requirements</a></li>
41<li><a href="Server-configuration.html">Server configuration</a></li> 59<li><a href="Server-configuration.html">Server configuration</a></li>
60<li><a href="Server-security.html">Server security</a></li>
61<li><a href="Shaarli-installation.html">Shaarli installation</a></li>
42<li><a href="Shaarli-configuration.html">Shaarli configuration</a></li> 62<li><a href="Shaarli-configuration.html">Shaarli configuration</a></li>
63<li><a href="Plugin-installation-&amp;-configuration.html">Plugin installation &amp; configuration</a></li>
43</ul></li> 64</ul></li>
65<li><a href="Docker.html">Docker</a></li>
66<li><a href="Plugin-list.html">Plugin list</a></li>
44<li><a href="Usage.html">Usage</a> 67<li><a href="Usage.html">Usage</a>
45<ul> 68<ul>
46<li><a href="Sharing-button.html">Sharing button</a> (bookmarklet)</li> 69<li><a href="Sharing-button.html">Sharing button</a> (bookmarklet)</li>
70<li><a href="Browsing-and-Searching.html">Browsing and Searching</a></li>
47<li><a href="Firefox-share.html">Firefox share</a></li> 71<li><a href="Firefox-share.html">Firefox share</a></li>
48<li><a href="RSS-feeds.html">RSS feeds</a></li> 72<li><a href="RSS-feeds.html">RSS feeds</a></li>
49</ul></li> 73</ul></li>
50<li>How To 74<li>How To
51<ul> 75<ul>
52<li><a href="Backup,-restore,-import-and-export.html">Backup, restore, import and export</a></li> 76<li><a href="Backup,-restore,-import-and-export.html">Backup, restore, import and export</a></li>
77<li><a href="Upgrade-from-original-sebsauvage/Shaarli.html">Upgrade from original sebsauvage/Shaarli</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> 78<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>
79<li><a href="Create-and-serve-multiple-Shaarlis-(farm).html">Create and serve multiple Shaarlis (farm)</a></li>
54<li><a href="Download-CSS-styles-from-an-OPML-list.html">Download CSS styles from an OPML list</a></li> 80<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> 81<li><a href="Datastore-hacks.html">Datastore hacks</a></li>
56</ul></li> 82</ul></li>
@@ -62,6 +88,7 @@ code > span.er { color: #ff0000; font-weight: bold; }
62<li><a href="Directory-structure.html">Directory structure</a></li> 88<li><a href="Directory-structure.html">Directory structure</a></li>
63<li><a href="3rd-party-libraries.html">3rd party libraries</a></li> 89<li><a href="3rd-party-libraries.html">3rd party libraries</a></li>
64<li><a href="Plugin-System.html">Plugin System</a></li> 90<li><a href="Plugin-System.html">Plugin System</a></li>
91<li><a href="Release-Shaarli.html">Release Shaarli</a></li>
65<li><a href="Security.html">Security</a></li> 92<li><a href="Security.html">Security</a></li>
66<li><a href="Static-analysis.html">Static analysis</a></li> 93<li><a href="Static-analysis.html">Static analysis</a></li>
67<li><a href="Theming.html">Theming</a></li> 94<li><a href="Theming.html">Theming</a></li>
@@ -79,10 +106,10 @@ code > span.er { color: #ff0000; font-weight: bold; }
79<p><em>Example virtual host configurations for popular web servers</em></p> 106<p><em>Example virtual host configurations for popular web servers</em></p>
80<ul> 107<ul>
81<li><a href="#apache">Apache</a><a href=".html"></a></li> 108<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> 109<li><a href="#nginx">Nginx</a><a href=".html"></a></li>
84</ul> 110</ul>
85<h2 id="prerequisites">Prerequisites</h2> 111<h2 id="prerequisites">Prerequisites</h2>
112<h3 id="shaarli">Shaarli</h3>
86<ul> 113<ul>
87<li>Shaarli is installed in a directory readable/writeable by the user</li> 114<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> 115<li>the correct read/write permissions have been granted to the web server <em>user and/or group</em></li>
@@ -90,25 +117,35 @@ code > span.er { color: #ff0000; font-weight: bold; }
90<li>a key pair (public, private) and a certificate have been generated</li> 117<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> 118<li>the appropriate server SSL extension is installed and active</li>
92</ul> 119</ul>
120<h3 id="https-tls-and-self-signed-certificates">HTTPS, TLS and self-signed certificates</h3>
93<p>Related guides:</p> 121<p>Related guides:</p>
94<ul> 122<ul>
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> 123<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> 124<li><a href="https://workaround.org/certificate-authority">How do I create my own Certificate Authority?</a><a href=".html"></a></li>
125<li>Generate a self-signed certificate (will trigger browser warnings) with apache2: <code>make-ssl-cert generate-default-snakeoil --force-overwrite</code> will create <code>/etc/ssl/certs/ssl-cert-snakeoil.pem</code> and <code>/etc/ssl/private/ssl-cert-snakeoil.key</code></li>
126</ul>
127<h3 id="proxies">Proxies</h3>
128<p>If 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:</p>
129<ul>
130<li><code>X-Forwarded-Proto</code>;</li>
131<li><code>X-Forwarded-Host</code>;</li>
132<li><code>X-Forwarded-For</code>.</li>
97</ul> 133</ul>
134<p>See also <a href="https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&amp;q=label%3Aproxy+">proxy-related</a> issues.<a href=".html"></a></p>
98<h2 id="apache">Apache</h2> 135<h2 id="apache">Apache</h2>
99<h3 id="minimal">Minimal</h3> 136<h3 id="minimal">Minimal</h3>
100<pre class="sourceCode apache"><code class="sourceCode apache"><span class="fu">&lt;VirtualHost</span><span class="ot"> *:80</span><span class="fu">&gt;</span> 137<div class="sourceCode"><pre class="sourceCode apache"><code class="sourceCode apache"><span class="fu">&lt;VirtualHost</span><span class="ot"> *:80</span><span class="fu">&gt;</span>
101 ServerName<span class="st"> shaarli.my-domain.org</span> 138 ServerName<span class="st"> shaarli.my-domain.org</span>
102 DocumentRoot<span class="st"> /absolute/path/to/shaarli/</span> 139 DocumentRoot<span class="st"> /absolute/path/to/shaarli/</span>
103<span class="fu">&lt;/VirtualHost&gt;</span></code></pre> 140<span class="fu">&lt;/VirtualHost&gt;</span></code></pre></div>
104<h3 id="debug---log-all-the-things">Debug - Log all the things!</h3> 141<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> 142<p>This configuration will log both Apache and PHP errors, which may prove useful to identify server configuration errors.</p>
106<p>See:</p> 143<p>See:</p>
107<ul> 144<ul>
108<li><a href="http://stackoverflow.com/q/176">Apache/PHP - error log per VirtualHost</a> (StackOverflow)<a href=".html"></a></li> 145<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> 146<li><a href="https://ma.ttias.be/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</a><a href=".html"></a></li>
110</ul> 147</ul>
111<pre class="sourceCode apache"><code class="sourceCode apache"><span class="fu">&lt;VirtualHost</span><span class="ot"> *:80</span><span class="fu">&gt;</span> 148<div class="sourceCode"><pre class="sourceCode apache"><code class="sourceCode apache"><span class="fu">&lt;VirtualHost</span><span class="ot"> *:80</span><span class="fu">&gt;</span>
112 ServerName<span class="st"> shaarli.my-domain.org</span> 149 ServerName<span class="st"> shaarli.my-domain.org</span>
113 DocumentRoot<span class="st"> /absolute/path/to/shaarli/</span> 150 DocumentRoot<span class="st"> /absolute/path/to/shaarli/</span>
114 151
@@ -120,24 +157,24 @@ code > span.er { color: #ff0000; font-weight: bold; }
120 php_flag display_errors on 157 php_flag display_errors on
121 php_value error_reporting 2147483647 158 php_value error_reporting 2147483647
122 php_value error_log /var/log/apache2/shaarli-php-error.log 159 php_value error_log /var/log/apache2/shaarli-php-error.log
123<span class="fu">&lt;/VirtualHost&gt;</span></code></pre> 160<span class="fu">&lt;/VirtualHost&gt;</span></code></pre></div>
124<h3 id="standard---keep-access-and-error-logs">Standard - Keep access and error logs</h3> 161<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">&lt;VirtualHost</span><span class="ot"> *:80</span><span class="fu">&gt;</span> 162<div class="sourceCode"><pre class="sourceCode apache"><code class="sourceCode apache"><span class="fu">&lt;VirtualHost</span><span class="ot"> *:80</span><span class="fu">&gt;</span>
126 ServerName<span class="st"> shaarli.my-domain.org</span> 163 ServerName<span class="st"> shaarli.my-domain.org</span>
127 DocumentRoot<span class="st"> /absolute/path/to/shaarli/</span> 164 DocumentRoot<span class="st"> /absolute/path/to/shaarli/</span>
128 165
129 <span class="ot">LogLevel</span><span class="ch"> </span><span class="kw">warn</span> 166 <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> 167 ErrorLog<span class="st"> /var/log/apache2/shaarli-error.log</span>
131 CustomLog<span class="st"> /var/log/apache2/shaarli-access.log combined</span> 168 CustomLog<span class="st"> /var/log/apache2/shaarli-access.log combined</span>
132<span class="fu">&lt;/VirtualHost&gt;</span></code></pre> 169<span class="fu">&lt;/VirtualHost&gt;</span></code></pre></div>
133<h3 id="paranoid---redirect-http-80-to-https-443">Paranoid - Redirect HTTP (:80) to HTTPS (:443)</h3> 170<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> 171<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">&lt;VirtualHost</span><span class="ot"> *:443</span><span class="fu">&gt;</span> 172<div class="sourceCode"><pre class="sourceCode apache"><code class="sourceCode apache"><span class="fu">&lt;VirtualHost</span><span class="ot"> *:443</span><span class="fu">&gt;</span>
136 ServerName<span class="st"> shaarli.my-domain.org</span> 173 ServerName<span class="st"> shaarli.my-domain.org</span>
137 DocumentRoot<span class="st"> /absolute/path/to/shaarli/</span> 174 DocumentRoot<span class="st"> /absolute/path/to/shaarli/</span>
138 175
139 <span class="ot">SSLEngine</span><span class="ch"> </span><span class="kw">on</span> 176 <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> 177 SSLCertificateFile<span class="st"> /absolute/path/to/the/website/certificate.pem</span>
141 SSLCertificateKeyFile<span class="st"> /absolute/path/to/the/website/key.key</span> 178 SSLCertificateKeyFile<span class="st"> /absolute/path/to/the/website/key.key</span>
142 179
143 <span class="fu">&lt;Directory</span><span class="ot"> /absolute/path/to/shaarli/</span><span class="fu">&gt;</span> 180 <span class="fu">&lt;Directory</span><span class="ot"> /absolute/path/to/shaarli/</span><span class="fu">&gt;</span>
@@ -158,7 +195,7 @@ code > span.er { color: #ff0000; font-weight: bold; }
158 <span class="ot">LogLevel</span><span class="ch"> </span><span class="kw">warn</span> 195 <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> 196 ErrorLog<span class="st"> /var/log/apache2/shaarli-error.log</span>
160 CustomLog<span class="st"> /var/log/apache2/shaarli-access.log combined</span> 197 CustomLog<span class="st"> /var/log/apache2/shaarli-access.log combined</span>
161<span class="fu">&lt;/VirtualHost&gt;</span></code></pre> 198<span class="fu">&lt;/VirtualHost&gt;</span></code></pre></div>
162<h2 id="lighthttpd">LightHttpd</h2> 199<h2 id="lighthttpd">LightHttpd</h2>
163<h2 id="nginx">Nginx</h2> 200<h2 id="nginx">Nginx</h2>
164<h3 id="foreword">Foreword</h3> 201<h3 id="foreword">Foreword</h3>
@@ -204,13 +241,13 @@ code > span.er { color: #ff0000; font-weight: bold; }
204<li><code>user:group = john:users</code>,</li> 241<li><code>user:group = john:users</code>,</li>
205</ul> 242</ul>
206<p>which corresponds to the following service configuration:</p> 243<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> 244<div class="sourceCode"><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> 245<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> 246<span class="dt">group </span><span class="ot">=</span><span class="st"> users</span>
210 247
211<span class="kw">[...][]</span><span class="dt">(.html)</span> 248<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> 249<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> 250<span class="dt">listen.group </span><span class="ot">=</span><span class="st"> users</span></code></pre></div>
214<pre class="nginx"><code># /etc/nginx/nginx.conf 251<pre class="nginx"><code># /etc/nginx/nginx.conf
215user john users; 252user john users;
216 253
@@ -374,5 +411,10 @@ http {
374 include php.conf; 411 include php.conf;
375 } 412 }
376}</code></pre> 413}</code></pre>
414<h2 id="restricting-search-engines-and-web-crawler-traffic">Restricting search engines and web crawler traffic</h2>
415<p>Creating a <code>robots.txt</code> witht he following contents at the root of your Shaarli installation will prevent &quot;honest&quot; web crawlers from indexing each and every link and Daily page from a Shaarli instance, thus getting rid of a certain amount of unsollicited network traffic.</p>
416<pre><code>User-agent: *
417Disallow: /</code></pre>
418<p>See: <a href="http://www.robotstxt.org/" class="uri">http://www.robotstxt.org/</a>, <a href="http://www.robotstxt.org/robotstxt.html" class="uri">http://www.robotstxt.org/robotstxt.html</a>, <a href="http://www.robotstxt.org/meta.html" class="uri">http://www.robotstxt.org/meta.html</a></p>
377</body> 419</body>
378</html> 420</html>
generated by cgit v1.2.3 (git 2.25.1) at 2024-12-15 03:36:21 +0000