aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc
diff options
context:
space:
mode:
authornodiscc <nodiscc@gmail.com>2018-04-20 23:16:59 +0200
committernodiscc <nodiscc@gmail.com>2018-06-17 18:56:00 +0200
commitbdfb967ca2f9d75791a2da2bb189d63df33638cc (patch)
tree877d38339e2648e18390bf6cd1deeaa8c42c6185 /doc
parent26b0b2022870a540c1a6d54e949c4bdc1486daed (diff)
downloadShaarli-bdfb967ca2f9d75791a2da2bb189d63df33638cc.tar.gz
Shaarli-bdfb967ca2f9d75791a2da2bb189d63df33638cc.tar.zst
Shaarli-bdfb967ca2f9d75791a2da2bb189d63df33638cc.zip
Improve documentation (#598, #1105)
* rework/simplify server configuration/requirements pages (consolidate/simplify SSL/TLS/apache configuration) * update index.md introduction * remove external images (badges) * Fix COPYING link and documentation links * Update features list * dedpulicate information * remove server-requirements.md and move relevant doc to other files * TODO: rework nginx configuration (single configuration example, with commented out blocks for special cases) * TODO: consolidate download/install/configuration pages * remove blank lighttpd configuration section * remove Required? column for composer packages, all libraries are mandatory * php 7.2 compatibilty * clarify that certbot binary and paths may vary depending on install method
Diffstat (limited to 'doc')
-rw-r--r--doc/md/3rd-party-libraries.md16
-rw-r--r--doc/md/Download-and-Installation.md7
-rw-r--r--doc/md/Server-configuration.md211
-rw-r--r--doc/md/Server-requirements.md42
-rw-r--r--doc/md/index.md74
5 files changed, 178 insertions, 172 deletions
diff --git a/doc/md/3rd-party-libraries.md b/doc/md/3rd-party-libraries.md
index ebab7a46..7e7dd334 100644
--- a/doc/md/3rd-party-libraries.md
+++ b/doc/md/3rd-party-libraries.md
@@ -1,13 +1,21 @@
1## CSS 1## CSS
2- Yahoo UI [CSS Reset](http://yuilibrary.com/yui/docs/cssreset/) 2
3 - resets default CSS properties for all HTML elements (overriding browsers' default values) 3- Yahoo UI [CSS Reset](http://yuilibrary.com/yui/docs/cssreset/) - standardize cross-browser rendering
4 - ensures custom CSS stylessheets will provide the same results on all browsers
5 4
6## Javascript 5## Javascript
6
7- [Awesomeplete](https://leaverou.github.io/awesomplete/) ([GitHub](https://github.com/LeaVerou/awesomplete)) - autocompletion in input forms 7- [Awesomeplete](https://leaverou.github.io/awesomplete/) ([GitHub](https://github.com/LeaVerou/awesomplete)) - autocompletion in input forms
8- [bLazy](http://dinbror.dk/blazy/) ([GitHub](https://github.com/dinbror/blazy)) - lazy loading for thumbnails 8- [bLazy](http://dinbror.dk/blazy/) ([GitHub](https://github.com/dinbror/blazy)) - lazy loading for thumbnails
9- [qr.js](http://neocotic.com/qr.js/) ([GitHub](https://github.com/neocotic/qr.js)) - QR code generation 9- [qr.js](http://neocotic.com/qr.js/) ([GitHub](https://github.com/neocotic/qr.js)) - QR code generation
10 10
11## PHP 11## PHP
12- [shaarli/netscape-bookmark-parser](https://github.com/shaarli/netscape-bookmark-parser) - Netscape bookmark parser 12
13- [RainTPL](https://github.com/rainphp/raintpl) - HTML templating for PHP 13- [RainTPL](https://github.com/rainphp/raintpl) - HTML templating for PHP
14
15### Composer
16
17Library | Usage
18---|---
19[`shaarli/netscape-bookmark-parser`](https://packagist.org/packages/shaarli/netscape-bookmark-parser) | Import bookmarks from Netscape files
20[`erusev/parsedown`](https://packagist.org/packages/erusev/parsedown) | Parse MarkDown syntax for the MarkDown plugin
21[`slim/slim`](https://packagist.org/packages/slim/slim) | Handle routes and middleware for the REST API
diff --git a/doc/md/Download-and-Installation.md b/doc/md/Download-and-Installation.md
index 20138f49..ebda2e8a 100644
--- a/doc/md/Download-and-Installation.md
+++ b/doc/md/Download-and-Installation.md
@@ -1,8 +1,7 @@
1To install Shaarli, simply place the files in a directory under your webserver's 1To install Shaarli, simply place the files in a directory under your webserver's
2Document Root (or directly at the document root). 2Document Root (or directly at the document root).
3 3
4Also, please make sure your server meets the [requirements](Server-requirements) 4Also, please make sure your server is properly [configured](Server-configuration).
5and is properly [configured](Server-configuration).
6 5
7Multiple releases branches are available: 6Multiple releases branches are available:
8 7
@@ -23,7 +22,7 @@ Using one of the following methods:
23 22
24### Download as an archive 23### Download as an archive
25 24
26In most cases, you should download the latest Shaarli release from the [releases](https://github.com/shaarli/Shaarli/releases) page. **Download our *shaarli-full* archive** to include dependencies. 25In most cases, you should download the latest Shaarli release from the [releases](https://github.com/shaarli/Shaarli/releases) page. Download our **shaarli-full** archive to include dependencies.
27 26
28The current latest released version is `v0.9.6` 27The current latest released version is `v0.9.6`
29 28
@@ -37,7 +36,7 @@ $ mv Shaarli /path/to/shaarli/
37 36
38Cloning using `git` or downloading Github branches as zip files requires additional steps: 37Cloning using `git` or downloading Github branches as zip files requires additional steps:
39 38
40 * Install [Composer](Unit-tests.md#install_composer) to manage Shaarli dependencies. 39 * Install [Composer](Unit-tests.md#install_composer) to manage third-party [PHP dependencies](3rd-party-libraries.md#composer).
41 * Install [yarn](https://yarnpkg.com/lang/en/docs/install/) to build the frontend dependencies. 40 * Install [yarn](https://yarnpkg.com/lang/en/docs/install/) to build the frontend dependencies.
42 * Install [python3-virtualenv](https://pypi.python.org/pypi/virtualenv) to build the local HTML documentation. 41 * Install [python3-virtualenv](https://pypi.python.org/pypi/virtualenv) to build the local HTML documentation.
43 42
diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md
index 25dd49fe..ca82b2ec 100644
--- a/doc/md/Server-configuration.md
+++ b/doc/md/Server-configuration.md
@@ -1,139 +1,130 @@
1*Example virtual host configurations for popular web servers*
2 1
2- [Prerequisites](#prerequisistes)
3- [Apache](#apache) 3- [Apache](#apache)
4- [Nginx](#nginx) 4- [Nginx](#nginx)
5- [Proxies](#proxies)
6- [See also](#see-also)
5 7
6## Prerequisites 8## Prerequisites
7### Shaarli 9### Shaarli
8- Shaarli is installed in a directory readable/writeable by the user
9- the correct read/write permissions have been granted to the web server _user and/or group_
10- for HTTPS / SSL:
11 - a key pair (public, private) and a certificate have been generated
12 - the appropriate server SSL extension is installed and active
13 10
14### HTTPS, TLS and self-signed certificates 11- A web server and PHP interpreter module/service have been installed.
15Related guides: 12- You have write access to the Shaarli installation directory.
13- The correct read/write permissions have been granted to the web server user and group.
14- Your PHP interpreter is compatible with supported PHP versions:
16 15
17- [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php) 16Version | Status | Shaarli compatibility
18- [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority) 17:---:|:---:|:---:
19- Generate a self-signed certificate (will trigger browser warnings) with apache2: 187.2 | Supported | Yes
20 `make-ssl-cert generate-default-snakeoil --force-overwrite` will create `/etc/ssl/certs/ssl-cert-snakeoil.pem` and `/etc/ssl/private/ssl-cert-snakeoil.key` 197.1 | Supported | Yes
207.0 | Supported | Yes
215.6 | Supported | Yes
225.5 | EOL: 2016-07-10 | Yes
235.4 | EOL: 2015-09-14 | Yes (up to Shaarli 0.8.x)
245.3 | EOL: 2014-08-14 | Yes (up to Shaarli 0.8.x)
21 25
22### Proxies 26- The following PHP extensions are installed on the server:
23If Shaarli is served behind a proxy (i.e. there is a proxy server between clients and the web server hosting Shaarli), please refer to the proxy server documentation for proper configuration. In particular, you have to ensure that the following server variables are properly set:
24 27
25- `X-Forwarded-Proto` 28Extension | Required? | Usage
26- `X-Forwarded-Host` 29---|:---:|---
27- `X-Forwarded-For` 30[`openssl`](http://php.net/manual/en/book.openssl.php) | All | OpenSSL, HTTPS
31[`php-mbstring`](http://php.net/manual/en/book.mbstring.php) | CentOS, Fedora, RHEL, Windows, some hosting providers | multibyte (Unicode) string support
32[`php-gd`](http://php.net/manual/en/book.image.php) | optional | thumbnail resizing
33[`php-intl`](http://php.net/manual/en/book.intl.php) | optional | localized text sorting (e.g. `e->è->f`)
34[`php-curl`](http://php.net/manual/en/book.curl.php) | optional | using cURL for fetching webpages and thumbnails in a more robust way
35[`php-gettext`](http://php.net/manual/en/book.gettext.php) | optional | Use the translation system in gettext mode (faster)
28 36
29See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues. 37--------------------------------------------------------------------------------
30 38
31## Apache 39### SSL/TLS configuration
32### Minimal
33```apache
34<VirtualHost *:80>
35 ServerName shaarli.my-domain.org
36 DocumentRoot /absolute/path/to/shaarli/
37</VirtualHost>
38```
39### Debug - Log all the things!
40This configuration will log both Apache and PHP errors, which may prove useful to identify server configuration errors.
41 40
42See: 41To setup HTTPS / SSL on your webserver (recommended), you must generate a public/private **key pair** and a **certificate**, and install, configure and activate the appropriate **webserver SSL extension**.
43 42
44- [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow) 43#### Let's Encrypt
45- [PHP: php_value vs php_admin_value and the use of php_flag explained](https://ma.ttias.be/php-php_value-vs-php_admin_value-and-the-use-of-php_flag-explained/)
46 44
47```apache 45[Let's Encrypt](https://en.wikipedia.org/wiki/Let%27s_Encrypt) is a certificate authority that provides free TLS/X.509 certificates via an automated process.
48<VirtualHost *:80>
49 ServerName shaarli.my-domain.org
50 DocumentRoot /absolute/path/to/shaarli/
51 46
52 LogLevel warn 47 * Install `certbot` using the appropriate method described on https://certbot.eff.org/.
53 ErrorLog /var/log/apache2/shaarli-error.log 48
54 CustomLog /var/log/apache2/shaarli-access.log combined 49Location of the `certbot` program and template configuration files may vary depending on which installation method was used. Change the file paths below accordingly. Here is an easy way to create a signed certificate using `certbot`, it assumes `certbot` was installed through APT on a Debian-based distribution:
55 50
56 php_flag log_errors on 51 * Stop the apache2/nginx service.
57 php_flag display_errors on 52 * Run `certbot --agree-tos --standalone --preferred-challenges tls-sni --email "youremail@example.com" --domain yourdomain.example.com`
58 php_value error_reporting 2147483647 53 * For the Apache webserver, copy `/usr/lib/python2.7/dist-packages/certbot_apache/options-ssl-apache.conf` to `/etc/letsencrypt/options-ssl-apache.conf` (paths may vary depending on installation method)
59 php_value error_log /var/log/apache2/shaarli-php-error.log 54 * For Nginx: TODO
60</VirtualHost> 55 * Setup your webserver as described below
61``` 56 * Restart the apache2/nginx service.
57
58#### Self-signed certificates
59
60If you don't want to request a certificate from Let's Encrypt, or are unable to (for example, webserver on a LAN, or domain name not registered in the public DNS system), you can generate a self-signed certificate. This certificate will trigger security warnings in web browsers, unless you add it to the browser's SSL store manually.
61
62* Apache: run `make-ssl-cert generate-default-snakeoil --force-overwrite`
63* Nginx: TODO
64
65--------------------------------------------------------------------------------
66
67## Apache
68
69Here is a basic configuration example for the Apache web server with `mod_php`.
70
71In `/etc/apache2/sites-available/shaarli.conf`:
62 72
63### Standard - Keep access and error logs
64```apache 73```apache
65<VirtualHost *:80> 74<VirtualHost *:443>
66 ServerName shaarli.my-domain.org 75 ServerName shaarli.my-domain.org
67 DocumentRoot /absolute/path/to/shaarli/ 76 DocumentRoot /absolute/path/to/shaarli/
68 77
78 # Logging
79 # Possible values include: debug, info, notice, warn, error, crit, alert, emerg.
69 LogLevel warn 80 LogLevel warn
70 ErrorLog /var/log/apache2/shaarli-error.log 81 ErrorLog /var/log/apache2/shaarli-error.log
71 CustomLog /var/log/apache2/shaarli-access.log combined 82 CustomLog /var/log/apache2/shaarli-access.log combined
72</VirtualHost>
73```
74 83
75### Paranoid - Redirect HTTP (:80) to HTTPS (:443) 84 # Let's Encrypt SSL configuration (recommended)
76See [Server-side TLS](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache) (Mozilla). 85 SSLEngine on
86 SSLCertificateFile /etc/letsencrypt/live/yourdomain.example.com/fullchain.pem
87 SSLCertificateKeyFile /etc/letsencrypt/live/yourdomain.example.com/privkey.pem
88 Include /etc/letsencrypt/options-ssl-apache.conf
77 89
78```apache 90 # Self-signed SSL cert configuration
79<VirtualHost *:443> 91 #SSLEngine on
80 ServerName shaarli.my-domain.org 92 #SSLCertificateFile /etc/ssl/certs/ssl-cert-snakeoil.pem
81 DocumentRoot /absolute/path/to/shaarli/ 93 #SSLCertificateKeyFile /etc/ssl/private/ssl-cert-snakeoil.key
82 94
83 SSLEngine on 95 # Optional, log PHP errors, useful for debugging
84 SSLCertificateFile /absolute/path/to/the/website/certificate.pem 96 #php_flag log_errors on
85 SSLCertificateKeyFile /absolute/path/to/the/website/key.key 97 #php_flag display_errors on
98 #php_value error_reporting 2147483647
99 #php_value error_log /var/log/apache2/shaarli-php-error.log
86 100
87 <Directory /absolute/path/to/shaarli/> 101 <Directory /absolute/path/to/shaarli/>
102 #Required for .htaccess support
88 AllowOverride All 103 AllowOverride All
89 Options Indexes FollowSymLinks MultiViews
90 Order allow,deny 104 Order allow,deny
91 allow from all 105 Allow from all
92 </Directory>
93 106
94 LogLevel warn 107 Options Indexes FollowSymLinks MultiViews #TODO is Indexes/Multiviews required?
95 ErrorLog /var/log/apache2/shaarli-error.log 108
96 CustomLog /var/log/apache2/shaarli-access.log combined 109 # Optional - required for playvideos plugin
97</VirtualHost> 110 #Header set Content-Security-Policy "script-src 'self' 'unsafe-inline' https://www.youtube.com https://s.ytimg.com 'unsafe-eval'"
98<VirtualHost *:80> 111 </Directory>
99 ServerName shaarli.my-domain.org
100 Redirect 301 / https://shaarli.my-domain.org
101 112
102 LogLevel warn
103 ErrorLog /var/log/apache2/shaarli-error.log
104 CustomLog /var/log/apache2/shaarli-access.log combined
105</VirtualHost> 113</VirtualHost>
106``` 114```
107 115
108### .htaccess 116Enable this configuration with `sudo a2ensite shaarli`
109 117
110Shaarli use `.htaccess` Apache files to deny access to files that shouldn't be directly accessed (datastore, config, etc.). You need the directive `AllowOverride All` in your virtual host configuration for them to work. 118_Note: If you use Apache 2.2 or lower, you need [mod_version](https://httpd.apache.org/docs/current/mod/mod_version.html) to be installed and enabled._
111 119
112**Warning**: If you use Apache 2.2 or lower, you need [mod_version](https://httpd.apache.org/docs/current/mod/mod_version.html) to be installed and enabled. 120_Note: Apache module `mod_rewrite` must be enabled to use the REST API._
113
114Apache module `mod_rewrite` **must** be enabled to use the REST API. URL rewriting rules for the Slim microframework are stated in the root `.htaccess` file.
115 121
116## LightHttpd
117 122
118## Nginx 123## Nginx
119### Foreword
120Nginx does not natively interpret PHP scripts; to this effect, we will run a [FastCGI](https://en.wikipedia.org/wiki/FastCGI) service, to which Nginx's FastCGI module will proxy all requests to PHP resources.
121
122Required packages:
123 124
124- [nginx](http://nginx.org) 125Here is a basic configuration example for the Nginx web server, using the [php-fpm](http://php-fpm.org) PHP FastCGI Process Manager, and Nginx's [FastCGI](https://en.wikipedia.org/wiki/FastCGI) module.
125- [php-fpm](http://php-fpm.org) - PHP FastCGI Process Manager
126 126
127Official documentation: 127<!--- TODO refactor everything below this point --->
128
129- [Beginner's guide](http://nginx.org/en/docs/beginners_guide.html)
130- [ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)
131- [Pitfalls](http://wiki.nginx.org/Pitfalls)
132
133Community resources:
134
135- [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla)
136- [PHP configuration examples](http://kbeezie.com/nginx-configuration-examples/) (Karl Blessing)
137 128
138### Common setup 129### Common setup
139Once Nginx and PHP-FPM are installed, we need to ensure: 130Once Nginx and PHP-FPM are installed, we need to ensure:
@@ -404,3 +395,39 @@ http {
404 } 395 }
405} 396}
406``` 397```
398
399## Proxies
400If Shaarli is served behind a proxy (i.e. there is a proxy server between clients and the web server hosting Shaarli), please refer to the proxy server documentation for proper configuration. In particular, you have to ensure that the following server variables are properly set:
401
402- `X-Forwarded-Proto`
403- `X-Forwarded-Host`
404- `X-Forwarded-For`
405
406See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues.
407
408
409## See also
410
411 * [Server security](Server-security.md)
412
413#### Webservers
414
415- [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow)
416- [Apache - PHP: php_value vs php_admin_value and the use of php_flag explained](https://ma.ttias.be/php-php_value-vs-php_admin_value-and-the-use-of-php_flag-explained/)
417- [Server-side TLS (Apache)](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache) (Mozilla)
418- [Nginx Beginner's guide](http://nginx.org/en/docs/beginners_guide.html)
419- [Nginx ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)
420- [Nginx Pitfalls](http://wiki.nginx.org/Pitfalls)
421- [Nginx PHP configuration examples](http://kbeezie.com/nginx-configuration-examples/) (Karl Blessing)
422- [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla)
423- [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php)
424- [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority)
425
426#### PHP
427
428- [Travis configuration](https://github.com/shaarli/Shaarli/blob/master/.travis.yml)
429- [PHP: Supported versions](http://php.net/supported-versions.php)
430- [PHP: Unsupported versions](http://php.net/eol.php) _(EOL - End Of Life)_
431- [PHP 7 Changelog](http://php.net/ChangeLog-7.php)
432- [PHP 5 Changelog](http://php.net/ChangeLog-5.php)
433- [PHP: Bugs](https://bugs.php.net/)
diff --git a/doc/md/Server-requirements.md b/doc/md/Server-requirements.md
deleted file mode 100644
index 2dc442df..00000000
--- a/doc/md/Server-requirements.md
+++ /dev/null
@@ -1,42 +0,0 @@
1## PHP
2
3### Release information
4- [PHP: Supported versions](http://php.net/supported-versions.php)
5- [PHP: Unsupported versions](http://php.net/eol.php) _(EOL - End Of Life)_
6- [PHP 7 Changelog](http://php.net/ChangeLog-7.php)
7- [PHP 5 Changelog](http://php.net/ChangeLog-5.php)
8- [PHP: Bugs](https://bugs.php.net/)
9
10### Supported versions
11Version | Status | Shaarli compatibility
12:---:|:---:|:---:
137.1 | Supported (v0.9.x) | Yes
147.0 | Supported | Yes
155.6 | Supported | Yes
165.5 | EOL: 2016-07-10 | Yes
175.4 | EOL: 2015-09-14 | Yes (up to Shaarli 0.8.x)
185.3 | EOL: 2014-08-14 | Yes (up to Shaarli 0.8.x)
19
20See also:
21
22- [Travis configuration](https://github.com/shaarli/Shaarli/blob/master/.travis.yml)
23
24### Dependency management
25Starting with Shaarli `v0.8.x`, [Composer](https://getcomposer.org/) is used to resolve,
26download and install third-party PHP dependencies.
27
28Library | Required? | Usage
29---|:---:|---
30[`shaarli/netscape-bookmark-parser`](https://packagist.org/packages/shaarli/netscape-bookmark-parser) | All | Import bookmarks from Netscape files
31[`erusev/parsedown`](https://packagist.org/packages/erusev/parsedown) | All | Parse MarkDown syntax for the MarkDown plugin
32[`slim/slim`](https://packagist.org/packages/slim/slim) | All | Handle routes and middleware for the REST API
33
34### Extensions
35Extension | Required? | Usage
36---|:---:|---
37[`openssl`](http://php.net/manual/en/book.openssl.php) | All | OpenSSL, HTTPS
38[`php-mbstring`](http://php.net/manual/en/book.mbstring.php) | CentOS, Fedora, RHEL, Windows, some hosting providers | multibyte (Unicode) string support
39[`php-gd`](http://php.net/manual/en/book.image.php) | optional | thumbnail resizing
40[`php-intl`](http://php.net/manual/en/book.intl.php) | optional | localized text sorting (e.g. `e->è->f`)
41[`php-curl`](http://php.net/manual/en/book.curl.php) | optional | using cURL for fetching webpages and thumbnails in a more robust way
42[`php-gettext`](http://php.net/manual/en/book.gettext.php) | optional | Use the translation system in gettext mode (faster)
diff --git a/doc/md/index.md b/doc/md/index.md
index 224070cb..21a63d3c 100644
--- a/doc/md/index.md
+++ b/doc/md/index.md
@@ -1,19 +1,27 @@
1# [Shaarli](https://github.com/shaarli/Shaarli/) documentation 1# [Shaarli](https://github.com/shaarli/Shaarli/) documentation
2 2
3Here you can find some info on how to use, configure, tweak and solve problems with your Shaarli. 3The personal, minimalist, super-fast, database free, bookmarking service.
4
5Do you want to share the links you discover?
6Shaarli is a minimalist link sharing service that you can install on your own server.
7It is designed to be personal (single-user), fast and handy.
8
9<!--- TODO screenshots --->
4 10
5For general info, read the [README](https://github.com/shaarli/Shaarli/blob/master/README.md). 11Here you can find some info on how to use, configure, tweak and solve problems with your Shaarli.
12For general information, read the [README](https://github.com/shaarli/Shaarli/blob/master/README.md).
6 13
7If you have any questions or ideas, please join the [chat](https://gitter.im/shaarli/Shaarli) (also reachable via [IRC](https://irc.gitter.im/)), post them in our [general discussion](https://github.com/shaarli/Shaarli/issues/308) or read the current [issues](https://github.com/shaarli/Shaarli/issues). 14If you have any questions or ideas, please join the [chat](https://gitter.im/shaarli/Shaarli) (also reachable via [IRC](https://irc.gitter.im/)), post them in our [general discussion](https://github.com/shaarli/Shaarli/issues/308) or read the current [issues](https://github.com/shaarli/Shaarli/issues).
15
8If you've found a bug, please create a [new issue](https://github.com/shaarli/Shaarli/issues/new). 16If you've found a bug, please create a [new issue](https://github.com/shaarli/Shaarli/issues/new).
9 17
10If you would like a feature added to Shaarli, check the issues labeled [`feature`](https://github.com/shaarli/Shaarli/labels/feature), [`enhancement`](https://github.com/shaarli/Shaarli/labels/enhancement), and [`plugin`](https://github.com/shaarli/Shaarli/labels/plugin). 18If you would like a feature added to Shaarli, check the issues labeled [`feature`](https://github.com/shaarli/Shaarli/labels/feature), [`enhancement`](https://github.com/shaarli/Shaarli/labels/enhancement), and [`plugin`](https://github.com/shaarli/Shaarli/labels/plugin).
11 19
12_Note: This documentation is available online at https://shaarli.readthedocs.io/, and locally in the `doc/html/` directory of your Shaarli installation._ 20* [GitHub project page](https://github.com/shaarli/Shaarli)
21* [Online documentation](https://shaarli.readthedocs.io/) (this page)
22* [Latest Shaarli releases](https://github.com/shaarli/Shaarli/releases)
23* [Changelog](https://github.com/shaarli/Shaarli/blob/master/CHANGELOG.md)
13 24
14[![Join the chat at https://gitter.im/shaarli/Shaarli](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/shaarli/Shaarli)
15[![Bountysource](https://www.bountysource.com/badge/team?team_id=19583&style=bounties_received)](https://www.bountysource.com/teams/shaarli/issues)
16[![Docker repository](https://img.shields.io/docker/pulls/shaarli/shaarli.svg)](https://hub.docker.com/r/shaarli/shaarli/)
17 25
18### Demo 26### Demo
19 27
@@ -22,6 +30,9 @@ It runs the latest development version of Shaarli and is updated/reset daily.
22 30
23Login: `demo`; Password: `demo` 31Login: `demo`; Password: `demo`
24 32
33<!---- TODO review everything below this point --->
34
35
25## Features 36## Features
26 37
27Shaarli can be used: 38Shaarli can be used:
@@ -42,26 +53,31 @@ Shaarli can be used:
42- to feed other social networks, blogs... using RSS feeds and external services (dlvr.it, ifttt.com ...). 53- to feed other social networks, blogs... using RSS feeds and external services (dlvr.it, ifttt.com ...).
43 54
44### Interface 55### Interface
56
45- minimalist design (simple is beautiful) 57- minimalist design (simple is beautiful)
46- FAST 58- FAST
47- ATOM and RSS feeds 59- ATOM and RSS feeds
48- views: 60- views:
49 - paginated link list 61 - paginated link list (with image and video thumbnails)
50 - tag cloud 62 - tag cloud
51 - picture wall: image and video thumbnails 63 - picture wall: image and video thumbnails (with lazy loading)
52 - daily: newspaper-like daily digest 64 - daily: newspaper-like daily digest
53 - daily RSS feed 65 - daily RSS feed
54- permalinks for easy reference 66- permalinks for easy reference
55- links can be public or private 67- links can be public or private
68- thumbnail generation for images and video services
69- URL cleanup: automatic removal of `?utm_source=...`, `fb=...`
56- extensible through [plugins](https://shaarli.readthedocs.io/en/master/Plugins/#plugin-usage) 70- extensible through [plugins](https://shaarli.readthedocs.io/en/master/Plugins/#plugin-usage)
57 71
58### Tag, view and search your links! 72### Tag, view and search your links
73
59- add a custom title and description to archived links 74- add a custom title and description to archived links
60- add tags to classify and search links 75- add tags to classify and search links
61 - features tag autocompletion, renaming, merging and deletion 76 - features tag autocompletion, renaming, merging and deletion
62- full-text and tag search 77- full-text and tag search
63 78
64### Easy setup 79### Easy setup
80
65- dead-simple installation: drop the files, open the page 81- dead-simple installation: drop the files, open the page
66- links are stored in a file 82- links are stored in a file
67 - compact storage 83 - compact storage
@@ -70,23 +86,19 @@ Shaarli can be used:
70- import and export links as Netscape bookmarks 86- import and export links as Netscape bookmarks
71 87
72### Accessibility 88### Accessibility
73- Firefox bookmarlet to share links in one click 89
90- bookmarlet to share links in one click
74- support for mobile browsers 91- support for mobile browsers
75- works with Javascript disabled 92- degrades gracefully with Javascript disabled
76- easy page customization through HTML/CSS/RainTPL 93- easy page customization through HTML/CSS/RainTPL
77 94
78### Security 95### Security
79- bruteforce-proof login form 96
80- protected against [XSRF](http://en.wikipedia.org/wiki/Cross-site_request_forgery)
81and session cookie hijacking
82
83### Goodies
84- thumbnail generation for images and video services:
85dailymotion, flickr, imageshack, imgur, vimeo, xkcd, youtube...
86 - lazy-loading with [bLazy](http://dinbror.dk/blazy/)
87- [PubSubHubbub](https://code.google.com/p/pubsubhubbub/) protocol support
88- URL cleanup: automatic removal of `?utm_source=...`, `fb=...`
89- discreet pop-up notification when a new release is available 97- discreet pop-up notification when a new release is available
98- bruteforce protection on the login form
99- protected against [XSRF](http://en.wikipedia.org/wiki/Cross-site_request_forgery) and session cookie hijacking
100
101<!---- TODO Limitations --->
90 102
91### REST API 103### REST API
92 104
@@ -95,28 +107,30 @@ Easily extensible by any client using the REST API exposed by Shaarli.
95See the [API documentation](http://shaarli.github.io/api-documentation/). 107See the [API documentation](http://shaarli.github.io/api-documentation/).
96 108
97## About 109## About
110
98### Shaarli community fork 111### Shaarli community fork
112
99This friendly fork is maintained by the Shaarli community at https://github.com/shaarli/Shaarli 113This friendly fork is maintained by the Shaarli community at https://github.com/shaarli/Shaarli
100 114
101This is a community fork of the original [Shaarli](https://github.com/sebsauvage/Shaarli/) project by [Sébastien Sauvage](http://sebsauvage.net/). 115This is a community fork of the original [Shaarli](https://github.com/sebsauvage/Shaarli/) project by [Sébastien Sauvage](http://sebsauvage.net/).
102 116
103The original project is currently unmaintained, and the developer [has informed us](https://github.com/sebsauvage/Shaarli/issues/191) 117The original project is currently unmaintained, and the developer [has informed us](https://github.com/sebsauvage/Shaarli/issues/191) that he would have no time to work on Shaarli in the near future.
104that he would have no time to work on Shaarli in the near future. 118
105The Shaarli community has carried on the work to provide 119The Shaarli community has carried on the work to provide [many patches](https://github.com/shaarli/Shaarli/compare/sebsauvage:master...master) for [bug fixes and enhancements](https://github.com/shaarli/Shaarli/issues?q=is%3Aclosed+) in this repository, and will keep maintaining the project for the foreseeable future, while keeping Shaarli simple and efficient.
106[many patches](https://github.com/shaarli/Shaarli/compare/sebsauvage:master...master) 120
107for [bug fixes and enhancements](https://github.com/shaarli/Shaarli/issues?q=is%3Aclosed+)
108in this repository, and will keep maintaining the project for the foreseeable future, while keeping Shaarli simple and efficient.
109 121
110### Contributing 122### Contributing
123
111If you'd like to help, please: 124If you'd like to help, please:
112- have a look at the open [issues](https://github.com/shaarli/Shaarli/issues) 125- have a look at the open [issues](https://github.com/shaarli/Shaarli/issues)
113and [pull requests](https://github.com/shaarli/Shaarli/pulls) 126and [pull requests](https://github.com/shaarli/Shaarli/pulls)
114- feel free to report bugs (feedback is much appreciated) 127- feel free to report bugs (feedback is much appreciated)
115- suggest new features and improvements to both code and [documentation](https://github.com/shaarli/Shaarli/wiki) 128- suggest new features and improvements to both code and [documentation](https://github.com/shaarli/Shaarli/tree/master/doc/md/)
116- propose solutions to existing problems 129- propose solutions to existing problems
117- submit pull requests :-) 130- submit pull requests :-)
118 131
119 132
120### License 133### License
121Shaarli is [Free Software](http://en.wikipedia.org/wiki/Free_software). See [COPYING](COPYING) for a detail of the contributors and licenses for each individual component. 134
135Shaarli is [Free Software](http://en.wikipedia.org/wiki/Free_software). See [COPYING](https://github.com/shaarli/Shaarli/blob/master/COPYING) for a detail of the contributors and licenses for each individual component. A list of contributors is available [here](https://github.com/shaarli/Shaarli/blob/master/AUTHORS).
122 136