diff options
Diffstat (limited to 'doc/md/Shaarli-configuration.md')
-rw-r--r-- | doc/md/Shaarli-configuration.md | 244 |
1 files changed, 244 insertions, 0 deletions
diff --git a/doc/md/Shaarli-configuration.md b/doc/md/Shaarli-configuration.md new file mode 100644 index 00000000..920c7e27 --- /dev/null +++ b/doc/md/Shaarli-configuration.md | |||
@@ -0,0 +1,244 @@ | |||
1 | ## Foreword | ||
2 | |||
3 | **Do not edit configuration options in index.php! Your changes would be lost.** | ||
4 | |||
5 | Once 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 | |||
13 | The 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 | |||
28 | On 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 | |||
39 | In `data/config.json.php`. | ||
40 | |||
41 | See also [Plugin System](Plugin-System.html). | ||
42 | |||
43 | ### Credentials | ||
44 | |||
45 | _These settings should not be edited_ | ||
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 | - **default_note_title**: Default title of a new note. | ||
59 | |||
60 | ### Security | ||
61 | |||
62 | - **session_protection_disabled**: Disable session cookie hijacking protection (not recommended). | ||
63 | It might be useful if your IP adress often changes. | ||
64 | - **ban_after**: Failed login attempts before being IP banned. | ||
65 | - **ban_duration**: IP ban duration in seconds. | ||
66 | - **open_shaarli**: Anyone can add a new link while logged out if enabled. | ||
67 | - **trusted_proxies**: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy. | ||
68 | - **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"]`). | ||
69 | |||
70 | ### Resources | ||
71 | |||
72 | - **data_dir**: Data directory. | ||
73 | - **datastore**: Shaarli's links database file path. | ||
74 | - **history**: Shaarli's operation history file path. | ||
75 | - **updates**: File path for the ran updates file. | ||
76 | - **log**: Log file path. | ||
77 | - **update_check**: Last update check file path. | ||
78 | - **raintpl_tpl**: Templates directory. | ||
79 | - **raintpl_tmp**: Template engine cache directory. | ||
80 | - **thumbnails_cache**: Thumbnails cache directory. | ||
81 | - **page_cache**: Shaarli's internal cache directory. | ||
82 | - **ban_file**: Banned IP file path. | ||
83 | |||
84 | ### Translation | ||
85 | |||
86 | - **language**: translation language (also see [Translations](Translations)) | ||
87 | - **auto** (default): The translation language is chosen from the browser locale. | ||
88 | It means that the language can be different for 2 different visitors depending on their locale. | ||
89 | - **en**: Use the English translation. | ||
90 | - **fr**: Use the French translation. | ||
91 | - **mode**: | ||
92 | - **auto** or **php** (default): Use the PHP implementation of gettext (slower) | ||
93 | - **gettext**: Use PHP builtin gettext extension | ||
94 | (faster, but requires `php-gettext` to be installed and to reload the web server on update) | ||
95 | - **extension**: Translation extensions for custom themes or plugins. | ||
96 | Must be an associative array: `translation domain => translation path`. | ||
97 | |||
98 | ### Updates | ||
99 | |||
100 | - **check_updates**: Enable or disable update check to the git repository. | ||
101 | - **check_updates_branch**: Git branch used to check updates (e.g. `stable` or `master`). | ||
102 | - **check_updates_interval**: Look for new version every N seconds (default: every day). | ||
103 | |||
104 | ### Privacy | ||
105 | |||
106 | - **default_private_links**: Check the private checkbox by default for every new link. | ||
107 | - **hide_public_links**: All links are hidden while logged out. | ||
108 | - **force_login**: if **hide_public_links** and this are set to `true`, all anonymous users are redirected to the login page. | ||
109 | - **hide_timestamps**: Timestamps are hidden. | ||
110 | - **remember_user_default**: Default state of the login page's *remember me* checkbox | ||
111 | - `true`: checked by default, `false`: unchecked by default | ||
112 | |||
113 | ### Feed | ||
114 | |||
115 | - **rss_permalinks**: Enable this to redirect RSS links to Shaarli's permalinks instead of shaared URL. | ||
116 | - **show_atom**: Display ATOM feed button. | ||
117 | |||
118 | ### Thumbnail | ||
119 | |||
120 | - **enable_thumbnails**: Enable or disable thumbnail display. | ||
121 | - **enable_localcache**: Enable or disable local cache. | ||
122 | |||
123 | ### Redirector | ||
124 | |||
125 | - **url**: Redirector URL, such as `anonym.to`. | ||
126 | - **encode_url**: Enable this if the redirector needs encoded URL to work properly. | ||
127 | |||
128 | ## Configuration file example | ||
129 | |||
130 | ```json | ||
131 | <?php /* | ||
132 | { | ||
133 | "credentials": { | ||
134 | "login": "<login>", | ||
135 | "hash": "<password hash>", | ||
136 | "salt": "<password salt>" | ||
137 | }, | ||
138 | "security": { | ||
139 | "ban_after": 4, | ||
140 | "session_protection_disabled": false, | ||
141 | "ban_duration": 1800, | ||
142 | "trusted_proxies": [ | ||
143 | "1.2.3.4", | ||
144 | "5.6.7.8" | ||
145 | ], | ||
146 | "allowed_protocols": [ | ||
147 | "ftp", | ||
148 | "ftps", | ||
149 | "magnet" | ||
150 | ] | ||
151 | }, | ||
152 | "resources": { | ||
153 | "data_dir": "data", | ||
154 | "config": "data\/config.php", | ||
155 | "datastore": "data\/datastore.php", | ||
156 | "ban_file": "data\/ipbans.php", | ||
157 | "updates": "data\/updates.txt", | ||
158 | "log": "data\/log.txt", | ||
159 | "update_check": "data\/lastupdatecheck.txt", | ||
160 | "raintpl_tmp": "tmp\/", | ||
161 | "raintpl_tpl": "tpl\/", | ||
162 | "thumbnails_cache": "cache", | ||
163 | "page_cache": "pagecache" | ||
164 | }, | ||
165 | "general": { | ||
166 | "check_updates": true, | ||
167 | "rss_permalinks": true, | ||
168 | "links_per_page": 20, | ||
169 | "default_private_links": true, | ||
170 | "enable_thumbnails": true, | ||
171 | "enable_localcache": true, | ||
172 | "check_updates_branch": "stable", | ||
173 | "check_updates_interval": 86400, | ||
174 | "enabled_plugins": [ | ||
175 | "markdown", | ||
176 | "wallabag", | ||
177 | "archiveorg" | ||
178 | ], | ||
179 | "timezone": "Europe\/Paris", | ||
180 | "title": "My Shaarli", | ||
181 | "header_link": "?" | ||
182 | }, | ||
183 | "extras": { | ||
184 | "show_atom": false, | ||
185 | "hide_public_links": false, | ||
186 | "hide_timestamps": false, | ||
187 | "open_shaarli": false, | ||
188 | "redirector": "http://anonym.to/?", | ||
189 | "redirector_encode_url": false | ||
190 | }, | ||
191 | "general": { | ||
192 | "header_link": "?", | ||
193 | "links_per_page": 20, | ||
194 | "enabled_plugins": [ | ||
195 | "markdown", | ||
196 | "wallabag" | ||
197 | ], | ||
198 | "timezone": "Europe\/Paris", | ||
199 | "title": "My Shaarli" | ||
200 | }, | ||
201 | "updates": { | ||
202 | "check_updates": true, | ||
203 | "check_updates_branch": "stable", | ||
204 | "check_updates_interval": 86400 | ||
205 | }, | ||
206 | "feed": { | ||
207 | "rss_permalinks": true, | ||
208 | "show_atom": false | ||
209 | }, | ||
210 | "privacy": { | ||
211 | "default_private_links": true, | ||
212 | "hide_public_links": false, | ||
213 | "force_login": false, | ||
214 | "hide_timestamps": false, | ||
215 | "remember_user_default": true | ||
216 | }, | ||
217 | "thumbnail": { | ||
218 | "enable_thumbnails": true, | ||
219 | "enable_localcache": true | ||
220 | }, | ||
221 | "redirector": { | ||
222 | "url": "http://anonym.to/?", | ||
223 | "encode_url": false | ||
224 | }, | ||
225 | "plugins": { | ||
226 | "WALLABAG_URL": "http://demo.wallabag.org", | ||
227 | "WALLABAG_VERSION": "1" | ||
228 | }, | ||
229 | "translation": { | ||
230 | "language": "fr", | ||
231 | "mode": "php", | ||
232 | "extensions": { | ||
233 | "demo": "plugins/demo_plugin/languages/" | ||
234 | } | ||
235 | } | ||
236 | } ?> | ||
237 | ``` | ||
238 | |||
239 | ## Additional configuration | ||
240 | |||
241 | The `playvideos` plugin may require that you adapt your server's | ||
242 | [Content Security Policy](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md#troubleshooting) | ||
243 | configuration to work properly. | ||
244 | |||