aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/md/Shaarli-configuration.md
diff options
context:
space:
mode:
authornodiscc <nodiscc@gmail.com>2017-01-26 18:52:54 +0100
committernodiscc <nodiscc@gmail.com>2017-06-18 00:19:49 +0200
commit53ed6d7d1e678d7486337ce67a2f17b30bac21ac (patch)
treef8bef0164a70bd03d2b9781951c01bdd018f1842 /doc/md/Shaarli-configuration.md
parentd5d22a6d07917865c44148ad76f43c65a929a890 (diff)
downloadShaarli-53ed6d7d1e678d7486337ce67a2f17b30bac21ac.tar.gz
Shaarli-53ed6d7d1e678d7486337ce67a2f17b30bac21ac.tar.zst
Shaarli-53ed6d7d1e678d7486337ce67a2f17b30bac21ac.zip
Generate HTML documentation using MkDocs (WIP)
MkDocs is a static site generator geared towards building project documentation. Documentation source files are written in Markdown, and configured with a single YAML file. * http://www.mkdocs.org/ * http://www.mkdocs.org/user-guide/configuration/ Ref. #312 * remove pandoc-generated HTML documentation * move markdown doc to doc/md/, * mkdocs.yml: * generate HTML doc in doc/html * add pages TOC/ordering * use index.md as index page * Makefile: remove execute permissions from generated files * Makefile: rewrite htmlpages GFM to markdown conversion using sed: awk expression aslo matched '][' which causes invalid output on complex links with images or code blocks * Add mkdocs.yml to .gitattributes, exclude this file from release archives * Makefile: rename: htmldoc -> doc_html target * run make doc: pull latest markdown documentation from wiki * run make htmlpages: update html documentation
Diffstat (limited to 'doc/md/Shaarli-configuration.md')
-rw-r--r--doc/md/Shaarli-configuration.md215
1 files changed, 215 insertions, 0 deletions
diff --git a/doc/md/Shaarli-configuration.md b/doc/md/Shaarli-configuration.md
new file mode 100644
index 00000000..933f5245
--- /dev/null
+++ b/doc/md/Shaarli-configuration.md
@@ -0,0 +1,215 @@
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- `read` access to the following resources:
15 - PHP scripts: `index.php`, `application/*.php`, `plugins/*.php`
16 - 3rd party PHP and Javascript libraries: `inc/*.php`, `inc/*.js`
17 - static assets:
18 - CSS stylesheets: `inc/*.css`
19 - `images/*`
20 - RainTPL templates: `tpl/*.html`
21- `read`, `write` and `execution` access to the following directories:
22 - `cache` - thumbnail cache
23 - `data` - link data store, configuration options
24 - `pagecache` - Atom/RSS feed cache
25 - `tmp` - RainTPL page cache
26
27On a Linux distribution:
28- the web server user will likely be `www` or `http` (for Apache2)
29- it will be a member of a group of the same name: `www:www`, `http:http`
30- to give it access to Shaarli, either:
31 - unzip Shaarli in the default web server location (usually `/var/www/`) and set the web server user as the owner
32 - put users in the same group as the web server, and set the appropriate access rights
33- if you have a domain / subdomain to serve Shaarli, [configure the server](Server-configuration) accordingly[](.html)
34
35## Configuration
36
37In `data/config.json.php`.
38
39See also [Plugin System](Plugin-System.html).
40
41### Credentials
42
43> You shouldn't edit those.
44
45**login**: Login username.
46**hash**: Generated password hash.
47**salt**: Password salt.
48
49### General
50
51**title**: Shaarli's instance title.
52**header_link**: Link to the homepage.
53**links_per_page**: Number of shaares displayed per page.
54**timezone**: See [the list of supported timezones](http://php.net/manual/en/timezones.php).
55**enabled_plugins**: List of enabled plugins.
56
57### Security
58
59**session_protection_disabled**: Disable session cookie hijacking protection (not recommended).
60It might be useful if your IP adress often changes.
61**ban_after**: Failed login attempts before being IP banned.
62**ban_duration**: IP ban duration in seconds.
63**open_shaarli**: Anyone can add a new link while logged out if enabled.
64**trusted_proxies**: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy.
65**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"]`).
66
67### Resources
68
69**data_dir**: Data directory.
70**datastore**: Shaarli's links database file path.
71**history**: Shaarli's operation history file path.
72**updates**: File path for the ran updates file.
73**log**: Log file path.
74**update_check**: Last update check file path.
75**raintpl_tpl**: Templates directory.
76**raintpl_tmp**: Template engine cache directory.
77**thumbnails_cache**: Thumbnails cache directory.
78**page_cache**: Shaarli's internal cache directory.
79**ban_file**: Banned IP file path.
80
81### Updates
82
83**check_updates**: Enable or disable update check to the git repository.
84**check_updates_branch**: Git branch used to check updates (e.g. `stable` or `master`).
85**check_updates_interval**: Look for new version every N seconds (default: every day).
86
87### Privacy
88
89**default_private_links**: Check the private checkbox by default for every new link.
90**hide_public_links**: All links are hidden while logged out.
91**hide_timestamps**: Timestamps are hidden.
92
93### Feed
94
95**rss_permalinks**: Enable this to redirect RSS links to Shaarli's permalinks instead of shaared URL.
96**show_atom**: Display ATOM feed button.
97
98### Thumbnail
99
100**enable_thumbnails**: Enable or disable thumbnail display.
101**enable_localcache**: Enable or disable local cache.
102
103### Redirector
104
105**url**: Redirector URL, such as `anonym.to`.
106**encode_url**: Enable this if the redirector needs encoded URL to work properly.
107
108## Configuration file example
109
110```json
111<?php /*
112{
113 "credentials": {
114 "login": "<login>",
115 "hash": "<password hash>",
116 "salt": "<password salt>"
117 },
118 "security": {
119 "ban_after": 4,
120 "session_protection_disabled": false,
121 "ban_duration": 1800,
122 "trusted_proxies": [
123 "1.2.3.4",
124 "5.6.7.8"
125 ],
126 "allowed_protocols": [
127 "ftp",
128 "ftps",
129 "magnet"
130 ]
131 },
132 "resources": {
133 "data_dir": "data",
134 "config": "data\/config.php",
135 "datastore": "data\/datastore.php",
136 "ban_file": "data\/ipbans.php",
137 "updates": "data\/updates.txt",
138 "log": "data\/log.txt",
139 "update_check": "data\/lastupdatecheck.txt",
140 "raintpl_tmp": "tmp\/",
141 "raintpl_tpl": "tpl\/",
142 "thumbnails_cache": "cache",
143 "page_cache": "pagecache"
144 },
145 "general": {
146 "check_updates": true,
147 "rss_permalinks": true,
148 "links_per_page": 20,
149 "default_private_links": true,
150 "enable_thumbnails": true,
151 "enable_localcache": true,
152 "check_updates_branch": "stable",
153 "check_updates_interval": 86400,
154 "enabled_plugins": [
155 "markdown",
156 "wallabag",
157 "archiveorg"
158 ],
159 "timezone": "Europe\/Paris",
160 "title": "My Shaarli",
161 "header_link": "?"
162 },
163 "extras": {
164 "show_atom": false,
165 "hide_public_links": false,
166 "hide_timestamps": false,
167 "open_shaarli": false,
168 "redirector": "http://anonym.to/?",
169 "redirector_encode_url": false
170 },
171 "general": {
172 "header_link": "?",
173 "links_per_page": 20,
174 "enabled_plugins": [
175 "markdown",
176 "wallabag"
177 ],
178 "timezone": "Europe\/Paris",
179 "title": "My Shaarli"
180 },
181 "updates": {
182 "check_updates": true,
183 "check_updates_branch": "stable",
184 "check_updates_interval": 86400
185 },
186 "feed": {
187 "rss_permalinks": true,
188 "show_atom": false
189 },
190 "privacy": {
191 "default_private_links": true,
192 "hide_public_links": false,
193 "hide_timestamps": false
194 },
195 "thumbnail": {
196 "enable_thumbnails": true,
197 "enable_localcache": true
198 },
199 "redirector": {
200 "url": "http://anonym.to/?",
201 "encode_url": false
202 },
203 "plugins": {
204 "WALLABAG_URL": "http://demo.wallabag.org",
205 "WALLABAG_VERSION": "1"
206 }
207} ?>
208```
209
210## Additional configuration
211
212The playvideos plugin may require that you adapt your server's
213[Content Security Policy](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md#troubleshooting)
214configuration to work properly.[](.html)
215