aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc
diff options
context:
space:
mode:
authorArthurHoaro <arthur@hoa.ro>2020-11-12 13:02:36 +0100
committerArthurHoaro <arthur@hoa.ro>2020-11-12 13:02:36 +0100
commit1409f1c89a7ca01456ae2dcd6357d296e2b99f5a (patch)
treeffa30a9358e82d27be75d8fc5e57f3c8820dc6d3 /doc
parent054e03f37fa29da8066f1a637919f13c7e7dc5d2 (diff)
parenta6935feb22df8d9634189ee87d257da9f03eedbd (diff)
downloadShaarli-1409f1c89a7ca01456ae2dcd6357d296e2b99f5a.tar.gz
Shaarli-1409f1c89a7ca01456ae2dcd6357d296e2b99f5a.tar.zst
Shaarli-1409f1c89a7ca01456ae2dcd6357d296e2b99f5a.zip
Merge branch 'master' into v0.12v0.12.1v0.12
Diffstat (limited to 'doc')
-rw-r--r--doc/md/Docker.md7
-rw-r--r--doc/md/Server-configuration.md63
-rw-r--r--doc/md/Shaarli-configuration.md19
-rw-r--r--doc/md/dev/Development.md12
-rw-r--r--doc/md/dev/Plugin-system.md11
5 files changed, 76 insertions, 36 deletions
diff --git a/doc/md/Docker.md b/doc/md/Docker.md
index c152fe92..fc406c00 100644
--- a/doc/md/Docker.md
+++ b/doc/md/Docker.md
@@ -1,3 +1,4 @@
1
1# Docker 2# Docker
2 3
3[Docker](https://docs.docker.com/get-started/overview/) is an open platform for developing, shipping, and running applications 4[Docker](https://docs.docker.com/get-started/overview/) is an open platform for developing, shipping, and running applications
@@ -113,9 +114,11 @@ $ mkdir shaarli && cd shaarli
113# Download the latest version of Shaarli's docker-compose.yml 114# Download the latest version of Shaarli's docker-compose.yml
114$ curl -L https://raw.githubusercontent.com/shaarli/Shaarli/latest/docker-compose.yml -o docker-compose.yml 115$ curl -L https://raw.githubusercontent.com/shaarli/Shaarli/latest/docker-compose.yml -o docker-compose.yml
115# Create the .env file and fill in your VPS and domain information 116# Create the .env file and fill in your VPS and domain information
116# (replace <MY_SHAARLI_DOMAIN> and <MY_CONTACT_EMAIL> with your actual information) 117# (replace <shaarli.mydomain.org>, <admin@mydomain.org> and <latest> with your actual information)
117$ echo 'SHAARLI_VIRTUAL_HOST=shaarli.mydomain.org' > .env 118$ echo 'SHAARLI_VIRTUAL_HOST=shaarli.mydomain.org' > .env
118$ echo 'SHAARLI_LETSENCRYPT_EMAIL=admin@mydomain.org' >> .env 119$ echo 'SHAARLI_LETSENCRYPT_EMAIL=admin@mydomain.org' >> .env
120# Available Docker tags can be found at https://hub.docker.com/r/shaarli/shaarli/tags
121$ echo 'SHAARLI_DOCKER_TAG=latest' >> .env
119# Pull the Docker images 122# Pull the Docker images
120$ docker-compose pull 123$ docker-compose pull
121# Run! 124# Run!
@@ -224,4 +227,4 @@ $ docker system prune
224- [docker pull](https://docs.docker.com/engine/reference/commandline/pull/) 227- [docker pull](https://docs.docker.com/engine/reference/commandline/pull/)
225- [docker run](https://docs.docker.com/engine/reference/commandline/run/) 228- [docker run](https://docs.docker.com/engine/reference/commandline/run/)
226- [docker-compose logs](https://docs.docker.com/compose/reference/logs/) 229- [docker-compose logs](https://docs.docker.com/compose/reference/logs/)
227- Træfik: [Getting Started](https://docs.traefik.io/), [Docker backend](https://docs.traefik.io/configuration/backends/docker/), [Let's Encrypt](https://docs.traefik.io/user-guide/docker-and-lets-encrypt/), [Docker image](https://hub.docker.com/_/traefik/) \ No newline at end of file 230- Træfik: [Getting Started](https://docs.traefik.io/), [Docker backend](https://docs.traefik.io/configuration/backends/docker/), [Let's Encrypt](https://docs.traefik.io/user-guide/docker-and-lets-encrypt/), [Docker image](https://hub.docker.com/_/traefik/)
diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md
index 297d7c29..a49b6033 100644
--- a/doc/md/Server-configuration.md
+++ b/doc/md/Server-configuration.md
@@ -40,6 +40,8 @@ Supported PHP versions:
40 40
41Version | Status | Shaarli compatibility 41Version | Status | Shaarli compatibility
42:---:|:---:|:---: 42:---:|:---:|:---:
438.0 | Supported | Yes
447.4 | Supported | Yes
437.3 | Supported | Yes 457.3 | Supported | Yes
447.2 | Supported | Yes 467.2 | Supported | Yes
457.1 | Supported | Yes 477.1 | Supported | Yes
@@ -53,7 +55,7 @@ Required PHP extensions:
53 55
54Extension | Required? | Usage 56Extension | Required? | Usage
55---|:---:|--- 57---|:---:|---
56[`openssl`](http://php.net/manual/en/book.openssl.php) | requires | OpenSSL, HTTPS 58[`openssl`](http://php.net/manual/en/book.openssl.php) | required | OpenSSL, HTTPS
57[`php-json`](http://php.net/manual/en/book.json.php) | required | configuration parsing 59[`php-json`](http://php.net/manual/en/book.json.php) | required | configuration parsing
58[`php-simplexml`](https://www.php.net/manual/en/book.simplexml.php) | required | REST API (Slim framework) 60[`php-simplexml`](https://www.php.net/manual/en/book.simplexml.php) | required | REST API (Slim framework)
59[`php-mbstring`](http://php.net/manual/en/book.mbstring.php) | CentOS, Fedora, RHEL, Windows, some hosting providers | multibyte (Unicode) string support 61[`php-mbstring`](http://php.net/manual/en/book.mbstring.php) | CentOS, Fedora, RHEL, Windows, some hosting providers | multibyte (Unicode) string support
@@ -191,19 +193,24 @@ sudo nano /etc/apache2/sites-available/shaarli.mydomain.org.conf
191 Require all granted 193 Require all granted
192 </Directory> 194 </Directory>
193 195
194 <LocationMatch "/\."> 196 # BE CAREFUL: directives order matter!
195 # Prevent accessing dotfiles
196 RedirectMatch 404 ".*"
197 </LocationMatch>
198 197
199 <LocationMatch "\.(?:ico|css|js|gif|jpe?g|png)$"> 198 <FilesMatch ".*\.(?!(ico|css|js|gif|jpe?g|png|ttf|oet|woff2?)$)[^\.]*$">
199 Require all denied
200 </FilesMatch>
201
202 <Files "index.php">
203 Require all granted
204 </Files>
205
206 <FilesMatch "\.(?:ico|css|js|gif|jpe?g|png|ttf|oet|woff2)$">
200 # allow client-side caching of static files 207 # allow client-side caching of static files
201 Header set Cache-Control "max-age=2628000, public, must-revalidate, proxy-revalidate" 208 Header set Cache-Control "max-age=2628000, public, must-revalidate, proxy-revalidate"
202 </LocationMatch> 209 </FilesMatch>
210
203 211
204 # serve the Shaarli favicon from its custom location 212 # serve the Shaarli favicon from its custom location
205 Alias favicon.ico /var/www/shaarli.mydomain.org/images/favicon.ico 213 Alias favicon.ico /var/www/shaarli.mydomain.org/images/favicon.ico
206
207</VirtualHost> 214</VirtualHost>
208``` 215```
209 216
@@ -294,7 +301,7 @@ server {
294 location / { 301 location / {
295 # default index file when no file URI is requested 302 # default index file when no file URI is requested
296 index index.php; 303 index index.php;
297 try_files $uri /index.php$is_args$args; 304 try_files _ /index.php$is_args$args;
298 } 305 }
299 306
300 location ~ (index)\.php$ { 307 location ~ (index)\.php$ {
@@ -307,20 +314,9 @@ server {
307 include fastcgi.conf; 314 include fastcgi.conf;
308 } 315 }
309 316
310 location ~ \.php$ { 317 location ~ /doc/html/ {
311 # deny access to all other PHP scripts 318 default_type "text/html";
312 # disable this if you host other PHP applications on the same virtualhost 319 try_files $uri $uri/ $uri.html =404;
313 deny all;
314 }
315
316 location ~ /\. {
317 # deny access to dotfiles
318 deny all;
319 }
320
321 location ~ ~$ {
322 # deny access to temp editor files, e.g. "script.php~"
323 deny all;
324 } 320 }
325 321
326 location = /favicon.ico { 322 location = /favicon.ico {
@@ -329,13 +325,12 @@ server {
329 } 325 }
330 326
331 # allow client-side caching of static files 327 # allow client-side caching of static files
332 location ~* \.(?:ico|css|js|gif|jpe?g|png)$ { 328 location ~* \.(?:ico|css|js|gif|jpe?g|png|ttf|oet|woff2?)$ {
333 expires max; 329 expires max;
334 add_header Cache-Control "public, must-revalidate, proxy-revalidate"; 330 add_header Cache-Control "public, must-revalidate, proxy-revalidate";
335 # HTTP 1.0 compatibility 331 # HTTP 1.0 compatibility
336 add_header Pragma public; 332 add_header Pragma public;
337 } 333 }
338
339} 334}
340``` 335```
341 336
@@ -360,7 +355,23 @@ sudo systemctl reload nginx
360 355
361If Shaarli is hosted on a server behind a [reverse proxy](https://en.wikipedia.org/wiki/Reverse_proxy) (i.e. there is a proxy server between clients and the web server hosting Shaarli), configure it accordingly. See [Reverse proxy](Reverse-proxy.md) configuration. 356If Shaarli is hosted on a server behind a [reverse proxy](https://en.wikipedia.org/wiki/Reverse_proxy) (i.e. there is a proxy server between clients and the web server hosting Shaarli), configure it accordingly. See [Reverse proxy](Reverse-proxy.md) configuration.
362 357
358## Using Shaarli without URL rewriting
359
360By default, Shaarli uses Slim framework's URL, which requires
361URL rewriting.
362
363If you can't use URL rewriting for any reason (not supported by
364your web server, shared hosting, etc.), you *can* use Shaarli
365without URL rewriting.
366
367You just need to prefix your URL by `/index.php/`.
368Example: instead of accessing `https://shaarli.mydomain.org/`,
369use `https://shaarli.mydomain.org/index.php/`.
363 370
371**Recommended:**
372 * after installation, in the configuration page, set your header link to `/index.php/`.
373 * in your configuration file `config.json.php` set `general.root_url` to
374 `https://shaarli.mydomain.org/index.php/`.
364 375
365## Allow import of large browser bookmarks export 376## Allow import of large browser bookmarks export
366 377
@@ -421,7 +432,7 @@ By default Shaarli already disallows indexing of your local copy of the document
421before = common.conf 432before = common.conf
422[Definition] 433[Definition]
423failregex = \s-\s<HOST>\s-\sLogin failed for user.*$ 434failregex = \s-\s<HOST>\s-\sLogin failed for user.*$
424ignoreregex = 435ignoreregex =
425``` 436```
426 437
427```ini 438```ini
diff --git a/doc/md/Shaarli-configuration.md b/doc/md/Shaarli-configuration.md
index 263fb761..b1326cce 100644
--- a/doc/md/Shaarli-configuration.md
+++ b/doc/md/Shaarli-configuration.md
@@ -74,6 +74,7 @@ Some settings can be configured directly from a web browser by accesing the `Too
74 "timezone": "Europe\/Paris", 74 "timezone": "Europe\/Paris",
75 "title": "My Shaarli", 75 "title": "My Shaarli",
76 "header_link": "?" 76 "header_link": "?"
77 "tags_separator": " "
77 }, 78 },
78 "dev": { 79 "dev": {
79 "debug": false, 80 "debug": false,
@@ -150,8 +151,10 @@ _These settings should not be edited_
150- **timezone**: See [the list of supported timezones](http://php.net/manual/en/timezones.php). 151- **timezone**: See [the list of supported timezones](http://php.net/manual/en/timezones.php).
151- **enabled_plugins**: List of enabled plugins. 152- **enabled_plugins**: List of enabled plugins.
152- **default_note_title**: Default title of a new note. 153- **default_note_title**: Default title of a new note.
154- **enable_async_metadata** (boolean): Retrieve external bookmark metadata asynchronously to prevent bookmark creation slowdown.
153- **retrieve_description** (boolean): If set to true, for every new Shaare Shaarli will try to retrieve the description and keywords from the HTML meta tags. 155- **retrieve_description** (boolean): If set to true, for every new Shaare Shaarli will try to retrieve the description and keywords from the HTML meta tags.
154- **root_url**: Overrides automatic discovery of Shaarli instance's URL (e.g.) `https://sub.domain.tld/shaarli-folder/`. 156- **root_url**: Overrides automatic discovery of Shaarli instance's URL (e.g.) `https://sub.domain.tld/shaarli-folder/`.
157- **tags_separator**: Defines your tags separator (default: whitespace).
155 158
156### Security 159### Security
157 160
@@ -163,6 +166,22 @@ _These settings should not be edited_
163- **trusted_proxies**: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy. 166- **trusted_proxies**: List of trusted IP which won't be banned after failed login attemps. Useful if Shaarli is behind a reverse proxy.
164- **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"]`). 167- **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"]`).
165 168
169### Formatter
170
171Single string value. Default available:
172
173 - `default`: supports line breaks, URL and hashtag auto-links.
174 - `markdown`: supports [Markdown](https://daringfireball.net/projects/markdown/syntax).
175 - `markdownExtra`: adds [extra](https://michelf.ca/projects/php-markdown/extra/) flavor to Markdown.
176
177### Formatter Settings
178
179Additional settings applied to formatters.
180
181#### default
182
183 - **autolink**: boolean to enable or disable automatic linkification of URL and hashtags.
184
166### Resources 185### Resources
167 186
168- **data_dir**: Data directory. 187- **data_dir**: Data directory.
diff --git a/doc/md/dev/Development.md b/doc/md/dev/Development.md
index 5c085e03..c42e8ffe 100644
--- a/doc/md/dev/Development.md
+++ b/doc/md/dev/Development.md
@@ -6,7 +6,7 @@ Please read [Contributing to Shaarli](https://github.com/shaarli/Shaarli/tree/ma
6 6
7 7
8- [Unit tests](Unit-tests) 8- [Unit tests](Unit-tests)
9- Javascript linting - Shaarli uses [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript). 9- Javascript linting - Shaarli uses [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript).
10Run `make eslint` to check JS style. 10Run `make eslint` to check JS style.
11- [GnuPG signature](GnuPG-signature) for tags/releases 11- [GnuPG signature](GnuPG-signature) for tags/releases
12 12
@@ -51,12 +51,12 @@ PHP (managed through [`composer.json`](https://github.com/shaarli/Shaarli/blob/m
51 51
52## Link structure 52## Link structure
53 53
54Every link available through the `LinkDB` object is represented as an array 54Every link available through the `LinkDB` object is represented as an array
55containing the following fields: 55containing the following fields:
56 56
57 * `id` (integer): Unique identifier. 57 * `id` (integer): Unique identifier.
58 * `title` (string): Title of the link. 58 * `title` (string): Title of the link.
59 * `url` (string): URL of the link. Used for displayable links (without redirector, url encoding, etc.). 59 * `url` (string): URL of the link. Used for displayable links (without redirector, url encoding, etc.).
60 Can be absolute or relative for Notes. 60 Can be absolute or relative for Notes.
61 * `real_url` (string): Real destination URL, can be redirected, encoded, etc. 61 * `real_url` (string): Real destination URL, can be redirected, encoded, etc.
62 * `shorturl` (string): Permalink small hash. 62 * `shorturl` (string): Permalink small hash.
@@ -66,7 +66,7 @@ containing the following fields:
66 * `thumbnail` (string|boolean): relative path of the thumbnail cache file, or false if there isn't any. 66 * `thumbnail` (string|boolean): relative path of the thumbnail cache file, or false if there isn't any.
67 * `created` (DateTime): link creation date time. 67 * `created` (DateTime): link creation date time.
68 * `updated` (DateTime): last modification date time. 68 * `updated` (DateTime): last modification date time.
69 69
70Small hashes are used to make a link to an entry in Shaarli. They are unique: the date of the item (eg. `20110923_150523`) is hashed with CRC32, then converted to base64 and some characters are replaced. They are always 6 characters longs and use only `A-Z a-z 0-9 - _` and `@`. 70Small hashes are used to make a link to an entry in Shaarli. They are unique: the date of the item (eg. `20110923_150523`) is hashed with CRC32, then converted to base64 and some characters are replaced. They are always 6 characters longs and use only `A-Z a-z 0-9 - _` and `@`.
71 71
72 72
@@ -163,11 +163,13 @@ See [`.travis.yml`](https://github.com/shaarli/Shaarli/blob/master/.travis.yml).
163 163
164## Static analysis 164## Static analysis
165 165
166Patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), especially: 166Patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), and must follow:
167 167
168- [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard 168- [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard
169- [PSR-2](http://www.php-fig.org/psr/psr-2/) - Coding Style Guide 169- [PSR-2](http://www.php-fig.org/psr/psr-2/) - Coding Style Guide
170- [PSR-12](http://www.php-fig.org/psr/psr-12/) - Extended Coding Style Guide
170 171
172These are enforced on pull requests using our Continuous Integration tools.
171 173
172**Work in progress:** Static analysis is currently being discussed here: in [#95 - Fix coding style (static analysis)](https://github.com/shaarli/Shaarli/issues/95), [#130 - Continuous Integration tools & features](https://github.com/shaarli/Shaarli/issues/130) 174**Work in progress:** Static analysis is currently being discussed here: in [#95 - Fix coding style (static analysis)](https://github.com/shaarli/Shaarli/issues/95), [#130 - Continuous Integration tools & features](https://github.com/shaarli/Shaarli/issues/130)
173 175
diff --git a/doc/md/dev/Plugin-system.md b/doc/md/dev/Plugin-system.md
index c29774de..f09fadc2 100644
--- a/doc/md/dev/Plugin-system.md
+++ b/doc/md/dev/Plugin-system.md
@@ -148,11 +148,16 @@ If a file needs to be included in server end, use simple relative path:
148`PluginManager::$PLUGINS_PATH . '/mything/template.html'`. 148`PluginManager::$PLUGINS_PATH . '/mything/template.html'`.
149 149
150If it needs to be included in front end side (e.g. an image), 150If it needs to be included in front end side (e.g. an image),
151the relative path must be prefixed with special data `_BASE_PATH_`: 151the relative path must be prefixed with special data:
152`($data['_BASE_PATH_'] ?? '') . '/' . PluginManager::$PLUGINS_PATH . '/mything/picture.png`. 152
153 * if it's a link that will need to be processed by Shaarli, use `_BASE_PATH_`:
154 for e.g. `$data['_BASE_PATH_'] . '/admin/tools`.
155 * if you want to include an asset, you need to add the root URL (base path without `/index.php`, for people using Shaarli without URL rewriting), then use `_ROOT_PATH_`:
156 for e.g
157`$['_ROOT_PATH_'] . '/' . PluginManager::$PLUGINS_PATH . '/mything/picture.png`.
153 158
154Note that special placeholders for CSS and JS files (respectively `css_files` and `js_files`) are already prefixed 159Note that special placeholders for CSS and JS files (respectively `css_files` and `js_files`) are already prefixed
155with the base path in template files. 160with the root path in template files.
156 161
157### It's not working! 162### It's not working!
158 163