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=
"../Various-hacks/">Various hacks
</a>
200 <li class=
"toctree-l1">
202 <a class=
"" href=
"../Troubleshooting/">Troubleshooting
</a>
205 <li class=
"toctree-l1">
207 <span class=
"caption-text">Development
</span>
211 <a class=
"" href=
"../Development-guidelines/">Development guidelines
</a>
215 <a class=
"" href=
"../Continuous-integration-tools/">Continuous integration tools
</a>
219 <a class=
"" href=
"../GnuPG-signature/">GnuPG signature
</a>
223 <a class=
"" href=
"../Coding-guidelines/">Coding guidelines
</a>
227 <a class=
"" href=
"../Directory-structure/">Directory structure
</a>
231 <a class=
"" href=
"../3rd-party-libraries/">3rd party libraries
</a>
235 <a class=
"" href=
"../Plugin-System/">Plugin System
</a>
239 <a class=
"" href=
"../Release-Shaarli/">Release Shaarli
</a>
243 <a class=
"" href=
"../Versioning-and-Branches/">Versioning and Branches
</a>
247 <a class=
"" href=
"../Security/">Security
</a>
251 <a class=
"" href=
"../Static-analysis/">Static analysis
</a>
255 <a class=
"" href=
"../Theming/">Theming
</a>
259 <a class=
"" href=
"../Unit-tests/">Unit tests
</a>
264 <li class=
"toctree-l1">
266 <span class=
"caption-text">About
</span>
270 <a class=
"" href=
"../FAQ/">FAQ
</a>
274 <a class=
"" href=
"../Community-&-Related-software/">Community & Related software
</a>
284 <section data-toggle=
"wy-nav-shift" class=
"wy-nav-content-wrap">
287 <nav class=
"wy-nav-top" role=
"navigation" aria-label=
"top navigation">
288 <i data-toggle=
"wy-nav-top" class=
"fa fa-bars"></i>
289 <a href=
"..">Shaarli Documentation
</a>
293 <div class=
"wy-nav-content">
294 <div class=
"rst-content">
295 <div role=
"navigation" aria-label=
"breadcrumbs navigation">
296 <ul class=
"wy-breadcrumbs">
297 <li><a href=
"..">Docs
</a> »</li>
301 <li>Setup
»</li>
305 <li>Shaarli configuration
</li>
306 <li class=
"wy-breadcrumbs-aside">
308 <a href=
"https://github.com/shaarli/Shaarli/edit/master/docs/Shaarli-configuration.md"
309 class=
"icon icon-github"> Edit on GitHub
</a>
316 <div class=
"section">
318 <h2 id=
"foreword">Foreword
</h2>
319 <p><strong>Do not edit configuration options in index.php! Your changes would be lost.
</strong> </p>
320 <p>Once your Shaarli instance is installed, the file
<code>data/config.json.php
</code> is generated:
321 <em> it contains all settings in JSON format, and can be edited to customize values
322 </em> it defines which
<a href=
"../Plugin-System">plugins
</a> are enabled
<a href=
"../.html"></a>
323 <em> its values override those defined in
<code>index.php
</code>
324 </em> it is wrap in a PHP comment to prevent anyone accessing it, regardless of server configuration
</p>
325 <h2 id=
"file-and-directory-permissions">File and directory permissions
</h2>
326 <p>The server process running Shaarli must have:
327 -
<code>read
</code> access to the following resources:
328 - PHP scripts:
<code>index.php
</code>,
<code>application/*.php
</code>,
<code>plugins/*.php
</code>
329 -
3rd party PHP and Javascript libraries:
<code>inc/*.php
</code>,
<code>inc/*.js
</code>
331 - CSS stylesheets:
<code>inc/*.css
</code>
332 -
<code>images/*
</code>
333 - RainTPL templates:
<code>tpl/*.html
</code>
334 -
<code>read
</code>,
<code>write
</code> and
<code>execution
</code> access to the following directories:
335 -
<code>cache
</code> - thumbnail cache
336 -
<code>data
</code> - link data store, configuration options
337 -
<code>pagecache
</code> - Atom/RSS feed cache
338 -
<code>tmp
</code> - RainTPL page cache
</p>
339 <p>On a Linux distribution:
340 - the web server user will likely be
<code>www
</code> or
<code>http
</code> (for Apache2)
341 - it will be a member of a group of the same name:
<code>www:www
</code>,
<code>http:http
</code>
342 - to give it access to Shaarli, either:
343 - unzip Shaarli in the default web server location (usually
<code>/var/www/
</code>) and set the web server user as the owner
344 - put users in the same group as the web server, and set the appropriate access rights
345 - if you have a domain / subdomain to serve Shaarli,
<a href=
"../Server-configuration">configure the server
</a> accordingly
<a href=
"../.html"></a></p>
346 <h2 id=
"configuration">Configuration
</h2>
347 <p>In
<code>data/config.json.php
</code>.
</p>
348 <p>See also
<a href=
"../Plugin-System.html">Plugin System
</a>.
</p>
349 <h3 id=
"credentials">Credentials
</h3>
351 <p>You shouldn't edit those.
</p>
353 <p><strong>login
</strong>: Login username.
<br />
354 <strong>hash
</strong>: Generated password hash.
<br />
355 <strong>salt
</strong>: Password salt.
</p>
356 <h3 id=
"general">General
</h3>
357 <p><strong>title
</strong>: Shaarli's instance title.
<br />
358 <strong>header_link
</strong>: Link to the homepage.
<br />
359 <strong>links_per_page
</strong>: Number of shaares displayed per page.
<br />
360 <strong>timezone
</strong>: See
<a href=
"http://php.net/manual/en/timezones.php">the list of supported timezones
</a>.
<br />
361 <strong>enabled_plugins
</strong>: List of enabled plugins.
</p>
362 <h3 id=
"security">Security
</h3>
363 <p><strong>session_protection_disabled
</strong>: Disable session cookie hijacking protection (not recommended).
364 It might be useful if your IP adress often changes.
<br />
365 <strong>ban_after
</strong>: Failed login attempts before being IP banned.
<br />
366 <strong>ban_duration
</strong>: IP ban duration in seconds.
<br />
367 <strong>open_shaarli
</strong>: Anyone can add a new link while logged out if enabled.
<br />
368 <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 />
369 <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>
370 <h3 id=
"resources">Resources
</h3>
371 <p><strong>data_dir
</strong>: Data directory.
<br />
372 <strong>datastore
</strong>: Shaarli's links database file path.
<br />
373 <strong>history
</strong>: Shaarli's operation history file path.
374 <strong>updates
</strong>: File path for the ran updates file.
<br />
375 <strong>log
</strong>: Log file path.
<br />
376 <strong>update_check
</strong>: Last update check file path.
<br />
377 <strong>raintpl_tpl
</strong>: Templates directory.
<br />
378 <strong>raintpl_tmp
</strong>: Template engine cache directory.
<br />
379 <strong>thumbnails_cache
</strong>: Thumbnails cache directory.
<br />
380 <strong>page_cache
</strong>: Shaarli's internal cache directory.
<br />
381 <strong>ban_file
</strong>: Banned IP file path.
</p>
382 <h3 id=
"updates">Updates
</h3>
383 <p><strong>check_updates
</strong>: Enable or disable update check to the git repository.
<br />
384 <strong>check_updates_branch
</strong>: Git branch used to check updates (e.g.
<code>stable
</code> or
<code>master
</code>).
<br />
385 <strong>check_updates_interval
</strong>: Look for new version every N seconds (default: every day).
</p>
386 <h3 id=
"privacy">Privacy
</h3>
387 <p><strong>default_private_links
</strong>: Check the private checkbox by default for every new link.
<br />
388 <strong>hide_public_links
</strong>: All links are hidden while logged out.
<br />
389 <strong>hide_timestamps
</strong>: Timestamps are hidden.
</p>
390 <h3 id=
"feed">Feed
</h3>
391 <p><strong>rss_permalinks
</strong>: Enable this to redirect RSS links to Shaarli's permalinks instead of shaared URL.
<br />
392 <strong>show_atom
</strong>: Display ATOM feed button.
</p>
393 <h3 id=
"thumbnail">Thumbnail
</h3>
394 <p><strong>enable_thumbnails
</strong>: Enable or disable thumbnail display.
<br />
395 <strong>enable_localcache
</strong>: Enable or disable local cache.
</p>
396 <h3 id=
"redirector">Redirector
</h3>
397 <p><strong>url
</strong>: Redirector URL, such as
<code>anonym.to
</code>.
<br />
398 <strong>encode_url
</strong>: Enable this if the redirector needs encoded URL to work properly.
</p>
399 <h2 id=
"configuration-file-example">Configuration file example
</h2>
400 <pre><code class=
"json"><?php /*
402 "credentials
": {
403 "login
":
"<login
>",
404 "hash
":
"<password hash
>",
405 "salt
":
"<password salt
>"
407 "security
": {
408 "ban_after
":
4,
409 "session_protection_disabled
": false,
410 "ban_duration
":
1800,
411 "trusted_proxies
": [
415 "allowed_protocols
": [
421 "resources
": {
422 "data_dir
":
"data
",
423 "config
":
"data\/config.php
",
424 "datastore
":
"data\/datastore.php
",
425 "ban_file
":
"data\/ipbans.php
",
426 "updates
":
"data\/updates.txt
",
427 "log
":
"data\/log.txt
",
428 "update_check
":
"data\/lastupdatecheck.txt
",
429 "raintpl_tmp
":
"tmp\/
",
430 "raintpl_tpl
":
"tpl\/
",
431 "thumbnails_cache
":
"cache
",
432 "page_cache
":
"pagecache
"
434 "general
": {
435 "check_updates
": true,
436 "rss_permalinks
": true,
437 "links_per_page
":
20,
438 "default_private_links
": true,
439 "enable_thumbnails
": true,
440 "enable_localcache
": true,
441 "check_updates_branch
":
"stable
",
442 "check_updates_interval
":
86400,
443 "enabled_plugins
": [
444 "markdown
",
445 "wallabag
",
446 "archiveorg
"
448 "timezone
":
"Europe\/Paris
",
449 "title
":
"My Shaarli
",
450 "header_link
":
"?
"
452 "extras
": {
453 "show_atom
": false,
454 "hide_public_links
": false,
455 "hide_timestamps
": false,
456 "open_shaarli
": false,
457 "redirector
":
"http://anonym.to/?
",
458 "redirector_encode_url
": false
460 "general
": {
461 "header_link
":
"?
",
462 "links_per_page
":
20,
463 "enabled_plugins
": [
464 "markdown
",
467 "timezone
":
"Europe\/Paris
",
468 "title
":
"My Shaarli
"
470 "updates
": {
471 "check_updates
": true,
472 "check_updates_branch
":
"stable
",
473 "check_updates_interval
":
86400
476 "rss_permalinks
": true,
477 "show_atom
": false
479 "privacy
": {
480 "default_private_links
": true,
481 "hide_public_links
": false,
482 "hide_timestamps
": false
484 "thumbnail
": {
485 "enable_thumbnails
": true,
486 "enable_localcache
": true
488 "redirector
": {
489 "url
":
"http://anonym.to/?
",
490 "encode_url
": false
492 "plugins
": {
493 "WALLABAG_URL
":
"http://demo.wallabag.org
",
494 "WALLABAG_VERSION
":
"1"
499 <h2 id=
"additional-configuration">Additional configuration
</h2>
500 <p>The playvideos plugin may require that you adapt your server's
501 <a href=
"https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md#troubleshooting">Content Security Policy
</a>
502 configuration to work properly.
<a href=
"../.html"></a></p>
508 <div class=
"rst-footer-buttons" role=
"navigation" aria-label=
"footer navigation">
510 <a href=
"../Plugins/" class=
"btn btn-neutral float-right" title=
"Plugins">Next
<span class=
"icon icon-circle-arrow-right"></span></a>
513 <a href=
"../Server-security/" class=
"btn btn-neutral" title=
"Server security"><span class=
"icon icon-circle-arrow-left"></span> Previous
</a>
520 <div role=
"contentinfo">
521 <!-- Copyright etc -->
525 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>.
535 <div class=
"rst-versions" role=
"note" style=
"cursor: pointer">
536 <span class=
"rst-current-version" data-toggle=
"rst-current-version">
538 <a href=
"https://github.com/shaarli/Shaarli" class=
"fa fa-github" style=
"float: left; color: #fcfcfc"> GitHub
</a>
541 <span><a href=
"../Server-security/" style=
"color: #fcfcfc;">« Previous
</a></span>
544 <span style=
"margin-left: 15px"><a href=
"../Plugins/" style=
"color: #fcfcfc">Next
»</a></span>
548 <script src=
"../js/theme.js"></script>