aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/Shaarli-configuration.md
diff options
context:
space:
mode:
authorArthurHoaro <arthur@hoa.ro>2016-10-12 12:36:59 +0200
committerArthurHoaro <arthur@hoa.ro>2016-10-12 12:36:59 +0200
commitfdf88d194874a533cf3a8de3d317d70018aa8a62 (patch)
treef204fb8ba9e589d4e063c57da01716c487b6e891 /doc/Shaarli-configuration.md
parentdc8e03bfc415d3771a45ccd324078a48b7466cbe (diff)
downloadShaarli-fdf88d194874a533cf3a8de3d317d70018aa8a62.tar.gz
Shaarli-fdf88d194874a533cf3a8de3d317d70018aa8a62.tar.zst
Shaarli-fdf88d194874a533cf3a8de3d317d70018aa8a62.zip
Bump version to v0.8.0
Signed-off-by: ArthurHoaro <arthur@hoa.ro>
Diffstat (limited to 'doc/Shaarli-configuration.md')
-rw-r--r--doc/Shaarli-configuration.md298
1 files changed, 179 insertions, 119 deletions
diff --git a/doc/Shaarli-configuration.md b/doc/Shaarli-configuration.md
index d0560d79..4a783c0e 100644
--- a/doc/Shaarli-configuration.md
+++ b/doc/Shaarli-configuration.md
@@ -1,14 +1,18 @@
1#Shaarli configuration 1#Shaarli configuration
2# Shaarli configuration
3
2## Foreword 4## Foreword
3 5
4**Do not edit configuration options in index.php! Your changes would be lost.** 6**Do not edit configuration options in index.php! Your changes would be lost.**
5 7
6Once your Shaarli instance is installed, the file `data/config.php` is generated: 8Once your Shaarli instance is installed, the file `data/config.json.php` is generated:
7* it contains all settings, and can be edited to customize values 9* it contains all settings in JSON format, and can be edited to customize values
8* it defines which [plugins](Plugin-System) are enabled[](.html) 10* it defines which [plugins](Plugin-System) are enabled[(.html)]((.html).html)
9* its values override those defined in `index.php` 11* its values override those defined in `index.php`
12* it is wrap in a PHP comment to prevent anyone accessing it, regardless of server configuration
10 13
11## File and directory permissions 14## File and directory permissions
15
12The server process running Shaarli must have: 16The server process running Shaarli must have:
13- `read` access to the following resources: 17- `read` access to the following resources:
14 - PHP scripts: `index.php`, `application/*.php`, `plugins/*.php` 18 - PHP scripts: `index.php`, `application/*.php`, `plugins/*.php`
@@ -29,123 +33,179 @@ On a Linux distribution:
29- to give it access to Shaarli, either: 33- to give it access to Shaarli, either:
30 - unzip Shaarli in the default web server location (usually `/var/www/`) and set the web server user as the owner 34 - unzip Shaarli in the default web server location (usually `/var/www/`) and set the web server user as the owner
31 - put users in the same group as the web server, and set the appropriate access rights 35 - put users in the same group as the web server, and set the appropriate access rights
32- if you have a domain / subdomain to serve Shaarli, [configure the server](Server-configuration) accordingly[](.html) 36- if you have a domain / subdomain to serve Shaarli, [configure the server](Server-configuration) accordingly[(.html)]((.html).html)
33 37
34## Example `data/config.php` 38## Configuration
35See also [Plugin System](Plugin-System.html). 39
36 40In `data/config.json.php`.
37```php 41
38<?php 42See also [Plugin System](Plugin-System.html).[](.html)
39// User login 43
40$GLOBALS['login'] = '<login>';[](.html) 44### Credentials
41 45
42// User password hash 46> You shouldn't edit those.
43$GLOBALS['hash'] = '200c452da46c2f889e5e48c49ef044bcacdcb095';[](.html) 47
44 48**login**: Login username.
45// Password salt 49**hash**: Generated password hash.
46$GLOBALS['salt'] = '13b654102321576033d8473b63a275a1bf94c0f0'; [](.html) 50**salt**: Password salt.
47 51
48// Local timezone 52### General
49$GLOBALS['timezone'] = 'Africa/Abidjan';[](.html) 53
50date_default_timezone_set('Africa/Abidjan'); 54**title**: Shaarli's instance title.
51 55**header_link**: Link to the homepage.
52// Shaarli title 56**links_per_page**: Number of shaares displayed per page.
53$GLOBALS['title'] = 'My Little Shaarly';[](.html) 57**timezone**: See [the list of supported timezones](http://php.net/manual/en/timezones.php). [](.html)
54 58**enabled_plugins**: List of enabled plugins.
55// Link the Shaarli title points to 59
56$GLOBALS['titleLink'] = '?';[](.html) 60### Security
57 61
58// HTTP referer redirector 62**session_protection_disabled**: Disable session cookie hijacking protection (not recommended).
59$GLOBALS['redirector'] = '';[](.html) 63It might be useful if your IP adress often changes.
60 64**ban_after**: Failed login attempts before being IP banned.
61// Disable session hijacking 65**ban_duration**: IP ban duration in seconds.
62$GLOBALS['disablesessionprotection'] = false; [](.html) 66**open_shaarli**: Anyone can add a new link while logged out if enabled.
63 67**trusted_proxies**: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy.
64// Whether new links are private by default 68
65$GLOBALS['privateLinkByDefault'] = false;[](.html) 69### Resources
66 70
67// Enabled plugins 71**data_dir**: Data directory.
68// Note: each plugin may provide further settings through its own "config.php" 72**datastore**: Shaarli's links database file path.
69$GLOBALS['config'['ENABLED_PLUGINS'] = array('addlink_toolbar', 'qrcode');]('ENABLED_PLUGINS']-=-array('addlink_toolbar',-'qrcode');.html) 73**updates**: File path for the ran updates file.
70 74**log**: Log file path.
71// Subdirectory where Shaarli stores its data files. 75**update_check**: Last update check file path.
72// You can change it for better security. 76**raintpl_tpl**: Templates directory.
73$GLOBALS['config'['DATADIR'] = 'data';]('DATADIR']-=-'data';.html) 77**raintpl_tmp**: Template engine cache directory.
74 78**thumbnails_cache**: Thumbnails cache directory.
75// File used to store settings 79**page_cache**: Shaarli's internal cache directory.
76$GLOBALS['config'['CONFIG_FILE'] = 'data/config.php';]('CONFIG_FILE']-=-'data/config.php';.html) 80**ban_file**: Banned IP file path.
77 81
78// File containing the link database 82### Updates
79$GLOBALS['config'['DATASTORE'] = 'data/datastore.php';]('DATASTORE']-=-'data/datastore.php';.html) 83
80 84**check_updates**: Enable or disable update check to the git repository.
81// Number of links displayed per page 85**check_updates_branch**: Git branch used to check updates (e.g. `stable` or `master`).
82$GLOBALS['config'['LINKS_PER_PAGE'] = 20;]('LINKS_PER_PAGE']-=-20;.html) 86**check_updates_interval**: Look for new version every N seconds (default: every day).
83 87
84// File recording failed login attempts and IP bans 88### Privacy
85$GLOBALS['config'['IPBANS_FILENAME'] = 'data/ipbans.php';]('IPBANS_FILENAME']-=-'data/ipbans.php';.html) 89
86 90**default_private_links**: Check the private checkbox by default for every new link.
87// Failed login attempts before being banned 91**hide_public_links**: All links are hidden while logged out.
88$GLOBALS['config'['BAN_AFTER'] = 4;]('BAN_AFTER']-=-4;.html) 92**hide_timestamps**: Timestamps are hidden.
89 93
90// Duration of an IP ban, in seconds (30 minutes) 94### Feed
91$GLOBALS['config'['BAN_DURATION'] = 1800;]('BAN_DURATION']-=-1800;.html) 95
92 96**rss_permalinks**: Enable this to redirect RSS links to Shaarli's permalinks instead of shaared URL.
93// If set to true, everyone will be able to add, edit and remove links, 97**show_atom**: Display ATOM feed button.
94// as well as change configuration 98
95$GLOBALS['config'['OPEN_SHAARLI'] = false;]('OPEN_SHAARLI']-=-false;.html) 99### Thumbnail
96 100
97// Do not show link timestamps 101**enable_thumbnails**: Enable or disable thumbnail display.
98$GLOBALS['config'['HIDE_TIMESTAMPS'] = false;]('HIDE_TIMESTAMPS']-=-false;.html) 102**enable_localcache**: Enable or disable local cache.
99 103
100// Set to false to disable local thumbnail cache, e.g. due to limited disk quotas 104### Redirector
101$GLOBALS['config'['ENABLE_THUMBNAILS'] = true;]('ENABLE_THUMBNAILS']-=-true;.html) 105
102 106**url**: Redirector URL, such as `anonym.to`.
103// Thumbnail cache directory 107**encode_url**: Enable this if the redirector needs encoded URL to work properly.
104$GLOBALS['config'['CACHEDIR'] = 'cache';]('CACHEDIR']-=-'cache';.html) 108
105 109## Configuration file example
106// Enable feed (rss, atom, dailyrss) cache 110
107$GLOBALS['config'['ENABLE_LOCALCACHE'] = true;]('ENABLE_LOCALCACHE']-=-true;.html) 111```json
108 112<?php /*
109// Feed cache directory 113{
110$GLOBALS['config'['PAGECACHE'] = 'pagecache';]('PAGECACHE']-=-'pagecache';.html) 114 "credentials": {
111 115 "login": "<login>",
112// RainTPL cache directory (keep the trailing slash!) 116 "hash": "<password hash>",
113$GLOBALS['config'['RAINTPL_TMP'] = 'tmp/';]('RAINTPL_TMP']-=-'tmp/';.html) 117 "salt": "<password salt>"
114 118 },
115// RainTPL template directory (keep the trailing slash!) 119 "security": {
116$GLOBALS['config'['RAINTPL_TPL'] = 'tpl/';]('RAINTPL_TPL']-=-'tpl/';.html) 120 "ban_after": 4,
117 121 "session_protection_disabled": false,
118// Whether Shaarli checks for new releases at https://github.com/shaarli/Shaarli 122 "ban_duration": 1800,
119$GLOBALS['config'['ENABLE_UPDATECHECK'] = true;]('ENABLE_UPDATECHECK']-=-true;.html) 123 "trusted_proxies": [[](.html)
120 124 "1.2.3.4",
121// File to store the latest Shaarli version 125 "5.6.7.8"
122$GLOBALS['config'['UPDATECHECK_FILENAME'] = 'data/lastupdatecheck.txt';]('UPDATECHECK_FILENAME']-=-'data/lastupdatecheck.txt';.html) 126 ]
123 127 },
124// Delay between version checks (requires to be logged in) (24 hours) 128 "resources": {
125$GLOBALS['config'['UPDATECHECK_INTERVAL'] = 86400;]('UPDATECHECK_INTERVAL']-=-86400;.html) 129 "data_dir": "data",
126 130 "config": "data\/config.php",
127// For each link, display a link to an archived version on archive.org 131 "datastore": "data\/datastore.php",
128$GLOBALS['config'['ARCHIVE_ORG'] = false;]('ARCHIVE_ORG']-=-false;.html) 132 "ban_file": "data\/ipbans.php",
129 133 "updates": "data\/updates.txt",
130// The RSS item links point: 134 "log": "data\/log.txt",
131// true => directly to the link 135 "update_check": "data\/lastupdatecheck.txt",
132// false => to the entry on Shaarli (permalink) 136 "raintpl_tmp": "tmp\/",
133$GLOBALS['config'['ENABLE_RSS_PERMALINKS'] = true;]('ENABLE_RSS_PERMALINKS']-=-true;.html) 137 "raintpl_tpl": "tpl\/",
134 138 "thumbnails_cache": "cache",
135// Hide all links to non-logged users 139 "page_cache": "pagecache"
136$GLOBALS['config'['HIDE_PUBLIC_LINKS'] = false;]('HIDE_PUBLIC_LINKS']-=-false;.html) 140 },
137 141 "general": {
138$GLOBALS['config'['PUBSUBHUB_URL'] = '';]('PUBSUBHUB_URL']-=-'';.html) 142 "check_updates": true,
139 143 "rss_permalinks": true,
140// Show an ATOM Feed button next to the Subscribe (RSS) button. 144 "links_per_page": 20,
141// ATOM feeds are available at the address ?do=atom regardless of this option. 145 "default_private_links": true,
142$GLOBALS['config'['SHOW_ATOM'] = false;]('SHOW_ATOM']-=-false;.html) 146 "enable_thumbnails": true,
143 147 "enable_localcache": true,
144// Set this to true if the redirector requires encoded URL, false otherwise. 148 "check_updates_branch": "stable",
145$GLOBALS['config'['REDIRECTOR_URLENCODE'] = true;]('REDIRECTOR_URLENCODE']-=-true;.html) 149 "check_updates_interval": 86400,
146?> 150 "enabled_plugins": [[](.html)
151 "markdown",
152 "wallabag",
153 "archiveorg"
154 ],
155 "timezone": "Europe\/Paris",
156 "title": "My Shaarli",
157 "header_link": "?"
158 },
159 "extras": {
160 "show_atom": false,
161 "hide_public_links": false,
162 "hide_timestamps": false,
163 "open_shaarli": false,
164 "redirector": "http://anonym.to/?",
165 "redirector_encode_url": false
166 },
167 "general": {
168 "header_link": "?",
169 "links_per_page": 20,
170 "enabled_plugins": [[](.html)
171 "markdown",
172 "wallabag"
173 ],
174 "timezone": "Europe\/Paris",
175 "title": "My Shaarli"
176 },
177 "updates": {
178 "check_updates": true,
179 "check_updates_branch": "stable",
180 "check_updates_interval": 86400
181 },
182 "feed": {
183 "rss_permalinks": true,
184 "show_atom": false
185 },
186 "privacy": {
187 "default_private_links": true,
188 "hide_public_links": false,
189 "hide_timestamps": false
190 },
191 "thumbnail": {
192 "enable_thumbnails": true,
193 "enable_localcache": true
194 },
195 "redirector": {
196 "url": "http://anonym.to/?",
197 "encode_url": false
198 },
199 "plugins": {
200 "WALLABAG_URL": "http://demo.wallabag.org",
201 "WALLABAG_VERSION": "1"
202 }
203} ?>
147``` 204```
148 205
149## Additional configuration 206## Additional configuration
150 207
151The playvideos plugin may require that you adapt your server's [Content Security Policy](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md#troubleshooting) configuration to work properly.[](.html) 208The playvideos plugin may require that you adapt your server's
209[Content Security Policy](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md#troubleshooting) [](.html)
210configuration to work properly.[(.html)]((.html).html)
211