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]-->
6 <meta http-equiv=
"X-UA-Compatible" content=
"IE=edge">
7 <meta name=
"viewport" content=
"width=device-width, initial-scale=1.0">
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'
>
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">
21 var mkdocs_page_name = "Shaarli configuration";
22 var mkdocs_page_input_path = "Shaarli-configuration.md";
23 var mkdocs_page_url = "/Shaarli-configuration/";
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>
32 <body class=
"wy-body-for-nav" role=
"document">
34 <div class=
"wy-grid-for-nav">
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>
41 <form id =
"rtd-search-form" class=
"wy-form" action=
"../search.html" method=
"get">
42 <input type=
"text" name=
"q" placeholder=
"Search docs" />
47 <div class=
"wy-menu wy-menu-vertical" data-spy=
"affix" role=
"navigation" aria-label=
"main navigation">
51 <li class=
"toctree-l1">
53 <a class=
"" href=
"..">Home
</a>
56 <li class=
"toctree-l1">
58 <span class=
"caption-text">Setup
</span>
62 <a class=
"" href=
"../Download-and-Installation/">Download and Installation
</a>
66 <a class=
"" href=
"../Upgrade-and-migration/">Upgrade and migration
</a>
70 <a class=
"" href=
"../Server-requirements/">Server requirements
</a>
74 <a class=
"" href=
"../Server-configuration/">Server configuration
</a>
78 <a class=
"" href=
"../Server-security/">Server security
</a>
82 <a class=
"current" href=
"./">Shaarli configuration
</a>
85 <li class=
"toctree-l3"><a href=
"#foreword">Foreword
</a></li>
88 <li class=
"toctree-l3"><a href=
"#file-and-directory-permissions">File and directory permissions
</a></li>
91 <li class=
"toctree-l3"><a href=
"#configuration">Configuration
</a></li>
95 <li><a class=
"toctree-l4" href=
"#credentials">Credentials
</a></li>
97 <li><a class=
"toctree-l4" href=
"#general">General
</a></li>
99 <li><a class=
"toctree-l4" href=
"#security">Security
</a></li>
101 <li><a class=
"toctree-l4" href=
"#resources">Resources
</a></li>
103 <li><a class=
"toctree-l4" href=
"#updates">Updates
</a></li>
105 <li><a class=
"toctree-l4" href=
"#privacy">Privacy
</a></li>
107 <li><a class=
"toctree-l4" href=
"#feed">Feed
</a></li>
109 <li><a class=
"toctree-l4" href=
"#thumbnail">Thumbnail
</a></li>
111 <li><a class=
"toctree-l4" href=
"#redirector">Redirector
</a></li>
116 <li class=
"toctree-l3"><a href=
"#configuration-file-example">Configuration file example
</a></li>
119 <li class=
"toctree-l3"><a href=
"#additional-configuration">Additional configuration
</a></li>
126 <a class=
"" href=
"../Plugins/">Plugins
</a>
131 <li class=
"toctree-l1">
133 <span class=
"caption-text">Docker
</span>
137 <a class=
"" href=
"../Docker-101/">Docker
101</a>
141 <a class=
"" href=
"../Shaarli-images/">Shaarli images
</a>
145 <a class=
"" href=
"../Reverse-proxy-configuration/">Reverse proxy configuration
</a>
149 <a class=
"" href=
"../Docker-resources/">Docker resources
</a>
154 <li class=
"toctree-l1">
156 <span class=
"caption-text">Usage
</span>
160 <a class=
"" href=
"../Features/">Features
</a>
164 <a class=
"" href=
"../Bookmarklet/">Bookmarklet
</a>
168 <a class=
"" href=
"../Browsing-and-searching/">Browsing and searching
</a>
172 <a class=
"" href=
"../Firefox-share/">Firefox share
</a>
176 <a class=
"" href=
"../RSS-feeds/">RSS feeds
</a>
180 <a class=
"" href=
"../REST-API/">REST API
</a>
185 <li class=
"toctree-l1">
187 <span class=
"caption-text">How To
</span>
191 <a class=
"" href=
"../Backup,-restore,-import-and-export/">Backup, restore, import and export
</a>
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>
199 <a class=
"" href=
"../Create-and-serve-multiple-Shaarlis-(farm)/">Create and serve multiple Shaarlis (farm)
</a>
203 <a class=
"" href=
"../Download-CSS-styles-from-an-OPML-list/">Download CSS styles from an OPML list
</a>
207 <a class=
"" href=
"../Datastore-hacks/">Datastore hacks
</a>
212 <li class=
"toctree-l1">
214 <a class=
"" href=
"../Troubleshooting/">Troubleshooting
</a>
217 <li class=
"toctree-l1">
219 <span class=
"caption-text">Development
</span>
223 <a class=
"" href=
"../Development-guidelines/">Development guidelines
</a>
227 <a class=
"" href=
"../Continuous-integration-tools/">Continuous integration tools
</a>
231 <a class=
"" href=
"../GnuPG-signature/">GnuPG signature
</a>
235 <a class=
"" href=
"../Coding-guidelines/">Coding guidelines
</a>
239 <a class=
"" href=
"../Directory-structure/">Directory structure
</a>
243 <a class=
"" href=
"../3rd-party-libraries/">3rd party libraries
</a>
247 <a class=
"" href=
"../Plugin-System/">Plugin System
</a>
251 <a class=
"" href=
"../Release-Shaarli/">Release Shaarli
</a>
255 <a class=
"" href=
"../Versioning-and-Branches/">Versioning and Branches
</a>
259 <a class=
"" href=
"../Security/">Security
</a>
263 <a class=
"" href=
"../Static-analysis/">Static analysis
</a>
267 <a class=
"" href=
"../Theming/">Theming
</a>
271 <a class=
"" href=
"../Unit-tests/">Unit tests
</a>
276 <li class=
"toctree-l1">
278 <span class=
"caption-text">About
</span>
282 <a class=
"" href=
"../FAQ/">FAQ
</a>
286 <a class=
"" href=
"../Community-&-Related-software/">Community & Related software
</a>
296 <section data-toggle=
"wy-nav-shift" class=
"wy-nav-content-wrap">
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>
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> »</li>
313 <li>Setup
»</li>
317 <li>Shaarli configuration
</li>
318 <li class=
"wy-breadcrumbs-aside">
320 <a href=
"https://github.com/shaarli/Shaarli/edit/master/docs/Shaarli-configuration.md"
321 class=
"icon icon-github"> Edit on GitHub
</a>
328 <div class=
"section">
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>
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>
363 <p>You shouldn't edit those.
</p>
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).
376 It 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"><?php /*
414 "credentials
": {
415 "login
":
"<login
>",
416 "hash
":
"<password hash
>",
417 "salt
":
"<password salt
>"
419 "security
": {
420 "ban_after
":
4,
421 "session_protection_disabled
": false,
422 "ban_duration
":
1800,
423 "trusted_proxies
": [
427 "allowed_protocols
": [
433 "resources
": {
434 "data_dir
":
"data
",
435 "config
":
"data\/config.php
",
436 "datastore
":
"data\/datastore.php
",
437 "ban_file
":
"data\/ipbans.php
",
438 "updates
":
"data\/updates.txt
",
439 "log
":
"data\/log.txt
",
440 "update_check
":
"data\/lastupdatecheck.txt
",
441 "raintpl_tmp
":
"tmp\/
",
442 "raintpl_tpl
":
"tpl\/
",
443 "thumbnails_cache
":
"cache
",
444 "page_cache
":
"pagecache
"
446 "general
": {
447 "check_updates
": true,
448 "rss_permalinks
": true,
449 "links_per_page
":
20,
450 "default_private_links
": true,
451 "enable_thumbnails
": true,
452 "enable_localcache
": true,
453 "check_updates_branch
":
"stable
",
454 "check_updates_interval
":
86400,
455 "enabled_plugins
": [
456 "markdown
",
457 "wallabag
",
458 "archiveorg
"
460 "timezone
":
"Europe\/Paris
",
461 "title
":
"My Shaarli
",
462 "header_link
":
"?
"
464 "extras
": {
465 "show_atom
": false,
466 "hide_public_links
": false,
467 "hide_timestamps
": false,
468 "open_shaarli
": false,
469 "redirector
":
"http://anonym.to/?
",
470 "redirector_encode_url
": false
472 "general
": {
473 "header_link
":
"?
",
474 "links_per_page
":
20,
475 "enabled_plugins
": [
476 "markdown
",
479 "timezone
":
"Europe\/Paris
",
480 "title
":
"My Shaarli
"
482 "updates
": {
483 "check_updates
": true,
484 "check_updates_branch
":
"stable
",
485 "check_updates_interval
":
86400
488 "rss_permalinks
": true,
489 "show_atom
": false
491 "privacy
": {
492 "default_private_links
": true,
493 "hide_public_links
": false,
494 "hide_timestamps
": false
496 "thumbnail
": {
497 "enable_thumbnails
": true,
498 "enable_localcache
": true
500 "redirector
": {
501 "url
":
"http://anonym.to/?
",
502 "encode_url
": false
504 "plugins
": {
505 "WALLABAG_URL
":
"http://demo.wallabag.org
",
506 "WALLABAG_VERSION
":
"1"
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>
514 configuration to work properly.
<a href=
"../.html"></a></p>
520 <div class=
"rst-footer-buttons" role=
"navigation" aria-label=
"footer navigation">
522 <a href=
"../Plugins/" class=
"btn btn-neutral float-right" title=
"Plugins">Next
<span class=
"icon icon-circle-arrow-right"></span></a>
525 <a href=
"../Server-security/" class=
"btn btn-neutral" title=
"Server security"><span class=
"icon icon-circle-arrow-left"></span> Previous
</a>
532 <div role=
"contentinfo">
533 <!-- Copyright etc -->
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>.
547 <div class=
"rst-versions" role=
"note" style=
"cursor: pointer">
548 <span class=
"rst-current-version" data-toggle=
"rst-current-version">
550 <a href=
"https://github.com/shaarli/Shaarli" class=
"fa fa-github" style=
"float: left; color: #fcfcfc"> GitHub
</a>
553 <span><a href=
"../Server-security/" style=
"color: #fcfcfc;">« Previous
</a></span>
556 <span style=
"margin-left: 15px"><a href=
"../Plugins/" style=
"color: #fcfcfc">Next
»</a></span>
560 <script src=
"../js/theme.js"></script>