aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/md')
-rw-r--r--doc/md/3rd-party-libraries.md16
-rw-r--r--doc/md/Bookmarklet.md29
-rw-r--r--doc/md/Community-&-Related-software.md9
-rw-r--r--doc/md/Continuous-integration-tools.md7
-rw-r--r--doc/md/Development-guidelines.md9
-rw-r--r--doc/md/Directory-structure.md44
-rw-r--r--doc/md/Download-and-Installation.md20
-rw-r--r--doc/md/FAQ.md4
-rw-r--r--doc/md/Firefox-share.md20
-rw-r--r--doc/md/Link-structure.md18
-rw-r--r--doc/md/Plugins.md4
-rw-r--r--doc/md/REST-API.md24
-rw-r--r--doc/md/Server-configuration.md218
-rw-r--r--doc/md/Server-requirements.md42
-rw-r--r--doc/md/Sharing-content.md71
-rw-r--r--doc/md/Translations.md12
-rw-r--r--doc/md/Troubleshooting.md18
-rw-r--r--doc/md/Unit-tests-Docker.md6
-rw-r--r--doc/md/Upgrade-and-migration.md31
-rw-r--r--doc/md/docker/reverse-proxy-configuration.md7
-rw-r--r--doc/md/docker/shaarli-images.md49
-rw-r--r--doc/md/guides/backup-restore-import-export.md (renamed from doc/md/Backup,-restore,-import-and-export.md)0
-rw-r--r--doc/md/guides/images/01-create-droplet-distro.jpgbin0 -> 20909 bytes
-rw-r--r--doc/md/guides/images/02-create-droplet-region.jpgbin0 -> 21603 bytes
-rw-r--r--doc/md/guides/images/03-create-droplet-size.jpgbin0 -> 20860 bytes
-rw-r--r--doc/md/guides/images/04-finalize.jpgbin0 -> 28233 bytes
-rw-r--r--doc/md/guides/images/05-droplet.jpgbin0 -> 11977 bytes
-rw-r--r--doc/md/guides/images/06-domain.jpgbin0 -> 4499 bytes
-rw-r--r--doc/md/guides/images/07-installation.jpgbin0 -> 42832 bytes
-rw-r--r--doc/md/guides/install-shaarli-with-debian9-and-docker.md257
-rw-r--r--doc/md/guides/various-hacks.md (renamed from doc/md/Various-hacks.md)0
-rw-r--r--doc/md/images/doc-logo.pngbin19543 -> 19520 bytes
-rw-r--r--doc/md/images/edit_icon.pngbin0 -> 1548 bytes
-rw-r--r--doc/md/images/firefoxshare.pngbin757 -> 715 bytes
-rw-r--r--doc/md/images/icon.pngbin0 -> 1266 bytes
-rw-r--r--doc/md/images/install-shaarli.pngbin44376 -> 33827 bytes
-rw-r--r--doc/md/images/logo.pngbin0 -> 5456 bytes
-rw-r--r--doc/md/images/rss-filter-1.pngbin18682 -> 18534 bytes
-rw-r--r--doc/md/images/rss-filter-2.pngbin15604 -> 15440 bytes
-rw-r--r--doc/md/index.md166
40 files changed, 740 insertions, 341 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/Bookmarklet.md b/doc/md/Bookmarklet.md
deleted file mode 100644
index c899e3cf..00000000
--- a/doc/md/Bookmarklet.md
+++ /dev/null
@@ -1,29 +0,0 @@
1## Add the sharing button (_bookmarklet_) to your browser
2
3- Open your Shaarli and `Login`
4- Click the `Tools` button in the top bar
5- Drag the **`✚Shaare link` button**, and drop it to your browser's bookmarks bar.
6
7_This bookmarklet button is compatible with Firefox, Opera, Chrome and Safari. Under Opera, you can't drag'n drop the button: You have to right-click on it and add a bookmark to your personal toolbar._
8
9![](images/bookmarklet.png)
10
11## Share links using the _bookmarklet_
12
13- When you are visiting a webpage you would like to share with Shaarli, click the _bookmarklet_ you just added.
14- A window opens.
15 - You can freely edit title, description, tags... to find it later using the text search or tag filtering.
16 - You will be able to edit this link later using the ![](https://raw.githubusercontent.com/shaarli/Shaarli/master/images/edit_icon.png) edit button.
17 - You can also check the “Private” box so that the link is saved but only visible to you.
18- Click `Save`.**Voilà! Your link is now shared.**
19
20## Troubleshooting: The bookmarklet doesn't work with a few websites (e.g. Github.com)
21
22Websites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. Unfortunatly, there is nothing Shaarli can do about it.
23
24See [#196](https://github.com/shaarli/Shaarli/issues/196).
25
26There is an open bug for both Firefox and Chromium:
27
28- https://bugzilla.mozilla.org/show_bug.cgi?id=866522
29- https://code.google.com/p/chromium/issues/detail?id=233903
diff --git a/doc/md/Community-&-Related-software.md b/doc/md/Community-&-Related-software.md
index 207153b6..67fdd70f 100644
--- a/doc/md/Community-&-Related-software.md
+++ b/doc/md/Community-&-Related-software.md
@@ -32,15 +32,18 @@ See [Theming](Theming) for a list of community-contributed themes, and an instal
32- [tt-rss-shaarli](https://github.com/jcsaaddupuy/tt-rss-shaarli) - [Tiny-Tiny RSS](http://tt-rss.org/) plugin that adds support for sharing articles with Shaarli 32- [tt-rss-shaarli](https://github.com/jcsaaddupuy/tt-rss-shaarli) - [Tiny-Tiny RSS](http://tt-rss.org/) plugin that adds support for sharing articles with Shaarli
33- [octopress-shaarli](https://github.com/ahmet2mir/octopress-shaarli) - Octopress plugin to retrieve Shaarli links on the sidebar 33- [octopress-shaarli](https://github.com/ahmet2mir/octopress-shaarli) - Octopress plugin to retrieve Shaarli links on the sidebar
34- [Scuttle to Shaarli](https://github.com/q2apro/scuttle-to-shaarli) - Import bookmarks from Scuttle 34- [Scuttle to Shaarli](https://github.com/q2apro/scuttle-to-shaarli) - Import bookmarks from Scuttle
35 35- [Shaarli app for Cloudron](https://git.cloudron.io/cloudron/shaarli-app) - Effortlessly run Shaarli with the help of [Cloudron](https://cloudron.io/) [![Install](https://cloudron.io/img/button.svg)](https://cloudron.io/button.html?app=com.github.shaarli)
36- [Shaarli_ynh](https://github.com/YunoHost-Apps/shaarli_ynh) - Shaarli is available as a [Yunohost](https://yunohost.org) app [![Install Shaarli with YunoHost](https://install-app.yunohost.org/install-with-yunohost.png)](https://install-app.yunohost.org/?app=shaarli)
36 37
37### Mobile Apps 38### Mobile Apps
38- [ShaarliOS](https://github.com/mro/ShaarliOS) - Apple iOS share extension. 39- [ShaarliOS](https://github.com/mro/ShaarliOS) - Apple iOS share extension.
39- [Shaarli for Android](http://sebsauvage.net/links/?ZAyDzg) - Android application that adds Shaarli as a sharing provider 40- [Shaarli for Android](http://sebsauvage.net/links/?ZAyDzg) - Android application that adds Shaarli as a sharing provider
40- [Shaarlier for Android](https://github.com/dimtion/Shaarlier) - Android application to simply add links directly into your Shaarli 41- [Shaarlier for Android](https://github.com/dimtion/Shaarlier) - Android application to simply add links directly into your Shaarli
42- [Stakali for Android](https://stakali.toneiv.eu) - Stakali is a personal bookmark manager which synchronizes with Shaarli
41 43
42### Browser addons 44### Browser addons
43 * [Shaarli Web Extension](https://github.com/ikipatang/shaarli-web-extension) - toolbar button to share your current tab with Shaarli. 45- [Shaarli Firefox Extension](https://github.com/ikipatang/shaarli-web-extension) - toolbar button to share your current tab with Shaarli.
46- [Shaarli Chrome Extension](https://github.com/octplane/Shiny-Shaarli) - toolbar button to share your current tab with Shaarli.
44 47
45### Server apps 48### Server apps
46- [shaarchiver](https://github.com/nodiscc/shaarchiver) - Archive your Shaarli bookmarks and their content 49- [shaarchiver](https://github.com/nodiscc/shaarchiver) - Archive your Shaarli bookmarks and their content
@@ -48,7 +51,7 @@ See [Theming](Theming) for a list of community-contributed themes, and an instal
48- [Shaarlo](https://github.com/DMeloni/shaarlo) - An aggregator for shaarlis with many features (a very popular running instance among French shaarliers: [shaarli.fr](http://shaarli.fr/)) 51- [Shaarlo](https://github.com/DMeloni/shaarlo) - An aggregator for shaarlis with many features (a very popular running instance among French shaarliers: [shaarli.fr](http://shaarli.fr/))
49- [Shaarlimages](https://github.com/BoboTiG/shaarlimages) - An image-oriented aggregator for Shaarlis 52- [Shaarlimages](https://github.com/BoboTiG/shaarlimages) - An image-oriented aggregator for Shaarlis
50- [mknexen/shaarli-api](https://github.com/mknexen/shaarli-api) - A REST API for Shaarli 53- [mknexen/shaarli-api](https://github.com/mknexen/shaarli-api) - A REST API for Shaarli
51- [Self dead link](https://github.com/qwertygc/shaarli-dev-code/blob/master/self-dead-link.php) - Detect dead links on shaarli. This version use the database of shaarli. [Another version](https://github.com/qwertygc/shaarli-dev-code/blob/master/dead-link.php), can be used for other shaarli instances (but is more resource consuming). 54- [Self dead link](https://framagit.org/qwertygc/shaarli-dev-code/blob/master/self-dead-link.php) - Detect dead links on shaarli. This version use the database of shaarli. [Another version](https://framagit.org/qwertygc/shaarli-dev-code/blob/master/dead-link.php), can be used for other shaarli instances (but is more resource consuming).
52- [Bookmark Archiver](https://github.com/pirate/bookmark-archiver) - Save an archived copy of all websites starred using browser bookmarks/Shaarli/Delicious/Instapaper/Unmark.it/Pocket/Pinboard. Outputs browseable html. 55- [Bookmark Archiver](https://github.com/pirate/bookmark-archiver) - Save an archived copy of all websites starred using browser bookmarks/Shaarli/Delicious/Instapaper/Unmark.it/Pocket/Pinboard. Outputs browseable html.
53 56
54## Alternatives to Shaarli 57## Alternatives to Shaarli
diff --git a/doc/md/Continuous-integration-tools.md b/doc/md/Continuous-integration-tools.md
index 4bd7a0ba..4ca6bdc7 100644
--- a/doc/md/Continuous-integration-tools.md
+++ b/doc/md/Continuous-integration-tools.md
@@ -2,8 +2,8 @@
2A [`Makefile`](https://github.com/shaarli/Shaarli/blob/master/Makefile) is available to perform project-related operations: 2A [`Makefile`](https://github.com/shaarli/Shaarli/blob/master/Makefile) is available to perform project-related operations:
3 3
4- Documentation - generate a local HTML copy of the GitHub wiki 4- Documentation - generate a local HTML copy of the GitHub wiki
5- [Static analysis](Static analysis) - check that the code is compliant to PHP conventions 5- [Static analysis](Static-analysis) - check that the code is compliant to PHP conventions
6- [Unit tests](Unit tests) - ensure there are no regressions introduced by new commits 6- [Unit tests](Unit-tests) - ensure there are no regressions introduced by new commits
7 7
8## Automatic builds 8## Automatic builds
9[Travis CI](http://docs.travis-ci.com/) is a Continuous Integration build server, that runs a build: 9[Travis CI](http://docs.travis-ci.com/) is a Continuous Integration build server, that runs a build:
@@ -17,7 +17,8 @@ Each build job:
17 17
18- updates Composer 18- updates Composer
19- installs 3rd-party test dependencies with Composer 19- installs 3rd-party test dependencies with Composer
20- runs [Unit tests](Unit tests) 20- runs [Unit tests](Unit-tests)
21- runs ESLint check
21 22
22After all jobs have finished, Travis returns the results to GitHub: 23After all jobs have finished, Travis returns the results to GitHub:
23 24
diff --git a/doc/md/Development-guidelines.md b/doc/md/Development-guidelines.md
index 532ec2e4..46b7c6f8 100644
--- a/doc/md/Development-guidelines.md
+++ b/doc/md/Development-guidelines.md
@@ -3,8 +3,11 @@
3Please have a look at the following pages: 3Please have a look at the following pages:
4 4
5- [Contributing to Shaarli](https://github.com/shaarli/Shaarli/tree/master/CONTRIBUTING.md) 5- [Contributing to Shaarli](https://github.com/shaarli/Shaarli/tree/master/CONTRIBUTING.md)
6- [Static analysis](Static analysis) - patches should try to stick to the [PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), especially: 6- [Static analysis](Static-analysis) - patches should try to stick to the
7[PHP Standard Recommendations](http://www.php-fig.org/psr/) (PSR), especially:
7 - [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard 8 - [PSR-1](http://www.php-fig.org/psr/psr-1/) - Basic Coding Standard
8 - [PSR-2](http://www.php-fig.org/psr/psr-2/) - Coding Style Guide 9 - [PSR-2](http://www.php-fig.org/psr/psr-2/) - Coding Style Guide
9- [Unit tests](Unit tests) 10- [Unit tests](Unit-tests)
10- [GnuPG signature](GnuPG signature) for tags/releases 11- Javascript linting - Shaarli uses [Airbnb JavaScript Style Guide](https://github.com/airbnb/javascript).
12Run `make eslint` to check JS style.
13- [GnuPG signature](GnuPG-signature) for tags/releases
diff --git a/doc/md/Directory-structure.md b/doc/md/Directory-structure.md
index eb50965b..c0b49393 100644
--- a/doc/md/Directory-structure.md
+++ b/doc/md/Directory-structure.md
@@ -1,4 +1,4 @@
1TODO: This page is out of date 1## Directory structure
2 2
3Here is the directory structure of Shaarli and the purpose of the different files: 3Here is the directory structure of Shaarli and the purpose of the different files:
4 4
@@ -6,29 +6,49 @@ Here is the directory structure of Shaarli and the purpose of the different file
6 index.php # Main program 6 index.php # Main program
7 application/ # Shaarli classes 7 application/ # Shaarli classes
8 ├── LinkDB.php 8 ├── LinkDB.php
9
10 ...
11
9 └── Utils.php 12 └── Utils.php
10 tests/ # Shaarli unitary & functional tests 13 tests/ # Shaarli unitary & functional tests
11 ├── LinkDBTest.php 14 ├── LinkDBTest.php
12 ├── utils # utilities to ease testing 15
16 ...
17
18 ├── utils # utilities to ease testing
13 │ └── ReferenceLinkDB.php 19 │ └── ReferenceLinkDB.php
14 └── UtilsTest.php 20 └── UtilsTest.php
21 assets/
22 ├── common/ # Assets shared by multiple themes
23 ├── ...
24 ├── default/ # Assets for the default template, before compilation
25 ├── fonts/ # Font files
26 ├── img/ # Images used by the default theme
27 ├── js/ # JavaScript files in ES6 syntax
28 ├── scss/ # SASS files
29 └── vintage/ # Assets for the vintage template, before compilation
30 └── ...
15 COPYING # Shaarli license 31 COPYING # Shaarli license
16 inc/ # static assets and 3rd party libraries 32 inc/ # static assets and 3rd party libraries
17 ├── awesomplete.* # tags autocompletion library 33 └── rain.tpl.class.php # RainTPL templating library
18 ├── blazy.* # picture wall lazy image loading library
19 ├── shaarli.css, reset.css # Shaarli stylesheet.
20 ├── qr.* # qr code generation library
21 └──rain.tpl.class.php # RainTPL templating library
22 tpl/ # RainTPL templates for Shaarli. They are used to build the pages.
23 images/ # Images and icons used in Shaarli 34 images/ # Images and icons used in Shaarli
24 data/ # data storage: bookmark database, configuration, logs, banlist… 35 data/ # data storage: bookmark database, configuration, logs, banlist...
25 ├── config.php # Shaarli configuration (login, password, timezone, title…) 36 ├── config.json.php # Shaarli configuration (login, password, timezone, title...)
26 ├── datastore.php # Your link database (compressed). 37 ├── datastore.php # Your link database (compressed).
27 ├── ipban.php # IP address ban system data 38 ├── ipban.php # IP address ban system data
28 ├── lastupdatecheck.txt # Update check timestamp file 39 ├── lastupdatecheck.txt # Update check timestamp file
29 └──log.txt # login/IPban log. 40 └── log.txt # login/IPban log.
41 tpl/ # RainTPL templates for Shaarli. They are used to build the pages.
42 ├── default/ # Default Shaarli theme
43 ├── fonts/ # Font files
44 ├── img/ # Images
45 ├── js/ # JavaScript files compiled by Babel and compatible with all browsers
46 ├── css/ # CSS files compiled with SASS
47 └── vintage/ # Legacy Shaarli theme
48 └── ...
30 cache/ # thumbnails cache 49 cache/ # thumbnails cache
31 # This directory is automatically created. You can erase it anytime you want. 50 # This directory is automatically created. You can erase it anytime you want.
32 tmp/ # Temporary directory for compiled RainTPL templates. 51 tmp/ # Temporary directory for compiled RainTPL templates.
33 # This directory is automatically created. You can erase it anytime you want. 52 # This directory is automatically created. You can erase it anytime you want.
53 vendor/ # Third-party dependencies. This directory is created by Composer
34``` 54```
diff --git a/doc/md/Download-and-Installation.md b/doc/md/Download-and-Installation.md
index 0fdbd27d..14649e06 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,13 +22,13 @@ 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.3` 27The current latest released version is `v0.9.7`
29 28
30```bash 29```bash
31$ wget https://github.com/shaarli/Shaarli/releases/download/v0.9.3/shaarli-v0.9.3-full.zip 30$ wget https://github.com/shaarli/Shaarli/releases/download/v0.9.7/shaarli-v0.9.7-full.zip
32$ unzip shaarli-v0.9.3-full.zip 31$ unzip shaarli-v0.9.7-full.zip
33$ mv Shaarli /path/to/shaarli/ 32$ mv Shaarli /path/to/shaarli/
34``` 33```
35 34
@@ -37,13 +36,15 @@ $ 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).
40 * Install [yarn](https://yarnpkg.com/lang/en/docs/install/) to build the frontend dependencies.
41 * 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.
42 42
43``` 43```
44$ mkdir -p /path/to/shaarli && cd /path/to/shaarli/ 44$ mkdir -p /path/to/shaarli && cd /path/to/shaarli/
45$ git clone -b latest https://github.com/shaarli/Shaarli.git . 45$ git clone -b latest https://github.com/shaarli/Shaarli.git .
46$ composer install --no-dev --prefer-dist 46$ composer install --no-dev --prefer-dist
47$ make build_frontend
47$ make translate 48$ make translate
48$ make htmldoc 49$ make htmldoc
49``` 50```
@@ -91,7 +92,9 @@ $ composer install --no-dev --prefer-dist
91 92
92_Use at your own risk!_ 93_Use at your own risk!_
93 94
94Install [Composer](Unit-tests.md#install_composer) to manage Shaarli dependencies. 95Install [Composer](Unit-tests.md#install_composer) to manage Shaarli PHP dependencies,
96and [yarn](https://yarnpkg.com/lang/en/docs/install/)
97for front-end dependencies.
95 98
96To get the latest changes from the `master` branch: 99To get the latest changes from the `master` branch:
97 100
@@ -101,6 +104,7 @@ $ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/
101# install/update third-party dependencies 104# install/update third-party dependencies
102$ cd /path/to/shaarli 105$ cd /path/to/shaarli
103$ composer install --no-dev --prefer-dist 106$ composer install --no-dev --prefer-dist
107$ make build_frontend
104$ make translate 108$ make translate
105$ make htmldoc 109$ make htmldoc
106``` 110```
diff --git a/doc/md/FAQ.md b/doc/md/FAQ.md
index 77faf117..a2ec7d57 100644
--- a/doc/md/FAQ.md
+++ b/doc/md/FAQ.md
@@ -22,7 +22,9 @@ With Shaarli:
22Shaarli stands for _shaaring_ your _links_. 22Shaarli stands for _shaaring_ your _links_.
23 23
24### My Shaarli is broken! 24### My Shaarli is broken!
25First of all, ensure that both the [web server](Server-configuration) and [Shaarli](Shaarli-configuration) are correctly configured, and that your installation is [supported](Server-requirements). 25First of all, ensure that both the [web server](Server-configuration) and
26[Shaarli](Shaarli-configuration) are correctly configured, and that your
27installation is [supported](Server-configuration).
26 28
27If everything looks right but the issue(s) remain(s), please: 29If everything looks right but the issue(s) remain(s), please:
28 30
diff --git a/doc/md/Firefox-share.md b/doc/md/Firefox-share.md
deleted file mode 100644
index 9a46b185..00000000
--- a/doc/md/Firefox-share.md
+++ /dev/null
@@ -1,20 +0,0 @@
1| Note | Firefox Share is no longer available for Firefox 57 and later versions. |
2|---------|---------|
3
4### Add Shaarli as a sharing service to Firefox
5
6- Open your Shaarli and `Login`
7- Click the `Tools` button in the top bar
8- Click the `✚Add to Firefox social` button and accept the activation.
9
10
11### Sharing links using Firefox share
12
13- Add the sharing service as described above
14- When you are visiting a webpage you would like to share with Shaarli,
15 click the Firefox _Share_ button [images/firefoxshare.png](images/firefoxshare.png)
16- You can edit your link before and after saving, just like the bookmarklet above.
17
18_Your Shaarli instance must be hosted on an HTTPS (SSL/TLS secure connection)
19enabled server for Firefox Share to work. Firefox Share will not work over
20plain HTTP connections._
diff --git a/doc/md/Link-structure.md b/doc/md/Link-structure.md
new file mode 100644
index 00000000..0a2d0f88
--- /dev/null
+++ b/doc/md/Link-structure.md
@@ -0,0 +1,18 @@
1## Link structure
2
3Every link available through the `LinkDB` object is represented as an array
4containing the following fields:
5
6 * `id` (integer): Unique identifier.
7 * `title` (string): Title of the link.
8 * `url` (string): URL of the link. Used for displayable links (without redirector, url encoding, etc.).
9 Can be absolute or relative for Notes.
10 * `real_url` (string): Real destination URL, can be redirected, encoded, etc.
11 * `shorturl` (string): Permalink small hash.
12 * `description` (string): Link text description.
13 * `private` (boolean): whether the link is private or not.
14 * `tags` (string): all link tags separated by a single space
15 * `thumbnail` (string|boolean): relative path of the thumbnail cache file, or false if there isn't any.
16 * `created` (DateTime): link creation date time.
17 * `updated` (DateTime): last modification date time.
18 \ No newline at end of file
diff --git a/doc/md/Plugins.md b/doc/md/Plugins.md
index 463dae17..954442e2 100644
--- a/doc/md/Plugins.md
+++ b/doc/md/Plugins.md
@@ -37,7 +37,7 @@ This is important in case plugins are depending on each other. Read plugins READ
37 37
38## File mode 38## File mode
39 39
40Enabled plugin are stored in your `config.php` parameters file, under the `array`: 40Enabled plugin are stored in your `config.json.php` parameters file, under the `array`:
41 41
42```php 42```php
43$GLOBALS['config']['ENABLED_PLUGINS'] 43$GLOBALS['config']['ENABLED_PLUGINS']
@@ -48,7 +48,7 @@ Example:
48 48
49```php 49```php
50$GLOBALS['config']['ENABLED_PLUGINS'] = array( 50$GLOBALS['config']['ENABLED_PLUGINS'] = array(
51 'qrcode', 51 'qrcode',
52 'archiveorg', 52 'archiveorg',
53 'wallabag', 53 'wallabag',
54 'markdown', 54 'markdown',
diff --git a/doc/md/REST-API.md b/doc/md/REST-API.md
index 68a83c00..11bd1cd2 100644
--- a/doc/md/REST-API.md
+++ b/doc/md/REST-API.md
@@ -3,8 +3,9 @@
3See the [REST API documentation](http://shaarli.github.io/api-documentation/) 3See the [REST API documentation](http://shaarli.github.io/api-documentation/)
4for a list of available endpoints and parameters. 4for a list of available endpoints and parameters.
5 5
6Please ensure that your server meets the [requirements](Server-requirements) 6Please ensure that your server meets the
7and is properly [configured](Server-configuration): 7[requirements](Server-configuration#prerequisites) and is properly
8[configured](Server-configuration):
8 9
9- URL rewriting is enabled (see specific Apache and Nginx sections) 10- URL rewriting is enabled (see specific Apache and Nginx sections)
10- the server's timezone is properly defined 11- the server's timezone is properly defined
@@ -151,3 +152,22 @@ See the reference API client:
151 152
152- [Documentation](http://python-shaarli-client.readthedocs.io/en/latest/) on ReadTheDocs 153- [Documentation](http://python-shaarli-client.readthedocs.io/en/latest/) on ReadTheDocs
153- [python-shaarli-client](https://github.com/shaarli/python-shaarli-client) on Github 154- [python-shaarli-client](https://github.com/shaarli/python-shaarli-client) on Github
155
156## Troubleshooting
157
158### Debug mode
159
160> This should never be used in a production environment.
161
162For security reasons, authentication issues will always return an `HTTP 401` error code without any detail.
163
164It is possible to enable the debug mode in `config.json.php`
165to get the actual error message in the HTTP response body with:
166
167```json
168{
169 "dev": {
170 "debug": true
171 }
172}
173```
diff --git a/doc/md/Server-configuration.md b/doc/md/Server-configuration.md
index 25dd49fe..78083a46 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 | EOL: 2018-12-31 | Yes (up to Shaarli 0.10.x)
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 | required to use thumbnails
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- [nginx](http://nginx.org)
125- [php-fpm](http://php-fpm.org) - PHP FastCGI Process Manager
126 124
127Official documentation: 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.
128 126
129- [Beginner's guide](http://nginx.org/en/docs/beginners_guide.html) 127<!--- TODO refactor everything below this point --->
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,46 @@ http {
404 } 395 }
405} 396}
406``` 397```
398
399## Proxies
400
401If 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:
402
403- `X-Forwarded-Proto`
404- `X-Forwarded-Host`
405- `X-Forwarded-For`
406
407See also [proxy-related](https://github.com/shaarli/Shaarli/issues?utf8=%E2%9C%93&q=label%3Aproxy+) issues.
408
409## Robots and crawlers
410
411Shaarli disallows indexing and crawling of your local documentation pages by search engines, using `<meta name="robots">` HTML tags.
412Your Shaarli instance and other pages you host may still be indexed by various robots on the public Internet.
413You may want to setup a robots.txt file or other crawler control mechanism on your server.
414See [[1]](https://en.wikipedia.org/wiki/Robots_exclusion_standard), [[2]](https://support.google.com/webmasters/answer/6062608?hl=en) and [[3]](https://developers.google.com/search/reference/robots_meta_tag)
415
416## See also
417
418 * [Server security](Server-security.md)
419
420#### Webservers
421
422- [Apache/PHP - error log per VirtualHost](http://stackoverflow.com/q/176) (StackOverflow)
423- [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/)
424- [Server-side TLS (Apache)](https://wiki.mozilla.org/Security/Server_Side_TLS#Apache) (Mozilla)
425- [Nginx Beginner's guide](http://nginx.org/en/docs/beginners_guide.html)
426- [Nginx ngx_http_fastcgi_module](http://nginx.org/en/docs/http/ngx_http_fastcgi_module.html)
427- [Nginx Pitfalls](http://wiki.nginx.org/Pitfalls)
428- [Nginx PHP configuration examples](http://kbeezie.com/nginx-configuration-examples/) (Karl Blessing)
429- [Server-side TLS (Nginx)](https://wiki.mozilla.org/Security/Server_Side_TLS#Nginx) (Mozilla)
430- [How to Create Self-Signed SSL Certificates with OpenSSL](http://www.xenocafe.com/tutorials/linux/centos/openssl/self_signed_certificates/index.php)
431- [How do I create my own Certificate Authority?](https://workaround.org/certificate-authority)
432
433#### PHP
434
435- [Travis configuration](https://github.com/shaarli/Shaarli/blob/master/.travis.yml)
436- [PHP: Supported versions](http://php.net/supported-versions.php)
437- [PHP: Unsupported versions](http://php.net/eol.php) _(EOL - End Of Life)_
438- [PHP 7 Changelog](http://php.net/ChangeLog-7.php)
439- [PHP 5 Changelog](http://php.net/ChangeLog-5.php)
440- [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/Sharing-content.md b/doc/md/Sharing-content.md
new file mode 100644
index 00000000..9a16fc62
--- /dev/null
+++ b/doc/md/Sharing-content.md
@@ -0,0 +1,71 @@
1Content posted to Shaarli is separated in items called _Shaares_. For each Shaare,
2you can customize the following aspects:
3
4 * URL to link to
5 * Title
6 * Free-text description
7 * Tags
8 * Public/private status
9
10--------------------------------------------------------------------------------
11
12## Adding new Shaares
13
14While logged in to your Shaarli, you can add new Shaares in several ways:
15
16 * [+Shaare button](#shaare-button)
17 * [Bookmarklet](#bookmarklet)
18 * Third-party [apps and browser addons](Community-&-Related-software.md#mobile-apps)
19 * [REST API](https://shaarli.github.io/api-documentation/)
20
21### +Shaare button
22
23 * While logged in to your Shaarli, click the **`+Shaare`** button located in the toolbar.
24 * Enter the URL of a link you want to share.
25 * Click `Add link`
26 * The `New Shaare` dialog appears, allowing you to fill in the details of your Shaare.
27 * The Description, Title, and Tags will help you find your Shaare later using tags or full-text search.
28 * You can also check the “Private” box so that the link is saved but only visible to you (the logged-in user).
29 * Click `Save`.
30
31<!-- TODO Add screenshot of add/edit link dialog -->
32
33### Bookmarklet
34
35The _Bookmarklet_ \[[1](https://en.wikipedia.org/wiki/Bookmarklet)\] is a special
36browser bookmark you can use to add new content to your Shaarli. This bookmarklet is
37compatible with Firefox, Opera, Chrome and Safari. To set it up:
38
39 * Access the `Tools` page from the button in the toolbar.
40 * Drag the **`✚Shaare link` button** to your browser's bookmarks bar.
41
42Once this is done, you can shaare any URL you are visiting simply by clicking the
43bookmarklet in your browser! The same `New Shaare` dialog as above is displayed.
44
45| Note | Websites which enforce Content Security Policy (CSP), such as github.com, disallow usage of bookmarklets. Unfortunately, there is nothing Shaarli can do about it. \[[1](https://github.com/shaarli/Shaarli/issues/196)]\ \[[2](https://bugzilla.mozilla.org/show_bug.cgi?id=866522)]\ \[[3](https://code.google.com/p/chromium/issues/detail?id=233903)]\ |
46|---------|---------|
47
48| Note | Under Opera, you can't drag'n drop the button: You have to right-click on it and add a bookmark to your personal toolbar. |
49|---------|---------|
50
51![](images/bookmarklet.png)
52
53
54--------------------------------------------------------------------------------
55
56## Editing Shaares
57
58Any Shaare can edited by clicking its ![](images/edit_icon.png) `Edit` button.
59
60Editing a Shaare will not change it's permalink, each permalink always points to the
61latest revision of a Shaare.
62
63--------------------------------------------------------------------------------
64
65## Using shaarli as a blog, notepad, pastebin...
66
67While adding or editing a link, leave the URL field blank to create a text-only
68("note") post. This allows you to post any kind of text content, such as blog
69articles, private or public notes, snippets... There is no character limit! You can
70access your Shaare from its permalink.
71
diff --git a/doc/md/Translations.md b/doc/md/Translations.md
index 54a36655..c7d33855 100644
--- a/doc/md/Translations.md
+++ b/doc/md/Translations.md
@@ -76,6 +76,18 @@ Then click on the "Update" button, and you can start to translate every availabl
76 76
77Save when you're done, then you can submit a pull request containing the new `shaarli.po`. 77Save when you're done, then you can submit a pull request containing the new `shaarli.po`.
78 78
79### Theme translations
80
81Theme translation extensions are loaded automatically if they're present.
82
83As a theme developer, all you have to do is to add the `.po` and `.mo` compiled file like this:
84
85 tpl/<theme name>/language/<lang>/LC_MESSAGES/<theme name>.po
86 tpl/<theme name>/language/<lang>/LC_MESSAGES/<theme name>.mo
87
88Where `<lang>` is the ISO 3166-1 alpha-2 language code.
89Read the following section "Extend Shaarli's translation" to learn how to generate those files.
90
79### Extend Shaarli's translation 91### Extend Shaarli's translation
80 92
81If you're writing a custom theme, or a non official plugin, you might want to use the translation system, 93If you're writing a custom theme, or a non official plugin, you might want to use the translation system,
diff --git a/doc/md/Troubleshooting.md b/doc/md/Troubleshooting.md
index b2d86d40..570f6956 100644
--- a/doc/md/Troubleshooting.md
+++ b/doc/md/Troubleshooting.md
@@ -63,7 +63,7 @@ Related threads:
63 63
64### I forgot my password! 64### I forgot my password!
65 65
66Delete the file `data/config.php` and display the page again. You will be asked for a new login/password. 66Delete the file `data/config.json.php` and display the page again. You will be asked for a new login/password.
67 67
68### I'm locked out - Login bruteforce protection 68### I'm locked out - Login bruteforce protection
69 69
@@ -97,7 +97,7 @@ php56 1
97 97
98```php 98```php
99//list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive. 99//list($status,$headers,$data) = getHTTP($url,4); // Short timeout to keep the application responsive.
100// FIXME: Decode charset according to charset specified in either 1) HTTP response headers or 2) <head> in html 100// FIXME: Decode charset according to charset specified in either 1) HTTP response headers or 2) <head> in html
101//if (strpos($status,'200 OK')) $title=html_extract_title($data); 101//if (strpos($status,'200 OK')) $title=html_extract_title($data);
102``` 102```
103 103
@@ -106,11 +106,11 @@ php56 1
106 106
107### Dates are not properly formatted 107### Dates are not properly formatted
108 108
109Shaarli tries to sniff the language of the browser (using HTTP_ACCEPT_LANGUAGE headers) and choose a date format accordingly. But Shaarli can only use the date formats (and more generaly speaking, the locales) provided by the webserver. So even if you have a browser in French, you may end up with dates in US format (it's the case on sebsauvage.net :-( ) 109Shaarli tries to sniff the language of the browser (using `HTTP_ACCEPT_LANGUAGE` headers)
110 110and choose a date format accordingly. But Shaarli can only use the date formats
111### Problems on CentOS servers 111(and more generally speaking, the locales) provided by the webserver.
112 112So even if you have a browser in French, you may end up with dates in US format
113On **CentOS**/RedHat derivatives, you may need to install the `php-mbstring` package. 113(it's the case on sebsauvage.net :-( )
114 114
115### My session expires! I can't stay logged in 115### My session expires! I can't stay logged in
116 116
@@ -126,7 +126,3 @@ This can be caused by several things:
126## Sessions do not seem to work correctly on your server 126## Sessions do not seem to work correctly on your server
127 127
128Follow the instructions in the error message. Make sure you are accessing shaarli via a direct IP address or a proper hostname. If you have **no dots** in the hostname (e.g. `localhost` or `http://my-webserver/shaarli/`), some browsers will not store cookies at all (this respects the [HTTP cookie specification](http://curl.haxx.se/rfc/cookie_spec.html)). 128Follow the instructions in the error message. Make sure you are accessing shaarli via a direct IP address or a proper hostname. If you have **no dots** in the hostname (e.g. `localhost` or `http://my-webserver/shaarli/`), some browsers will not store cookies at all (this respects the [HTTP cookie specification](http://curl.haxx.se/rfc/cookie_spec.html)).
129
130### pubsubhubbub support
131
132Download [publisher.php](https://pubsubhubbub.googlecode.com/git/publisher_clients/php/library/publisher.php) at the root of your Shaarli installation and set `$GLOBALS['config']['PUBSUBHUB_URL']` in your `config.php`
diff --git a/doc/md/Unit-tests-Docker.md b/doc/md/Unit-tests-Docker.md
index c2de7cc7..59bd5b45 100644
--- a/doc/md/Unit-tests-Docker.md
+++ b/doc/md/Unit-tests-Docker.md
@@ -8,7 +8,7 @@ Read first:
8 8
9### Docker test images 9### Docker test images
10 10
11Test Dockerfiles are located under `docker/tests/<distribution>/Dockerfile`, 11Test Dockerfiles are located under `tests/docker/<distribution>/Dockerfile`,
12and can be used to build Docker images to run Shaarli test suites under common 12and can be used to build Docker images to run Shaarli test suites under common
13Linux environments. 13Linux environments.
14 14
@@ -27,7 +27,7 @@ What's behind the curtains:
27 - test PHP dependencies (OS packages) 27 - test PHP dependencies (OS packages)
28 - Composer 28 - Composer
29- the local workspace is mapped to the container's `/shaarli/` directory, 29- the local workspace is mapped to the container's `/shaarli/` directory,
30- the files are rsync'd to so tests are run using a standard Linux user account 30- the files are rsync'd so tests are run using a standard Linux user account
31 (running tests as `root` would bypass permission checks and may hide issues) 31 (running tests as `root` would bypass permission checks and may hide issues)
32- the tests are run inside the container. 32- the tests are run inside the container.
33 33
@@ -36,7 +36,7 @@ What's behind the curtains:
36```bash 36```bash
37# build the Debian 9 Docker image 37# build the Debian 9 Docker image
38$ cd /path/to/shaarli 38$ cd /path/to/shaarli
39$ cd docker/test/debian9 39$ cd tests/docker/debian9
40$ docker build -t shaarli-test:debian9 . 40$ docker build -t shaarli-test:debian9 .
41``` 41```
42 42
diff --git a/doc/md/Upgrade-and-migration.md b/doc/md/Upgrade-and-migration.md
index 1dc07339..d5682a34 100644
--- a/doc/md/Upgrade-and-migration.md
+++ b/doc/md/Upgrade-and-migration.md
@@ -2,14 +2,14 @@
2 2
3### Note your current version 3### Note your current version
4 4
5If anything goes wrong, it's important for us to know which version you're upgrading from. 5If anything goes wrong, it's important for us to know which version you're upgrading from.
6The current version is present in the `version.php` file. 6The current version is present in the `shaarli_version.php` file.
7 7
8### Backup your data 8### Backup your data
9 9
10Shaarli stores all user data under the `data` directory: 10Shaarli stores all user data under the `data` directory:
11 11
12- `data/config.php` - main configuration file 12- `data/config.json.php` (or `data/config.php` for older Shaarli versions) - main configuration file
13- `data/datastore.php` - bookmarked links 13- `data/datastore.php` - bookmarked links
14- `data/ipbans.php` - banned IP addresses 14- `data/ipbans.php` - banned IP addresses
15- `data/updates.txt` - contains all automatic update to the configuration and datastore files already run 15- `data/updates.txt` - contains all automatic update to the configuration and datastore files already run
@@ -27,7 +27,7 @@ As all user data is kept under `data`, this is the only directory you need to wo
27 27
28- backup the `data` directory 28- backup the `data` directory
29- install or update Shaarli: 29- install or update Shaarli:
30 - fresh installation - see [Download and installation](Download-and-installation) 30 - fresh installation - see [Download and Installation](Download-and-Installation)
31 - update - see the following sections 31 - update - see the following sections
32- check or restore the `data` directory 32- check or restore the `data` directory
33 33
@@ -35,11 +35,11 @@ As all user data is kept under `data`, this is the only directory you need to wo
35 35
36All tagged revisions can be downloaded as tarballs or ZIP archives from the [releases](https://github.com/shaarli/Shaarli/releases) page. 36All tagged revisions can be downloaded as tarballs or ZIP archives from the [releases](https://github.com/shaarli/Shaarli/releases) page.
37 37
38We recommend that you use the latest release tarball with the `-full` suffix. It contains the dependencies, please read [Download and installation](Download-and-installation) for `git` complete instructions. 38We recommend that you use the latest release tarball with the `-full` suffix. It contains the dependencies, please read [Download and Installation](Download-and-Installation) for `git` complete instructions.
39 39
40Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the `data` directory! 40Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the `data` directory!
41 41
42If you use translations in gettext mode - meaning you manually changed the default mode -, 42If you use translations in gettext mode - meaning you manually changed the default mode -,
43reload your web server. 43reload your web server.
44 44
45After upgrading, access your fresh Shaarli installation from a web browser; the configuration and data store will then be automatically updated, and new settings added to `data/config.json.php` (see [Shaarli configuration](Shaarli configuration) for more details). 45After upgrading, access your fresh Shaarli installation from a web browser; the configuration and data store will then be automatically updated, and new settings added to `data/config.json.php` (see [Shaarli configuration](Shaarli configuration) for more details).
@@ -83,6 +83,13 @@ $ make translate
83 83
84If you use translations in gettext mode, reload your web server. 84If you use translations in gettext mode, reload your web server.
85 85
86Shaarli >= `v0.10.0` manages its front-end dependencies with nodejs. You need to install
87[yarn](https://yarnpkg.com/lang/en/docs/install/):
88
89```bash
90$ make build_frontend
91```
92
86### Migrating and upgrading from Sebsauvage's repository 93### Migrating and upgrading from Sebsauvage's repository
87 94
88If you have installed Shaarli from [Sebsauvage's original Git repository](https://github.com/sebsauvage/Shaarli), you can use [Git remotes](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) to update your working copy. 95If you have installed Shaarli from [Sebsauvage's original Git repository](https://github.com/sebsauvage/Shaarli), you can use [Git remotes](https://git-scm.com/book/en/v2/Git-Basics-Working-with-Remotes) to update your working copy.
@@ -170,6 +177,13 @@ $ make translate
170 177
171If you use translations in gettext mode, reload your web server. 178If you use translations in gettext mode, reload your web server.
172 179
180Shaarli >= `v0.10.0` manages its front-end dependencies with nodejs. You need to install
181[yarn](https://yarnpkg.com/lang/en/docs/install/):
182
183```bash
184$ make build_frontend
185```
186
173Optionally, you can delete information related to the legacy version: 187Optionally, you can delete information related to the legacy version:
174 188
175```bash 189```bash
@@ -192,7 +206,10 @@ Total 3317 (delta 2050), reused 3301 (delta 2034)to
192 206
193#### Step 3: configuration 207#### Step 3: configuration
194 208
195After migrating, access your fresh Shaarli installation from a web browser; the configuration will then be automatically updated, and new settings added to `data/config.php` (see [Shaarli configuration](Shaarli-configuration) for more details). 209After migrating, access your fresh Shaarli installation from a web browser; the
210configuration will then be automatically updated, and new settings added to
211`data/config.json.php` (see [Shaarli configuration](Shaarli-configuration) for more
212details).
196 213
197## Troubleshooting 214## Troubleshooting
198 215
diff --git a/doc/md/docker/reverse-proxy-configuration.md b/doc/md/docker/reverse-proxy-configuration.md
index 6066140e..e53c9422 100644
--- a/doc/md/docker/reverse-proxy-configuration.md
+++ b/doc/md/docker/reverse-proxy-configuration.md
@@ -13,12 +13,14 @@ This guide assumes that:
13 - [mod_proxy](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html) 13 - [mod_proxy](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html)
14 - [Reverse Proxy Request Headers](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#x-headers) 14 - [Reverse Proxy Request Headers](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#x-headers)
15 15
16The following HTTP headers are set by using the `ProxyPass` directive: 16The following HTTP headers are set when the `ProxyPass` directive is set:
17 17
18- `X-Forwarded-For` 18- `X-Forwarded-For`
19- `X-Forwarded-Host` 19- `X-Forwarded-Host`
20- `X-Forwarded-Server` 20- `X-Forwarded-Server`
21 21
22The original `SERVER_NAME` can be sent to the proxied host by setting the [`ProxyPreserveHost`](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#ProxyPreserveHost) directive to `On`.
23
22```apache 24```apache
23<VirtualHost *:80> 25<VirtualHost *:80>
24 ServerName shaarli.domain.tld 26 ServerName shaarli.domain.tld
@@ -37,7 +39,8 @@ The following HTTP headers are set by using the `ProxyPass` directive:
37 CustomLog /var/log/apache2/shaarli-access.log combined 39 CustomLog /var/log/apache2/shaarli-access.log combined
38 40
39 RequestHeader set X-Forwarded-Proto "https" 41 RequestHeader set X-Forwarded-Proto "https"
40 42 ProxyPreserveHost On
43
41 ProxyPass / http://127.0.0.1:10080/ 44 ProxyPass / http://127.0.0.1:10080/
42 ProxyPassReverse / http://127.0.0.1:10080/ 45 ProxyPassReverse / http://127.0.0.1:10080/
43</VirtualHost> 46</VirtualHost>
diff --git a/doc/md/docker/shaarli-images.md b/doc/md/docker/shaarli-images.md
index 12f7b5d1..5948949a 100644
--- a/doc/md/docker/shaarli-images.md
+++ b/doc/md/docker/shaarli-images.md
@@ -8,9 +8,9 @@ The images can be found in the [`shaarli/shaarli`](https://hub.docker.com/r/shaa
8repository. 8repository.
9 9
10### Available image tags 10### Available image tags
11- `latest`: latest branch (tarball release) 11- `latest`: latest branch
12- `master`: master branch (tarball release) 12- `master`: master branch
13- `stable`: stable branch (tarball release) 13- `stable`: stable branch
14 14
15The `latest` and `master` images rely on: 15The `latest` and `master` images rely on:
16 16
@@ -24,11 +24,18 @@ The `stable` image relies on:
24- [PHP5-FPM](http://php-fpm.org/) 24- [PHP5-FPM](http://php-fpm.org/)
25- [Nginx](http://nginx.org/) 25- [Nginx](http://nginx.org/)
26 26
27Additional [Dockerfiles](https://github.com/shaarli/Shaarli/tree/master/docker) are provided for the `arm32v7` platform, relying on [Linuxserver.io Alpine armhf images](https://hub.docker.com/r/lsiobase/alpine.armhf/). These images must be built using [`docker build`](https://docs.docker.com/engine/reference/commandline/build/) on an `arm32v7` machine or using an emulator such as [qemu](https://resin.io/blog/building-arm-containers-on-any-x86-machine-even-dockerhub/). 27Additional Dockerfiles are provided for the `arm32v7` platform, relying on
28[Linuxserver.io Alpine armhf
29images](https://hub.docker.com/r/lsiobase/alpine.armhf/). These images must be
30built using [`docker
31build`](https://docs.docker.com/engine/reference/commandline/build/) on an
32`arm32v7` machine or using an emulator such as
33[qemu](https://resin.io/blog/building-arm-containers-on-any-x86-machine-even-dockerhub/).
28 34
29### Download from DockerHub 35### Download from Docker Hub
30```bash 36```shell
31$ docker pull shaarli/shaarli 37$ docker pull shaarli/shaarli
38
32latest: Pulling from shaarli/shaarli 39latest: Pulling from shaarli/shaarli
3332716d9fcddb: Pull complete 4032716d9fcddb: Pull complete
3484899d045435: Pull complete 4184899d045435: Pull complete
@@ -46,7 +53,7 @@ Status: Downloaded newer image for shaarli/shaarli:latest
46``` 53```
47 54
48### Create and start a new container from the image 55### Create and start a new container from the image
49```bash 56```shell
50# map the host's :8000 port to the container's :80 port 57# map the host's :8000 port to the container's :80 port
51$ docker create -p 8000:80 shaarli/shaarli 58$ docker create -p 8000:80 shaarli/shaarli
52d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101 59d40b7af693d678958adedfb88f87d6ea0237186c23de5c4102a55a8fcb499101
@@ -62,7 +69,7 @@ d40b7af693d6 shaarli/shaarli /usr/bin/supervisor 15 seconds ago Up 4 seconds
62``` 69```
63 70
64### Stop and destroy a container 71### Stop and destroy a container
65```bash 72```shell
66$ docker stop backstabbing_galileo # those docker guys are really rude to physicists! 73$ docker stop backstabbing_galileo # those docker guys are really rude to physicists!
67backstabbing_galileo 74backstabbing_galileo
68 75
@@ -84,12 +91,34 @@ CONTAINER ID IMAGE COMMAND CREATED STATUS
84``` 91```
85 92
86### Automatic builds 93### Automatic builds
94Docker users can start a personal instance from an
95[autobuild image](https://hub.docker.com/r/shaarli/shaarli/).
96For example to start a temporary Shaarli at ``localhost:8000``, and keep session
97data (config, storage):
87 98
88Docker users can start a personal instance from an [autobuild image](https://hub.docker.com/r/shaarli/shaarli/). For example to start a temporary Shaarli at ``localhost:8000``, and keep session data (config, storage): 99```shell
89```
90MY_SHAARLI_VOLUME=$(cd /path/to/shaarli/data/ && pwd -P) 100MY_SHAARLI_VOLUME=$(cd /path/to/shaarli/data/ && pwd -P)
91docker run -ti --rm \ 101docker run -ti --rm \
92 -p 8000:80 \ 102 -p 8000:80 \
93 -v $MY_SHAARLI_VOLUME:/var/www/shaarli/data \ 103 -v $MY_SHAARLI_VOLUME:/var/www/shaarli/data \
94 shaarli/shaarli 104 shaarli/shaarli
95``` 105```
106
107### Volumes and data persistence
108Data can be persisted by [using volumes](https://docs.docker.com/storage/volumes/).
109Volumes allow to keep your data when renewing and/or updating container images:
110
111```shell
112# Create data volumes
113$ docker volume create shaarli-data
114$ docker volume create shaarli-cache
115
116# Create and start a Shaarli container using these volumes to persist data
117$ docker create \
118 --name shaarli \
119 -v shaarli-cache:/var/www/shaarli/cache \
120 -v shaarli-data:/var/www/shaarli/data \
121 -p 8000:80 \
122 shaarli/shaarli:master
123$ docker start shaarli
124```
diff --git a/doc/md/Backup,-restore,-import-and-export.md b/doc/md/guides/backup-restore-import-export.md
index bb790074..bb790074 100644
--- a/doc/md/Backup,-restore,-import-and-export.md
+++ b/doc/md/guides/backup-restore-import-export.md
diff --git a/doc/md/guides/images/01-create-droplet-distro.jpg b/doc/md/guides/images/01-create-droplet-distro.jpg
new file mode 100644
index 00000000..63682ba8
--- /dev/null
+++ b/doc/md/guides/images/01-create-droplet-distro.jpg
Binary files differ
diff --git a/doc/md/guides/images/02-create-droplet-region.jpg b/doc/md/guides/images/02-create-droplet-region.jpg
new file mode 100644
index 00000000..135a78be
--- /dev/null
+++ b/doc/md/guides/images/02-create-droplet-region.jpg
Binary files differ
diff --git a/doc/md/guides/images/03-create-droplet-size.jpg b/doc/md/guides/images/03-create-droplet-size.jpg
new file mode 100644
index 00000000..aa5b2fd2
--- /dev/null
+++ b/doc/md/guides/images/03-create-droplet-size.jpg
Binary files differ
diff --git a/doc/md/guides/images/04-finalize.jpg b/doc/md/guides/images/04-finalize.jpg
new file mode 100644
index 00000000..68ec0dc5
--- /dev/null
+++ b/doc/md/guides/images/04-finalize.jpg
Binary files differ
diff --git a/doc/md/guides/images/05-droplet.jpg b/doc/md/guides/images/05-droplet.jpg
new file mode 100644
index 00000000..44e93a1e
--- /dev/null
+++ b/doc/md/guides/images/05-droplet.jpg
Binary files differ
diff --git a/doc/md/guides/images/06-domain.jpg b/doc/md/guides/images/06-domain.jpg
new file mode 100644
index 00000000..5827dd93
--- /dev/null
+++ b/doc/md/guides/images/06-domain.jpg
Binary files differ
diff --git a/doc/md/guides/images/07-installation.jpg b/doc/md/guides/images/07-installation.jpg
new file mode 100644
index 00000000..42cc9f10
--- /dev/null
+++ b/doc/md/guides/images/07-installation.jpg
Binary files differ
diff --git a/doc/md/guides/install-shaarli-with-debian9-and-docker.md b/doc/md/guides/install-shaarli-with-debian9-and-docker.md
new file mode 100644
index 00000000..f1b26d47
--- /dev/null
+++ b/doc/md/guides/install-shaarli-with-debian9-and-docker.md
@@ -0,0 +1,257 @@
1_Last updated on 2018-07-01._
2
3## Goals
4- Getting a Virtual Private Server (VPS)
5- Running Shaarli:
6 - as a Docker container,
7 - using the Træfik reverse proxy,
8 - securized with TLS certificates from Let's Encrypt.
9
10
11The following components and tools will be used:
12
13- [Debian](https://www.debian.org/), a GNU/Linux distribution widely used in
14 server environments;
15- [Docker](https://docs.docker.com/engine/docker-overview/), an open platform
16 for developing, shipping, and running applications;
17- [Docker Compose](https://docs.docker.com/compose/), a tool for defining and
18 running multi-container Docker applications.
19
20
21More information can be found in the [Resources](#resources) section at the
22bottom of the guide.
23
24## Getting a Virtual Private Server
25For this guide, I went for the smallest VPS available from DigitalOcean,
26a Droplet with 1 CPU, 1 GiB RAM and 25 GiB SSD storage, which costs
27$5/month ($0.007/hour):
28
29- [Droplets Overview](https://www.digitalocean.com/docs/droplets/overview/)
30- [Pricing](https://www.digitalocean.com/pricing/)
31- [How to Create a Droplet from the DigitalOcean Control Panel](https://www.digitalocean.com/docs/droplets/how-to/create/)
32- [How to Add SSH Keys to Droplets](https://www.digitalocean.com/docs/droplets/how-to/add-ssh-keys/)
33- [Initial Server Setup with Debian 8](https://www.digitalocean.com/community/tutorials/initial-server-setup-with-debian-8) (also applies to Debian 9)
34- [An Introduction to Securing your Linux VPS](https://www.digitalocean.com/community/tutorials/an-introduction-to-securing-your-linux-vps)
35
36### Creating a Droplet
37Select `Debian 9` as the Droplet distribution:
38
39<img src="../images/01-create-droplet-distro.jpg"
40 width="500px"
41 alt="Droplet distribution" />
42
43Choose a region that is geographically close to you:
44
45<img src="../images/02-create-droplet-region.jpg"
46 width="500px"
47 alt="Droplet region" />
48
49Choose a Droplet size that corresponds to your usage and budget:
50
51<img src="../images/03-create-droplet-size.jpg"
52 width="500px"
53 alt="Droplet size" />
54
55Finalize the Droplet creation:
56
57<img src="../images/04-finalize.jpg"
58 width="500px"
59 alt="Droplet finalization" />
60
61Droplet information is displayed on the Control Panel:
62
63<img src="../images/05-droplet.jpg"
64 width="500px"
65 alt="Droplet summary" />
66
67Once your VPS has been created, you will receive an e-mail with connection
68instructions.
69
70## Obtaining a domain name
71After creating your VPS, it will be reachable using its IP address; some hosting
72providers also create a DNS record, e.g. `ns4853142.ip-01-47-127.eu`.
73
74A domain name (DNS record) is required to obtain a certificate and setup HTTPS
75(HTTP with TLS encryption).
76
77Domain names can be obtained from registrars through hosting providers such as
78[Gandi](https://www.gandi.net/en/domain).
79
80Once you have your own domain, you need to create a new DNS record that points
81to your VPS' IP address:
82
83<img src="../images/06-domain.jpg"
84 width="650px"
85 alt="Domain configuration" />
86
87## Host setup
88Now's the time to connect to your freshly created VPS!
89
90```shell
91$ ssh root@188.166.85.8
92
93Linux stretch-shaarli-02 4.9.0-6-amd64 #1 SMP Debian 4.9.88-1+deb9u1 (2018-05-07) x86_64
94
95The programs included with the Debian GNU/Linux system are free software;
96the exact distribution terms for each program are described in the
97individual files in /usr/share/doc/*/copyright.
98
99Debian GNU/Linux comes with ABSOLUTELY NO WARRANTY, to the extent
100permitted by applicable law.
101Last login: Sun Jul 1 11:20:18 2018 from <REDACTED>
102
103root@stretch-shaarli-02:~$
104```
105
106### Updating the system
107```shell
108root@stretch-shaarli-02:~$ apt update && apt upgrade -y
109```
110
111### Setting up Docker
112_The following instructions are from the
113[Get Docker CE for Debian](https://docs.docker.com/install/linux/docker-ce/debian/)
114guide._
115
116Install package dependencies:
117
118```shell
119root@stretch-shaarli-02:~$ apt install -y apt-transport-https ca-certificates curl gnupg2 software-properties-common
120```
121
122Add Docker's package repository GPG key:
123
124```shell
125root@stretch-shaarli-02:~$ curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -
126```
127
128Add Docker's package repository:
129
130```shell
131root@stretch-shaarli-02:~$ add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian stretch stable"
132```
133
134Update package lists and install Docker:
135
136```shell
137root@stretch-shaarli-02:~$ apt update && apt install -y docker-ce
138```
139
140Verify Docker is properly configured by running the `hello-world` image:
141
142```shell
143root@stretch-shaarli-02:~$ docker run hello-world
144```
145
146### Setting up Docker Compose
147_The following instructions are from the
148[Install Docker Compose](https://docs.docker.com/compose/install/)
149guide._
150
151Download the current version from the release page:
152
153```shell
154root@stretch-shaarli-02:~$ curl -L https://github.com/docker/compose/releases/download/1.21.2/docker-compose-$(uname -s)-$(uname -m) -o /usr/local/bin/docker-compose
155root@stretch-shaarli-02:~$ chmod +x /usr/local/bin/docker-compose
156```
157
158## Running Shaarli
159Shaarli comes with a configuration file for Docker Compose, that will setup:
160
161- a local Docker network
162- a Docker [volume](https://docs.docker.com/storage/volumes/) to store Shaarli data
163- a Docker [volume](https://docs.docker.com/storage/volumes/) to store Træfik TLS configuration and certificates
164- a [Shaarli](https://hub.docker.com/r/shaarli/shaarli/) instance
165- a [Træfik](https://hub.docker.com/_/traefik/) instance
166
167[Træfik](https://docs.traefik.io/) is a modern HTTP reverse proxy, with native
168support for Docker and [Let's Encrypt](https://letsencrypt.org/).
169
170### Compose configuration
171Create a new directory to store the configuration:
172
173```shell
174root@stretch-shaarli-02:~$ mkdir shaarli && cd shaarli
175root@stretch-shaarli-02:~/shaarli$
176```
177
178Download the current version of Shaarli's `docker-compose.yml`:
179
180```shell
181root@stretch-shaarli-02:~/shaarli$ curl -L https://raw.githubusercontent.com/shaarli/Shaarli/master/docker-compose.yml -o docker-compose.yml
182```
183
184Create the `.env` file and fill in your VPS and domain information (replace
185`<MY_SHAARLI_DOMAIN>` and `<MY_CONTACT_EMAIL>` with your actual information):
186
187```shell
188root@stretch-shaarli-02:~/shaarli$ vim .env
189```
190
191```shell
192SHAARLI_VIRTUAL_HOST=<MY_SHAARLI_DOMAIN>
193SHAARLI_LETSENCRYPT_EMAIL=<MY_CONTACT_EMAIL>
194```
195
196### Pull the Docker images
197```shell
198root@stretch-shaarli-02:~/shaarli$ docker-compose pull
199Pulling shaarli ... done
200Pulling traefik ... done
201```
202
203### Run!
204```shell
205root@stretch-shaarli-02:~/shaarli$ docker-compose up -d
206Creating network "shaarli_http-proxy" with the default driver
207Creating volume "shaarli_traefik-acme" with default driver
208Creating volume "shaarli_shaarli-data" with default driver
209Creating shaarli_shaarli_1 ... done
210Creating shaarli_traefik_1 ... done
211```
212
213## Conclusion
214Congratulations! Your Shaarli instance should be up and running, and available
215at `https://<MY_SHAARLI_DOMAIN>`.
216
217<img src="../images/07-installation.jpg"
218 width="500px"
219 alt="Shaarli installation page" />
220
221## Resources
222### Related Shaarli documentation
223- [Docker 101](../docker/docker-101.md)
224- [Shaarli images](../docker/shaarli-images.md)
225
226### Hosting providers
227- [DigitalOcean](https://www.digitalocean.com/)
228- [Gandi](https://www.gandi.net/en)
229- [OVH](https://www.ovh.co.uk/)
230- [RackSpace](https://www.rackspace.com/)
231- etc.
232
233### Domain Names and Registrars
234- [Introduction to the Domain Name System (DNS)](https://opensource.com/article/17/4/introduction-domain-name-system-dns)
235- [ICANN](https://www.icann.org/)
236- [Domain name registrar](https://en.wikipedia.org/wiki/Domain_name_registrar)
237- [OVH Domain Registration](https://www.ovh.co.uk/domains/)
238- [Gandi Domain Registration](https://www.gandi.net/en/domain)
239
240### HTTPS and Security
241- [Transport Layer Security](https://en.wikipedia.org/wiki/Transport_Layer_Security)
242- [Let's Encrypt](https://letsencrypt.org/)
243
244### Docker
245- [Docker Overview](https://docs.docker.com/engine/docker-overview/)
246- [Docker Documentation](https://docs.docker.com/)
247- [Get Docker CE for Debian](https://docs.docker.com/install/linux/docker-ce/debian/)
248- [docker logs](https://docs.docker.com/engine/reference/commandline/logs/)
249- [Volumes](https://docs.docker.com/storage/volumes/)
250- [Install Docker Compose](https://docs.docker.com/compose/install/)
251- [docker-compose logs](https://docs.docker.com/compose/reference/logs/)
252
253### Træfik
254- [Getting Started](https://docs.traefik.io/)
255- [Docker backend](https://docs.traefik.io/configuration/backends/docker/)
256- [Let's Encrypt and Docker](https://docs.traefik.io/user-guide/docker-and-lets-encrypt/)
257- [traefik](https://hub.docker.com/_/traefik/) Docker image
diff --git a/doc/md/Various-hacks.md b/doc/md/guides/various-hacks.md
index 0074ae9f..0074ae9f 100644
--- a/doc/md/Various-hacks.md
+++ b/doc/md/guides/various-hacks.md
diff --git a/doc/md/images/doc-logo.png b/doc/md/images/doc-logo.png
index 3d8d1787..3da7ba57 100644
--- a/doc/md/images/doc-logo.png
+++ b/doc/md/images/doc-logo.png
Binary files differ
diff --git a/doc/md/images/edit_icon.png b/doc/md/images/edit_icon.png
new file mode 100644
index 00000000..16c440c8
--- /dev/null
+++ b/doc/md/images/edit_icon.png
Binary files differ
diff --git a/doc/md/images/firefoxshare.png b/doc/md/images/firefoxshare.png
index 98c2fdd3..8f8fdba4 100644
--- a/doc/md/images/firefoxshare.png
+++ b/doc/md/images/firefoxshare.png
Binary files differ
diff --git a/doc/md/images/icon.png b/doc/md/images/icon.png
new file mode 100644
index 00000000..530d7469
--- /dev/null
+++ b/doc/md/images/icon.png
Binary files differ
diff --git a/doc/md/images/install-shaarli.png b/doc/md/images/install-shaarli.png
index 7ae33816..d5d5baa7 100644
--- a/doc/md/images/install-shaarli.png
+++ b/doc/md/images/install-shaarli.png
Binary files differ
diff --git a/doc/md/images/logo.png b/doc/md/images/logo.png
new file mode 100644
index 00000000..f8b0c94f
--- /dev/null
+++ b/doc/md/images/logo.png
Binary files differ
diff --git a/doc/md/images/rss-filter-1.png b/doc/md/images/rss-filter-1.png
index d2a03f67..0cf1591c 100644
--- a/doc/md/images/rss-filter-1.png
+++ b/doc/md/images/rss-filter-1.png
Binary files differ
diff --git a/doc/md/images/rss-filter-2.png b/doc/md/images/rss-filter-2.png
index 538b126e..5a40755a 100644
--- a/doc/md/images/rss-filter-2.png
+++ b/doc/md/images/rss-filter-2.png
Binary files differ
diff --git a/doc/md/index.md b/doc/md/index.md
index e77b4d3a..220eeec1 100644
--- a/doc/md/index.md
+++ b/doc/md/index.md
@@ -1,19 +1,21 @@
1# [Shaarli](https://github.com/shaarli/Shaarli/) documentation 1# <img src="images/icon.png" width="20px" height="20px"> Shaarli
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 4
5For general info, read the [README](https://github.com/shaarli/Shaarli/blob/master/README.md). 5Do you want to share the links you discover?
6Shaarli is a minimalist bookmark manager and link sharing service that you can install on your own server.
7It is designed to be personal (single-user), fast and handy.
6 8
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). 9<!-- TODO screenshots -->
8If you've found a bug, please create a [new issue](https://github.com/shaarli/Shaarli/issues/new).
9 10
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). 11Visit the pages in the sidebar to find information on how to setup, use, configure, tweak and troubleshoot Shaarli.
11 12
12_Note: This documentation is available online at https://shaarli.readthedocs.io/, and locally in the `doc/html/` directory of your Shaarli installation._
13 13
14[![Join the chat at https://gitter.im/shaarli/Shaarli](https://badges.gitter.im/Join%20Chat.svg)](https://gitter.im/shaarli/Shaarli) 14* [GitHub project page](https://github.com/shaarli/Shaarli)
15[![Bountysource](https://www.bountysource.com/badge/team?team_id=19583&style=bounties_received)](https://www.bountysource.com/teams/shaarli/issues) 15* [Online documentation](https://shaarli.readthedocs.io/)
16[![Docker repository](https://img.shields.io/docker/pulls/shaarli/shaarli.svg)](https://hub.docker.com/r/shaarli/shaarli/) 16* [Latest releases](https://github.com/shaarli/Shaarli/releases)
17* [Changelog](https://github.com/shaarli/Shaarli/blob/master/CHANGELOG.md)
18
17 19
18### Demo 20### Demo
19 21
@@ -26,104 +28,94 @@ Login: `demo`; Password: `demo`
26 28
27Shaarli can be used: 29Shaarli can be used:
28 30
29- to share, comment and save interesting links and news. 31- to share, comment and save interesting links and news
30- to bookmark useful/frequent personal links (as private links) and share them between computers. 32- to bookmark useful/frequent links and share them between computers
31- as a minimal blog/microblog/writing platform (no character limit). 33- as a minimal blog/microblog/writing platform
32- as a read-it-later list (for example items tagged `readlater`). 34- as a read-it-later list
33- to draft and save articles/posts/ideas. 35- to draft and save articles/posts/ideas
34- to keep code snippets. 36- to keep notes, documentation and code snippets
35- to keep notes and documentation. 37- as a shared clipboard/notepad/pastebin between machines
36- as a shared clipboard/notepad/pastebin between machines. 38- as a todo list
37- as a todo list. 39- to store media playlists
38- to store playlists (e.g. with the `music` or `video` tags).
39- to keep extracts/comments from webpages that may disappear. 40- to keep extracts/comments from webpages that may disappear.
40- to keep track of ongoing discussions (for example items tagged `discussion`). 41- to keep track of ongoing discussions
41- [to feed RSS aggregators](http://shaarli.chassegnouf.net/?9Efeiw) (planets) with specific tags. 42- to feed other blogs, aggregators, social networks... using RSS feeds
42- to feed other social networks, blogs... using RSS feeds and external services (dlvr.it, ifttt.com ...). 43
44### Edit, view and search your links
43 45
44### Interface 46- Minimalist design
45- minimalist design (simple is beautiful)
46- FAST 47- FAST
47- ATOM and RSS feeds 48- Customizable link titles and descriptions
48- views: 49- Tags to organize your links (features tag autocompletion, renaming, merging and deletion)
49 - paginated link list 50- Search by tag or using the full-text search
50 - tag cloud 51- Public and private links (visible only to logged-in users)
51 - picture wall: image and video thumbnails 52- Unique permalinks for easy reference
52 - daily: newspaper-like daily digest 53- Paginated link list (with image and video thumbnails)
53 - daily RSS feed 54- Tag cloud and list views
54- permalinks for easy reference 55- Picture wall: image and video thumbnails view (with lazy loading)
55- links can be public or private 56- ATOM and RSS feeds (can also be filtered using tags or text search)
56- extensible through [plugins](https://shaarli.readthedocs.io/en/master/Plugins/#plugin-usage) 57- Daily: newspaper-like daily digest (and daily RSS feed)
57 58- URL cleanup: automatic removal of `?utm_source=...`, `fb=...`
58### Tag, view and search your links! 59- Extensible through [plugins](https://shaarli.readthedocs.io/en/master/Plugins/#plugin-usage)
59- add a custom title and description to archived links
60- add tags to classify and search links
61 - features tag autocompletion, renaming, merging and deletion
62- full-text and tag search
63 60
64### Easy setup 61### Easy setup
65- dead-simple installation: drop the files, open the page 62
66- links are stored in a file 63- Dead-simple installation: drop the files, open the page
67 - compact storage 64- Links are stored in a file (no database required, easy backup: simply copy the datastore file)
68 - no database required 65- Import and export links as Netscape bookmarks compatible with most Web browsers
69 - easy backup: simply copy the datastore file
70- import and export links as Netscape bookmarks
71 66
72### Accessibility 67### Accessibility
73- Firefox bookmarlet to share links in one click 68
74- support for mobile browsers 69- Bookmarklet and other tools to share links in one click
75- works with Javascript disabled 70- Support for mobile browsers
76- easy page customization through HTML/CSS/RainTPL 71- Degrades gracefully with Javascript disabled
72- Easy page customization through HTML/CSS/RainTPL
77 73
78### Security 74### Security
79- bruteforce-proof login form
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
90 75
91### REST API 76- Discreet pop-up notification when a new release is available
77- Bruteforce protection on the login form
78- Protected against [XSRF](http://en.wikipedia.org/wiki/Cross-site_request_forgery) and session cookie hijacking
92 79
93Easily extensible by any client using the REST API exposed by Shaarli. 80<!-- TODO Limitations -->
94 81
95See the [API documentation](http://shaarli.github.io/api-documentation/). 82### REST API
96 83
97### Using Shaarli as a blog, notepad, pastebin... 84- Easily extensible by any client using the REST API exposed by Shaarli ([API documentation](http://shaarli.github.io/api-documentation/)).
98- Go to your Shaarli setup and log in
99- Click the `Add Link` button
100- To share text only, do not enter any URL in the corresponding input field and click `Add Link`
101- Pick a title and enter your article, or note, in the description field; add a few tags; optionally check `Private` then click `Save`
102- Voilà! Your article is now published (privately if you selected that option) and accessible using its permalink.
103 85
104## About 86## About
87
105### Shaarli community fork 88### Shaarli community fork
106This friendly fork is maintained by the Shaarli community at https://github.com/shaarli/Shaarli 89
90This friendly fork is maintained by the Shaarli community at <https://github.com/shaarli/Shaarli>
107 91
108This is a community fork of the original [Shaarli](https://github.com/sebsauvage/Shaarli/) project by [Sébastien Sauvage](http://sebsauvage.net/). 92This is a community fork of the original [Shaarli](https://github.com/sebsauvage/Shaarli/) project by [Sébastien Sauvage](http://sebsauvage.net/).
109 93
110The original project is currently unmaintained, and the developer [has informed us](https://github.com/sebsauvage/Shaarli/issues/191) 94The 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.
111that he would have no time to work on Shaarli in the near future. 95
112The Shaarli community has carried on the work to provide 96The Shaarli community has carried on the work to provide [many
113[many patches](https://github.com/shaarli/Shaarli/compare/sebsauvage:master...master) 97patches](https://github.com/shaarli/Shaarli/compare/sebsauvage:master...master) for
114for [bug fixes and enhancements](https://github.com/shaarli/Shaarli/issues?q=is%3Aclosed+) 98[bug fixes and enhancements](https://github.com/shaarli/Shaarli/issues?q=is%3Aclosed+)
115in this repository, and will keep maintaining the project for the foreseeable future, while keeping Shaarli simple and efficient. 99in this repository, and will keep maintaining the project for the foreseeable
100future, while keeping Shaarli simple and efficient.
101
116 102
117### Contributing 103### Contributing and getting help
118If you'd like to help, please: 104
119- have a look at the open [issues](https://github.com/shaarli/Shaarli/issues) 105Feedback is very appreciated!
120and [pull requests](https://github.com/shaarli/Shaarli/pulls) 106
121- feel free to report bugs (feedback is much appreciated) 107- If 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).
122- suggest new features and improvements to both code and [documentation](https://github.com/shaarli/Shaarli/wiki) 108- Have a look at the open [issues](https://github.com/shaarli/Shaarli/issues) and [pull requests](https://github.com/shaarli/Shaarli/pulls)
123- propose solutions to existing problems 109- If 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).
124- submit pull requests :-) 110- If you've found a bug, please create a [new issue](https://github.com/shaarli/Shaarli/issues/new).
111- Feel free to propose solutions to existing problems, help us improve the documentation and translations, and submit pull requests :-)
125 112
126 113
127### License 114### License
128Shaarli 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. 115
116Shaarli is [Free Software](http://en.wikipedia.org/wiki/Free_software). See
117[COPYING](https://github.com/shaarli/Shaarli/blob/master/COPYING) for a detail
118of the contributors and licenses for each individual component. A list of
119contributors is available
120[here](https://github.com/shaarli/Shaarli/blob/master/AUTHORS).
129 121
generated by cgit v1.2.3 (git 2.25.1) at 2024-05-29 12:04:02 +0000