aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/html/Shaarli-configuration
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/html/Shaarli-configuration
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/html/Shaarli-configuration')
-rw-r--r--doc/html/Shaarli-configuration/index.html563
1 files changed, 563 insertions, 0 deletions
diff --git a/doc/html/Shaarli-configuration/index.html b/doc/html/Shaarli-configuration/index.html
new file mode 100644
index 00000000..95a487d0
--- /dev/null
+++ b/doc/html/Shaarli-configuration/index.html
@@ -0,0 +1,563 @@
1<!DOCTYPE html>
2<!--[if IE 8]><html class="no-js lt-ie9" lang="en" > <![endif]-->
3<!--[if gt IE 8]><!--> <html class="no-js" lang="en" > <!--<![endif]-->
4<head>
5 <meta charset="utf-8">
6 <meta http-equiv="X-UA-Compatible" content="IE=edge">
7 <meta name="viewport" content="width=device-width, initial-scale=1.0">
8
9
10 <link rel="shortcut icon" href="../img/favicon.ico">
11 <title>Shaarli configuration - Shaarli Documentation</title>
12 <link href='https://fonts.googleapis.com/css?family=Lato:400,700|Roboto+Slab:400,700|Inconsolata:400,700' rel='stylesheet' type='text/css'>
13
14 <link rel="stylesheet" href="../css/theme.css" type="text/css" />
15 <link rel="stylesheet" href="../css/theme_extra.css" type="text/css" />
16 <link rel="stylesheet" href="../css/highlight.css">
17 <link href="../github-markdown.css" rel="stylesheet">
18
19 <script>
20 // Current page data
21 var mkdocs_page_name = "Shaarli configuration";
22 var mkdocs_page_input_path = "Shaarli-configuration.md";
23 var mkdocs_page_url = "/Shaarli-configuration/";
24 </script>
25
26 <script src="../js/jquery-2.1.1.min.js"></script>
27 <script src="../js/modernizr-2.8.3.min.js"></script>
28 <script type="text/javascript" src="../js/highlight.pack.js"></script>
29
30</head>
31
32<body class="wy-body-for-nav" role="document">
33
34 <div class="wy-grid-for-nav">
35
36
37 <nav data-toggle="wy-nav-shift" class="wy-nav-side stickynav">
38 <div class="wy-side-nav-search">
39 <a href=".." class="icon icon-home"> Shaarli Documentation</a>
40 <div role="search">
41 <form id ="rtd-search-form" class="wy-form" action="../search.html" method="get">
42 <input type="text" name="q" placeholder="Search docs" />
43 </form>
44</div>
45 </div>
46
47 <div class="wy-menu wy-menu-vertical" data-spy="affix" role="navigation" aria-label="main navigation">
48 <ul class="current">
49
50
51 <li class="toctree-l1">
52
53 <a class="" href="..">Home</a>
54 </li>
55
56 <li class="toctree-l1">
57
58 <span class="caption-text">Setup</span>
59 <ul class="subnav">
60 <li class="">
61
62 <a class="" href="../Download-and-Installation/">Download and Installation</a>
63 </li>
64 <li class="">
65
66 <a class="" href="../Upgrade-and-migration/">Upgrade and migration</a>
67 </li>
68 <li class="">
69
70 <a class="" href="../Server-requirements/">Server requirements</a>
71 </li>
72 <li class="">
73
74 <a class="" href="../Server-configuration/">Server configuration</a>
75 </li>
76 <li class="">
77
78 <a class="" href="../Server-security/">Server security</a>
79 </li>
80 <li class=" current">
81
82 <a class="current" href="./">Shaarli configuration</a>
83 <ul class="subnav">
84
85 <li class="toctree-l3"><a href="#foreword">Foreword</a></li>
86
87
88 <li class="toctree-l3"><a href="#file-and-directory-permissions">File and directory permissions</a></li>
89
90
91 <li class="toctree-l3"><a href="#configuration">Configuration</a></li>
92
93 <ul>
94
95 <li><a class="toctree-l4" href="#credentials">Credentials</a></li>
96
97 <li><a class="toctree-l4" href="#general">General</a></li>
98
99 <li><a class="toctree-l4" href="#security">Security</a></li>
100
101 <li><a class="toctree-l4" href="#resources">Resources</a></li>
102
103 <li><a class="toctree-l4" href="#updates">Updates</a></li>
104
105 <li><a class="toctree-l4" href="#privacy">Privacy</a></li>
106
107 <li><a class="toctree-l4" href="#feed">Feed</a></li>
108
109 <li><a class="toctree-l4" href="#thumbnail">Thumbnail</a></li>
110
111 <li><a class="toctree-l4" href="#redirector">Redirector</a></li>
112
113 </ul>
114
115
116 <li class="toctree-l3"><a href="#configuration-file-example">Configuration file example</a></li>
117
118
119 <li class="toctree-l3"><a href="#additional-configuration">Additional configuration</a></li>
120
121
122 </ul>
123 </li>
124 <li class="">
125
126 <a class="" href="../Plugins/">Plugins</a>
127 </li>
128 </ul>
129 </li>
130
131 <li class="toctree-l1">
132
133 <span class="caption-text">Docker</span>
134 <ul class="subnav">
135 <li class="">
136
137 <a class="" href="../Docker-101/">Docker 101</a>
138 </li>
139 <li class="">
140
141 <a class="" href="../Shaarli-images/">Shaarli images</a>
142 </li>
143 <li class="">
144
145 <a class="" href="../Reverse-proxy-configuration/">Reverse proxy configuration</a>
146 </li>
147 <li class="">
148
149 <a class="" href="../Docker-resources/">Docker resources</a>
150 </li>
151 </ul>
152 </li>
153
154 <li class="toctree-l1">
155
156 <span class="caption-text">Usage</span>
157 <ul class="subnav">
158 <li class="">
159
160 <a class="" href="../Features/">Features</a>
161 </li>
162 <li class="">
163
164 <a class="" href="../Bookmarklet/">Bookmarklet</a>
165 </li>
166 <li class="">
167
168 <a class="" href="../Browsing-and-searching/">Browsing and searching</a>
169 </li>
170 <li class="">
171
172 <a class="" href="../Firefox-share/">Firefox share</a>
173 </li>
174 <li class="">
175
176 <a class="" href="../RSS-feeds/">RSS feeds</a>
177 </li>
178 <li class="">
179
180 <a class="" href="../REST-API/">REST API</a>
181 </li>
182 </ul>
183 </li>
184
185 <li class="toctree-l1">
186
187 <span class="caption-text">How To</span>
188 <ul class="subnav">
189 <li class="">
190
191 <a class="" href="../Backup,-restore,-import-and-export/">Backup, restore, import and export</a>
192 </li>
193 <li class="">
194
195 <a class="" href="../Copy-an-existing-installation-over-SSH-and-serve-it-locally/">Copy an existing installation over SSH and serve it locally</a>
196 </li>
197 <li class="">
198
199 <a class="" href="../Create-and-serve-multiple-Shaarlis-(farm)/">Create and serve multiple Shaarlis (farm)</a>
200 </li>
201 <li class="">
202
203 <a class="" href="../Download-CSS-styles-from-an-OPML-list/">Download CSS styles from an OPML list</a>
204 </li>
205 <li class="">
206
207 <a class="" href="../Datastore-hacks/">Datastore hacks</a>
208 </li>
209 </ul>
210 </li>
211
212 <li class="toctree-l1">
213
214 <a class="" href="../Troubleshooting/">Troubleshooting</a>
215 </li>
216
217 <li class="toctree-l1">
218
219 <span class="caption-text">Development</span>
220 <ul class="subnav">
221 <li class="">
222
223 <a class="" href="../Development-guidelines/">Development guidelines</a>
224 </li>
225 <li class="">
226
227 <a class="" href="../Continuous-integration-tools/">Continuous integration tools</a>
228 </li>
229 <li class="">
230
231 <a class="" href="../GnuPG-signature/">GnuPG signature</a>
232 </li>
233 <li class="">
234
235 <a class="" href="../Coding-guidelines/">Coding guidelines</a>
236 </li>
237 <li class="">
238
239 <a class="" href="../Directory-structure/">Directory structure</a>
240 </li>
241 <li class="">
242
243 <a class="" href="../3rd-party-libraries/">3rd party libraries</a>
244 </li>
245 <li class="">
246
247 <a class="" href="../Plugin-System/">Plugin System</a>
248 </li>
249 <li class="">
250
251 <a class="" href="../Release-Shaarli/">Release Shaarli</a>
252 </li>
253 <li class="">
254
255 <a class="" href="../Versioning-and-Branches/">Versioning and Branches</a>
256 </li>
257 <li class="">
258
259 <a class="" href="../Security/">Security</a>
260 </li>
261 <li class="">
262
263 <a class="" href="../Static-analysis/">Static analysis</a>
264 </li>
265 <li class="">
266
267 <a class="" href="../Theming/">Theming</a>
268 </li>
269 <li class="">
270
271 <a class="" href="../Unit-tests/">Unit tests</a>
272 </li>
273 </ul>
274 </li>
275
276 <li class="toctree-l1">
277
278 <span class="caption-text">About</span>
279 <ul class="subnav">
280 <li class="">
281
282 <a class="" href="../FAQ/">FAQ</a>
283 </li>
284 <li class="">
285
286 <a class="" href="../Community-&-Related-software/">Community & Related software</a>
287 </li>
288 </ul>
289 </li>
290
291 </ul>
292 </div>
293 &nbsp;
294 </nav>
295
296 <section data-toggle="wy-nav-shift" class="wy-nav-content-wrap">
297
298
299 <nav class="wy-nav-top" role="navigation" aria-label="top navigation">
300 <i data-toggle="wy-nav-top" class="fa fa-bars"></i>
301 <a href="..">Shaarli Documentation</a>
302 </nav>
303
304
305 <div class="wy-nav-content">
306 <div class="rst-content">
307 <div role="navigation" aria-label="breadcrumbs navigation">
308 <ul class="wy-breadcrumbs">
309 <li><a href="..">Docs</a> &raquo;</li>
310
311
312
313 <li>Setup &raquo;</li>
314
315
316
317 <li>Shaarli configuration</li>
318 <li class="wy-breadcrumbs-aside">
319
320 <a href="https://github.com/shaarli/Shaarli/edit/master/docs/Shaarli-configuration.md"
321 class="icon icon-github"> Edit on GitHub</a>
322
323 </li>
324 </ul>
325 <hr/>
326</div>
327 <div role="main">
328 <div class="section">
329
330 <h2 id="foreword">Foreword</h2>
331<p><strong>Do not edit configuration options in index.php! Your changes would be lost.</strong> </p>
332<p>Once your Shaarli instance is installed, the file <code>data/config.json.php</code> is generated:
333<em> it contains all settings in JSON format, and can be edited to customize values
334</em> it defines which <a href="../Plugin-System">plugins</a> are enabled<a href="../.html"></a>
335<em> its values override those defined in <code>index.php</code>
336</em> it is wrap in a PHP comment to prevent anyone accessing it, regardless of server configuration</p>
337<h2 id="file-and-directory-permissions">File and directory permissions</h2>
338<p>The server process running Shaarli must have:
339- <code>read</code> access to the following resources:
340 - PHP scripts: <code>index.php</code>, <code>application/*.php</code>, <code>plugins/*.php</code>
341 - 3rd party PHP and Javascript libraries: <code>inc/*.php</code>, <code>inc/*.js</code>
342 - static assets:
343 - CSS stylesheets: <code>inc/*.css</code>
344 - <code>images/*</code>
345 - RainTPL templates: <code>tpl/*.html</code>
346- <code>read</code>, <code>write</code> and <code>execution</code> access to the following directories:
347 - <code>cache</code> - thumbnail cache
348 - <code>data</code> - link data store, configuration options
349 - <code>pagecache</code> - Atom/RSS feed cache
350 - <code>tmp</code> - RainTPL page cache</p>
351<p>On a Linux distribution:
352- the web server user will likely be <code>www</code> or <code>http</code> (for Apache2)
353- it will be a member of a group of the same name: <code>www:www</code>, <code>http:http</code>
354- to give it access to Shaarli, either:
355 - unzip Shaarli in the default web server location (usually <code>/var/www/</code>) and set the web server user as the owner
356 - put users in the same group as the web server, and set the appropriate access rights
357- if you have a domain / subdomain to serve Shaarli, <a href="../Server-configuration">configure the server</a> accordingly<a href="../.html"></a></p>
358<h2 id="configuration">Configuration</h2>
359<p>In <code>data/config.json.php</code>.</p>
360<p>See also <a href="../Plugin-System.html">Plugin System</a>.</p>
361<h3 id="credentials">Credentials</h3>
362<blockquote>
363<p>You shouldn't edit those.</p>
364</blockquote>
365<p><strong>login</strong>: Login username.<br />
366<strong>hash</strong>: Generated password hash.<br />
367<strong>salt</strong>: Password salt.</p>
368<h3 id="general">General</h3>
369<p><strong>title</strong>: Shaarli's instance title.<br />
370<strong>header_link</strong>: Link to the homepage.<br />
371<strong>links_per_page</strong>: Number of shaares displayed per page.<br />
372<strong>timezone</strong>: See <a href="http://php.net/manual/en/timezones.php">the list of supported timezones</a>.<br />
373<strong>enabled_plugins</strong>: List of enabled plugins.</p>
374<h3 id="security">Security</h3>
375<p><strong>session_protection_disabled</strong>: Disable session cookie hijacking protection (not recommended).
376It might be useful if your IP adress often changes.<br />
377<strong>ban_after</strong>: Failed login attempts before being IP banned.<br />
378<strong>ban_duration</strong>: IP ban duration in seconds.<br />
379<strong>open_shaarli</strong>: Anyone can add a new link while logged out if enabled.<br />
380<strong>trusted_proxies</strong>: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy.<br />
381<strong>allowed_protocols</strong>: List of allowed protocols in shaare URLs or markdown-rendered descriptions. Useful if you want to store <code>javascript:</code> links (bookmarklets) in Shaarli (default: <code>["ftp", "ftps", "magnet"]</code>).</p>
382<h3 id="resources">Resources</h3>
383<p><strong>data_dir</strong>: Data directory.<br />
384<strong>datastore</strong>: Shaarli's links database file path.<br />
385<strong>history</strong>: Shaarli's operation history file path.
386<strong>updates</strong>: File path for the ran updates file.<br />
387<strong>log</strong>: Log file path.<br />
388<strong>update_check</strong>: Last update check file path.<br />
389<strong>raintpl_tpl</strong>: Templates directory.<br />
390<strong>raintpl_tmp</strong>: Template engine cache directory.<br />
391<strong>thumbnails_cache</strong>: Thumbnails cache directory.<br />
392<strong>page_cache</strong>: Shaarli's internal cache directory.<br />
393<strong>ban_file</strong>: Banned IP file path.</p>
394<h3 id="updates">Updates</h3>
395<p><strong>check_updates</strong>: Enable or disable update check to the git repository.<br />
396<strong>check_updates_branch</strong>: Git branch used to check updates (e.g. <code>stable</code> or <code>master</code>).<br />
397<strong>check_updates_interval</strong>: Look for new version every N seconds (default: every day).</p>
398<h3 id="privacy">Privacy</h3>
399<p><strong>default_private_links</strong>: Check the private checkbox by default for every new link.<br />
400<strong>hide_public_links</strong>: All links are hidden while logged out.<br />
401<strong>hide_timestamps</strong>: Timestamps are hidden.</p>
402<h3 id="feed">Feed</h3>
403<p><strong>rss_permalinks</strong>: Enable this to redirect RSS links to Shaarli's permalinks instead of shaared URL.<br />
404<strong>show_atom</strong>: Display ATOM feed button.</p>
405<h3 id="thumbnail">Thumbnail</h3>
406<p><strong>enable_thumbnails</strong>: Enable or disable thumbnail display.<br />
407<strong>enable_localcache</strong>: Enable or disable local cache.</p>
408<h3 id="redirector">Redirector</h3>
409<p><strong>url</strong>: Redirector URL, such as <code>anonym.to</code>.<br />
410<strong>encode_url</strong>: Enable this if the redirector needs encoded URL to work properly.</p>
411<h2 id="configuration-file-example">Configuration file example</h2>
412<pre><code class="json">&lt;?php /*
413{
414 &quot;credentials&quot;: {
415 &quot;login&quot;: &quot;&lt;login&gt;&quot;,
416 &quot;hash&quot;: &quot;&lt;password hash&gt;&quot;,
417 &quot;salt&quot;: &quot;&lt;password salt&gt;&quot;
418 },
419 &quot;security&quot;: {
420 &quot;ban_after&quot;: 4,
421 &quot;session_protection_disabled&quot;: false,
422 &quot;ban_duration&quot;: 1800,
423 &quot;trusted_proxies&quot;: [
424 &quot;1.2.3.4&quot;,
425 &quot;5.6.7.8&quot;
426 ],
427 &quot;allowed_protocols&quot;: [
428 &quot;ftp&quot;,
429 &quot;ftps&quot;,
430 &quot;magnet&quot;
431 ]
432 },
433 &quot;resources&quot;: {
434 &quot;data_dir&quot;: &quot;data&quot;,
435 &quot;config&quot;: &quot;data\/config.php&quot;,
436 &quot;datastore&quot;: &quot;data\/datastore.php&quot;,
437 &quot;ban_file&quot;: &quot;data\/ipbans.php&quot;,
438 &quot;updates&quot;: &quot;data\/updates.txt&quot;,
439 &quot;log&quot;: &quot;data\/log.txt&quot;,
440 &quot;update_check&quot;: &quot;data\/lastupdatecheck.txt&quot;,
441 &quot;raintpl_tmp&quot;: &quot;tmp\/&quot;,
442 &quot;raintpl_tpl&quot;: &quot;tpl\/&quot;,
443 &quot;thumbnails_cache&quot;: &quot;cache&quot;,
444 &quot;page_cache&quot;: &quot;pagecache&quot;
445 },
446 &quot;general&quot;: {
447 &quot;check_updates&quot;: true,
448 &quot;rss_permalinks&quot;: true,
449 &quot;links_per_page&quot;: 20,
450 &quot;default_private_links&quot;: true,
451 &quot;enable_thumbnails&quot;: true,
452 &quot;enable_localcache&quot;: true,
453 &quot;check_updates_branch&quot;: &quot;stable&quot;,
454 &quot;check_updates_interval&quot;: 86400,
455 &quot;enabled_plugins&quot;: [
456 &quot;markdown&quot;,
457 &quot;wallabag&quot;,
458 &quot;archiveorg&quot;
459 ],
460 &quot;timezone&quot;: &quot;Europe\/Paris&quot;,
461 &quot;title&quot;: &quot;My Shaarli&quot;,
462 &quot;header_link&quot;: &quot;?&quot;
463 },
464 &quot;extras&quot;: {
465 &quot;show_atom&quot;: false,
466 &quot;hide_public_links&quot;: false,
467 &quot;hide_timestamps&quot;: false,
468 &quot;open_shaarli&quot;: false,
469 &quot;redirector&quot;: &quot;http://anonym.to/?&quot;,
470 &quot;redirector_encode_url&quot;: false
471 },
472 &quot;general&quot;: {
473 &quot;header_link&quot;: &quot;?&quot;,
474 &quot;links_per_page&quot;: 20,
475 &quot;enabled_plugins&quot;: [
476 &quot;markdown&quot;,
477 &quot;wallabag&quot;
478 ],
479 &quot;timezone&quot;: &quot;Europe\/Paris&quot;,
480 &quot;title&quot;: &quot;My Shaarli&quot;
481 },
482 &quot;updates&quot;: {
483 &quot;check_updates&quot;: true,
484 &quot;check_updates_branch&quot;: &quot;stable&quot;,
485 &quot;check_updates_interval&quot;: 86400
486 },
487 &quot;feed&quot;: {
488 &quot;rss_permalinks&quot;: true,
489 &quot;show_atom&quot;: false
490 },
491 &quot;privacy&quot;: {
492 &quot;default_private_links&quot;: true,
493 &quot;hide_public_links&quot;: false,
494 &quot;hide_timestamps&quot;: false
495 },
496 &quot;thumbnail&quot;: {
497 &quot;enable_thumbnails&quot;: true,
498 &quot;enable_localcache&quot;: true
499 },
500 &quot;redirector&quot;: {
501 &quot;url&quot;: &quot;http://anonym.to/?&quot;,
502 &quot;encode_url&quot;: false
503 },
504 &quot;plugins&quot;: {
505 &quot;WALLABAG_URL&quot;: &quot;http://demo.wallabag.org&quot;,
506 &quot;WALLABAG_VERSION&quot;: &quot;1&quot;
507 }
508} ?&gt;
509</code></pre>
510
511<h2 id="additional-configuration">Additional configuration</h2>
512<p>The playvideos plugin may require that you adapt your server's
513<a href="https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md#troubleshooting">Content Security Policy</a>
514configuration to work properly.<a href="../.html"></a></p>
515
516 </div>
517 </div>
518 <footer>
519
520 <div class="rst-footer-buttons" role="navigation" aria-label="footer navigation">
521
522 <a href="../Plugins/" class="btn btn-neutral float-right" title="Plugins">Next <span class="icon icon-circle-arrow-right"></span></a>
523
524
525 <a href="../Server-security/" class="btn btn-neutral" title="Server security"><span class="icon icon-circle-arrow-left"></span> Previous</a>
526
527 </div>
528
529
530 <hr/>
531
532 <div role="contentinfo">
533 <!-- Copyright etc -->
534
535 </div>
536
537 Built with <a href="http://www.mkdocs.org">MkDocs</a> using a <a href="https://github.com/snide/sphinx_rtd_theme">theme</a> provided by <a href="https://readthedocs.org">Read the Docs</a>.
538</footer>
539
540 </div>
541 </div>
542
543 </section>
544
545 </div>
546
547 <div class="rst-versions" role="note" style="cursor: pointer">
548 <span class="rst-current-version" data-toggle="rst-current-version">
549
550 <a href="https://github.com/shaarli/Shaarli" class="fa fa-github" style="float: left; color: #fcfcfc"> GitHub</a>
551
552
553 <span><a href="../Server-security/" style="color: #fcfcfc;">&laquo; Previous</a></span>
554
555
556 <span style="margin-left: 15px"><a href="../Plugins/" style="color: #fcfcfc">Next &raquo;</a></span>
557
558 </span>
559</div>
560 <script src="../js/theme.js"></script>
561
562</body>
563</html>
generated by cgit v1.2.3 (git 2.25.1) at 2024-11-29 15:22:39 +0000