aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/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/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/Shaarli-configuration.md')
-rw-r--r--doc/Shaarli-configuration.md212
1 files changed, 0 insertions, 212 deletions
diff --git a/doc/Shaarli-configuration.md b/doc/Shaarli-configuration.md
deleted file mode 100644
index 25647cb7..00000000
--- a/doc/Shaarli-configuration.md
+++ /dev/null
@@ -1,212 +0,0 @@
1#Shaarli configuration
2# Shaarli configuration
3
4## Foreword
5
6**Do not edit configuration options in index.php! Your changes would be lost.**
7
8Once your Shaarli instance is installed, the file `data/config.json.php` is generated:
9* it contains all settings in JSON format, and can be edited to customize values
10* it defines which [plugins](Plugin-System) are enabled[(.html)]((.html).html)
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
13
14## File and directory permissions
15
16The server process running Shaarli must have:
17- `read` access to the following resources:
18 - PHP scripts: `index.php`, `application/*.php`, `plugins/*.php`
19 - 3rd party PHP and Javascript libraries: `inc/*.php`, `inc/*.js`
20 - static assets:
21 - CSS stylesheets: `inc/*.css`
22 - `images/*`
23 - RainTPL templates: `tpl/*.html`
24- `read`, `write` and `execution` access to the following directories:
25 - `cache` - thumbnail cache
26 - `data` - link data store, configuration options
27 - `pagecache` - Atom/RSS feed cache
28 - `tmp` - RainTPL page cache
29
30On a Linux distribution:
31- the web server user will likely be `www` or `http` (for Apache2)
32- it will be a member of a group of the same name: `www:www`, `http:http`
33- to give it access to Shaarli, either:
34 - unzip Shaarli in the default web server location (usually `/var/www/`) and set the web server user as the owner
35 - put users in the same group as the web server, and set the appropriate access rights
36- if you have a domain / subdomain to serve Shaarli, [configure the server](Server-configuration) accordingly[(.html)]((.html).html)
37
38## Configuration
39
40In `data/config.json.php`.
41
42See also [Plugin System](Plugin-System.html).[](.html)
43
44### Credentials
45
46> You shouldn't edit those.
47
48**login**: Login username.
49**hash**: Generated password hash.
50**salt**: Password salt.
51
52### General
53
54**title**: Shaarli's instance title.
55**header_link**: Link to the homepage.
56**links_per_page**: Number of shaares displayed per page.
57**timezone**: See [the list of supported timezones](http://php.net/manual/en/timezones.php). [](.html)
58**enabled_plugins**: List of enabled plugins.
59
60### Security
61
62**session_protection_disabled**: Disable session cookie hijacking protection (not recommended).
63It 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
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": [[](.html)
125 "1.2.3.4",
126 "5.6.7.8"
127 ]
128 },
129 "resources": {
130 "data_dir": "data",
131 "config": "data\/config.php",
132 "datastore": "data\/datastore.php",
133 "ban_file": "data\/ipbans.php",
134 "updates": "data\/updates.txt",
135 "log": "data\/log.txt",
136 "update_check": "data\/lastupdatecheck.txt",
137 "raintpl_tmp": "tmp\/",
138 "raintpl_tpl": "tpl\/",
139 "thumbnails_cache": "cache",
140 "page_cache": "pagecache"
141 },
142 "general": {
143 "check_updates": true,
144 "rss_permalinks": true,
145 "links_per_page": 20,
146 "default_private_links": true,
147 "enable_thumbnails": true,
148 "enable_localcache": true,
149 "check_updates_branch": "stable",
150 "check_updates_interval": 86400,
151 "enabled_plugins": [[](.html)
152 "markdown",
153 "wallabag",
154 "archiveorg"
155 ],
156 "timezone": "Europe\/Paris",
157 "title": "My Shaarli",
158 "header_link": "?"
159 },
160 "extras": {
161 "show_atom": false,
162 "hide_public_links": false,
163 "hide_timestamps": false,
164 "open_shaarli": false,
165 "redirector": "http://anonym.to/?",
166 "redirector_encode_url": false
167 },
168 "general": {
169 "header_link": "?",
170 "links_per_page": 20,
171 "enabled_plugins": [[](.html)
172 "markdown",
173 "wallabag"
174 ],
175 "timezone": "Europe\/Paris",
176 "title": "My Shaarli"
177 },
178 "updates": {
179 "check_updates": true,
180 "check_updates_branch": "stable",
181 "check_updates_interval": 86400
182 },
183 "feed": {
184 "rss_permalinks": true,
185 "show_atom": false
186 },
187 "privacy": {
188 "default_private_links": true,
189 "hide_public_links": false,
190 "hide_timestamps": false
191 },
192 "thumbnail": {
193 "enable_thumbnails": true,
194 "enable_localcache": true
195 },
196 "redirector": {
197 "url": "http://anonym.to/?",
198 "encode_url": false
199 },
200 "plugins": {
201 "WALLABAG_URL": "http://demo.wallabag.org",
202 "WALLABAG_VERSION": "1"
203 }
204} ?>
205```
206
207## Additional configuration
208
209The playvideos plugin may require that you adapt your server's
210[Content Security Policy](https://github.com/shaarli/Shaarli/blob/master/plugins/playvideos/README.md#troubleshooting) [](.html)
211configuration to work properly.[(.html)]((.html).html)
212