aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/md/Shaarli-configuration.md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/md/Shaarli-configuration.md')
-rw-r--r--doc/md/Shaarli-configuration.md217
1 files changed, 217 insertions, 0 deletions
diff --git a/doc/md/Shaarli-configuration.md b/doc/md/Shaarli-configuration.md
new file mode 100644
index 00000000..0c605459
--- /dev/null
+++ b/doc/md/Shaarli-configuration.md
@@ -0,0 +1,217 @@
1## Foreword
2
3**Do not edit configuration options in index.php! Your changes would be lost.**
4
5Once your Shaarli instance is installed, the file `data/config.json.php` is generated:
6* it contains all settings in JSON format, and can be edited to customize values
7* it defines which [plugins](Plugin-System) are enabled[](.html)
8* its values override those defined in `index.php`
9* it is wrap in a PHP comment to prevent anyone accessing it, regardless of server configuration
10
11## File and directory permissions
12
13The server process running Shaarli must have:
14
15- `read` access to the following resources:
16 - PHP scripts: `index.php`, `application/*.php`, `plugins/*.php`
17 - 3rd party PHP and Javascript libraries: `inc/*.php`, `inc/*.js`
18 - static assets:
19 - CSS stylesheets: `inc/*.css`
20 - `images/*`
21 - RainTPL templates: `tpl/*.html`
22- `read`, `write` and `execution` access to the following directories:
23 - `cache` - thumbnail cache
24 - `data` - link data store, configuration options
25 - `pagecache` - Atom/RSS feed cache
26 - `tmp` - RainTPL page cache
27
28On a Linux distribution:
29
30- the web server user will likely be `www` or `http` (for Apache2)
31- it will be a member of a group of the same name: `www:www`, `http:http`
32- to give it access to Shaarli, either:
33 - unzip Shaarli in the default web server location (usually `/var/www/`) and set the web server user as the owner
34 - put users in the same group as the web server, and set the appropriate access rights
35- if you have a domain / subdomain to serve Shaarli, [configure the server](Server-configuration) accordingly[](.html)
36
37## Configuration
38
39In `data/config.json.php`.
40
41See also [Plugin System](Plugin-System.html).
42
43### Credentials
44
45> You shouldn't edit those.
46
47**login**: Login username.
48**hash**: Generated password hash.
49**salt**: Password salt.
50
51### General
52
53**title**: Shaarli's instance title.
54**header_link**: Link to the homepage.
55**links_per_page**: Number of shaares displayed per page.
56**timezone**: See [the list of supported timezones](http://php.net/manual/en/timezones.php).
57**enabled_plugins**: List of enabled plugins.
58
59### Security
60
61**session_protection_disabled**: Disable session cookie hijacking protection (not recommended).
62It might be useful if your IP adress often changes.
63**ban_after**: Failed login attempts before being IP banned.
64**ban_duration**: IP ban duration in seconds.
65**open_shaarli**: Anyone can add a new link while logged out if enabled.
66**trusted_proxies**: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy.
67**allowed_protocols**: List of allowed protocols in shaare URLs or markdown-rendered descriptions. Useful if you want to store `javascript:` links (bookmarklets) in Shaarli (default: `["ftp", "ftps", "magnet"]`).
68
69### Resources
70
71**data_dir**: Data directory.
72**datastore**: Shaarli's links database file path.
73**history**: Shaarli's operation history file path.
74**updates**: File path for the ran updates file.
75**log**: Log file path.
76**update_check**: Last update check file path.
77**raintpl_tpl**: Templates directory.
78**raintpl_tmp**: Template engine cache directory.
79**thumbnails_cache**: Thumbnails cache directory.
80**page_cache**: Shaarli's internal cache directory.
81**ban_file**: Banned IP file path.
82
83### Updates
84
85**check_updates**: Enable or disable update check to the git repository.
86**check_updates_branch**: Git branch used to check updates (e.g. `stable` or `master`).
87**check_updates_interval**: Look for new version every N seconds (default: every day).
88
89### Privacy
90
91**default_private_links**: Check the private checkbox by default for every new link.
92**hide_public_links**: All links are hidden while logged out.
93**hide_timestamps**: Timestamps are hidden.
94
95### Feed
96
97**rss_permalinks**: Enable this to redirect RSS links to Shaarli's permalinks instead of shaared URL.
98**show_atom**: Display ATOM feed button.
99
100### Thumbnail
101
102**enable_thumbnails**: Enable or disable thumbnail display.
103**enable_localcache**: Enable or disable local cache.
104
105### Redirector
106
107**url**: Redirector URL, such as `anonym.to`.
108**encode_url**: Enable this if the redirector needs encoded URL to work properly.
109
110## Configuration file example
111
112```json
113<?php /*
114{
115 "credentials": {
116 "login": "<login>",
117 "hash": "<password hash>",
118 "salt": "<password salt>"
119 },
120 "security": {
121 "ban_after": 4,
122 "session_protection_disabled": false,
123 "ban_duration": 1800,
124 "trusted_proxies": [
125 "1.2.3.4",
126 "5.6.7.8"
127 ],
128 "allowed_protocols": [
129 "ftp",
130 "ftps",
131 "magnet"
132 ]
133 },
134 "resources": {
135 "data_dir": "data",
136 "config": "data\/config.php",
137 "datastore": "data\/datastore.php",
138 "ban_file": "data\/ipbans.php",
139 "updates": "data\/updates.txt",
140 "log": "data\/log.txt",
141 "update_check": "data\/lastupdatecheck.txt",
142 "raintpl_tmp": "tmp\/",
143 "raintpl_tpl": "tpl\/",
144 "thumbnails_cache": "cache",
145 "page_cache": "pagecache"
146 },
147 "general": {
148 "check_updates": true,
149 "rss_permalinks": true,
150 "links_per_page": 20,
151 "default_private_links": true,
152 "enable_thumbnails": true,
153 "enable_localcache": true,
154 "check_updates_branch": "stable",
155 "check_updates_interval": 86400,
156 "enabled_plugins": [
157 "markdown",
158 "wallabag",
159 "archiveorg"
160 ],
161 "timezone": "Europe\/Paris",
162 "title": "My Shaarli",
163 "header_link": "?"
164 },
165 "extras": {
166 "show_atom": false,
167 "hide_public_links": false,
168 "hide_timestamps": false,
169 "open_shaarli": false,
170 "redirector": "http://anonym.to/?",
171 "redirector_encode_url": false
172 },
173 "general": {
174 "header_link": "?",
175 "links_per_page": 20,
176 "enabled_plugins": [
177 "markdown",
178 "wallabag"
179 ],
180 "timezone": "Europe\/Paris",
181 "title": "My Shaarli"
182 },
183 "updates": {
184 "check_updates": true,
185 "check_updates_branch": "stable",
186 "check_updates_interval": 86400
187 },
188 "feed": {
189 "rss_permalinks": true,
190 "show_atom": false
191 },
192 "privacy": {
193 "default_private_links": true,
194 "hide_public_links": false,
195 "hide_timestamps": false
196 },
197 "thumbnail": {
198 "enable_thumbnails": true,
199 "enable_localcache": true
200 },
201 "redirector": {
202 "url": "http://anonym.to/?",
203 "encode_url": false
204 },
205 "plugins": {
206 "WALLABAG_URL": "http://demo.wallabag.org",
207 "WALLABAG_VERSION": "1"
208 }
209} ?>
210```
211
212## Additional configuration
213
214The playvideos plugin may require that you adapt your server's
215[Content Security Policy](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md#troubleshooting)
216configuration to work properly.[](.html)
217