aboutsummaryrefslogtreecommitdiffhomepage
path: root/doc/md
diff options
context:
space:
mode:
Diffstat (limited to 'doc/md')
-rw-r--r--doc/md/Browsing-and-searching.md2
-rw-r--r--doc/md/Community-&-Related-software.md9
-rw-r--r--doc/md/Download-and-Installation.md46
-rw-r--r--doc/md/Firefox-share.md3
-rw-r--r--doc/md/Server-requirements.md1
-rw-r--r--doc/md/Shaarli-configuration.md21
-rw-r--r--doc/md/Translations.md152
-rw-r--r--doc/md/Unit-tests.md10
-rw-r--r--doc/md/Upgrade-and-migration.md21
-rw-r--r--doc/md/docker/reverse-proxy-configuration.md116
-rw-r--r--doc/md/docker/shaarli-images.md27
-rw-r--r--doc/md/images/install-shaarli.pngbin0 -> 44376 bytes
-rw-r--r--doc/md/images/poedit-1.jpgbin0 -> 72956 bytes
-rw-r--r--doc/md/index.md43
14 files changed, 406 insertions, 45 deletions
diff --git a/doc/md/Browsing-and-searching.md b/doc/md/Browsing-and-searching.md
index 24483139..f948bbe1 100644
--- a/doc/md/Browsing-and-searching.md
+++ b/doc/md/Browsing-and-searching.md
@@ -25,7 +25,7 @@ The `Tag cloud` page diplays a "cloud" view of all tags in your Shaarli.
25 25
26## Filtering RSS feeds/Picture wall 26## Filtering RSS feeds/Picture wall
27 27
28RSS feeds can also be restricted to only return items matching a text/tag search: see [RSS feeds](RSS feeds). 28RSS feeds can also be restricted to only return items matching a text/tag search: see [RSS feeds](RSS-feeds).
29 29
30## Filter buttons 30## Filter buttons
31 31
diff --git a/doc/md/Community-&-Related-software.md b/doc/md/Community-&-Related-software.md
index 8edbeefa..3c55e935 100644
--- a/doc/md/Community-&-Related-software.md
+++ b/doc/md/Community-&-Related-software.md
@@ -34,6 +34,7 @@ See [REST API](REST-API) for a list of official and community clients.
34- [related](https://github.com/ilesinge/shaarli-related) by [@ilesinge](https://github.com/ilesinge) - Show related links based on the number of identical tags. 34- [related](https://github.com/ilesinge/shaarli-related) by [@ilesinge](https://github.com/ilesinge) - Show related links based on the number of identical tags.
35- [social](https://github.com/alexisju/social) by [@alexisju](https://github.com/alexisju): share links to social networks. 35- [social](https://github.com/alexisju/social) by [@alexisju](https://github.com/alexisju): share links to social networks.
36- [shaarli2twitter](https://github.com/ArthurHoaro/shaarli2twitter) by [@ArthurHoaro](https://github.com/ArthurHoaro) - Automatically tweet your shared links from Shaarli 36- [shaarli2twitter](https://github.com/ArthurHoaro/shaarli2twitter) by [@ArthurHoaro](https://github.com/ArthurHoaro) - Automatically tweet your shared links from Shaarli
37- [shaarli2mastodon](https://github.com/kalvn/shaarli2mastodon) by [@kalvn](https://github.com/kalvn) - This Shaarli plugin allows you to automatically publish links you post on your Mastodon timeline.
37 38
38 39
39### Third-party themes 40### Third-party themes
@@ -47,10 +48,12 @@ See [Theming](Theming) for a list of community-contributed themes, and an instal
47 48
48 49
49### Mobile Apps 50### Mobile Apps
50- [ShaarliOS](https://github.com/mro/ShaarliOS) iOS share extension - see [#308](https://github.com/shaarli/Shaarli/issues/308#issuecomment-184592070) for some promo codes, 51- [ShaarliOS](https://github.com/mro/ShaarliOS) - Apple iOS share extension.
51- [Shaarli for Android](http://sebsauvage.net/links/?ZAyDzg) - Android application that adds Shaarli as a sharing provider 52- [Shaarli for Android](http://sebsauvage.net/links/?ZAyDzg) - Android application that adds Shaarli as a sharing provider
52- [Shaarlier for Android](https://github.com/dimtion/Shaarlier) - Android application to simply add links directly into your Shaarli 53- [Shaarlier for Android](https://github.com/dimtion/Shaarlier) - Android application to simply add links directly into your Shaarli
53 54
55### Browser addons
56 * [Shaarli Web Extension](https://github.com/ikipatang/shaarli-web-extension) - toolbar button to share your current tab with Shaarli.
54 57
55### Server apps 58### Server apps
56- [shaarchiver](https://github.com/nodiscc/shaarchiver) - Archive your Shaarli bookmarks and their content 59- [shaarchiver](https://github.com/nodiscc/shaarchiver) - Archive your Shaarli bookmarks and their content
@@ -61,7 +64,5 @@ See [Theming](Theming) for a list of community-contributed themes, and an instal
61- [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). 64- [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).
62- [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. 65- [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.
63 66
64
65## Alternatives to Shaarli 67## Alternatives to Shaarli
66See the [bookmarks & link sharing](https://github.com/Kickball/awesome-selfhosted/#bookmarks--link-sharing) 68See [awesome-selfhosted: bookmarks & link sharing](https://github.com/Kickball/awesome-selfhosted/#bookmarks--link-sharing).
67section on [awesome-selfhosted](https://github.com/Kickball/awesome-selfhosted/).
diff --git a/doc/md/Download-and-Installation.md b/doc/md/Download-and-Installation.md
index e5e929ef..bbbfc26d 100644
--- a/doc/md/Download-and-Installation.md
+++ b/doc/md/Download-and-Installation.md
@@ -4,44 +4,57 @@ Document Root (or directly at the document root).
4Also, please make sure your server meets the [requirements](Server-requirements) 4Also, please make sure your server meets the [requirements](Server-requirements)
5and is properly [configured](Server-configuration). 5and is properly [configured](Server-configuration).
6 6
7Several releases are available: 7Multiple releases branches are available:
8
9- latest (last release)
10- stable (previous major release)
11- master (development)
12
13Using one of the following methods:
8 14
9- by downloading full release archives including all dependencies 15- by downloading full release archives including all dependencies
10- by downloading Github archives 16- by downloading Github archives
11- by cloning the Git repository 17- by cloning the Git repository
18- using Docker: [see the documentation](docker/shaarli-images.md)
12 19
13--- 20--------------------------------------------------------------------------------
14 21
15## Latest release (recommended) 22## Latest release (recommended)
23
16### Download as an archive 24### Download as an archive
17Get the latest released version from the [releases](https://github.com/shaarli/Shaarli/releases) page.
18 25
19**Download our *shaarli-full* archive** to include dependencies. 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.
20 27
21The current latest released version is `v0.9.1` 28The current latest released version is `v0.9.1`
22 29
23Or in command lines:
24
25```bash 30```bash
26$ wget https://github.com/shaarli/Shaarli/releases/download/v0.9.1/shaarli-v0.9.1-full.zip 31$ wget https://github.com/shaarli/Shaarli/releases/download/v0.9.1/shaarli-v0.9.1-full.zip
27$ unzip shaarli-v0.9.1-full.zip 32$ unzip shaarli-v0.9.1-full.zip
28$ mv Shaarli /path/to/shaarli/ 33$ mv Shaarli /path/to/shaarli/
29``` 34```
30 35
31In most cases, download Shaarli from the [releases](https://github.com/shaarli/Shaarli/releases) page. Cloning using `git` or downloading Github branches as zip files requires additional steps (see below).|
32
33### Using git 36### Using git
34 37
38Cloning using `git` or downloading Github branches as zip files requires additional steps:
39
40 * Install [Composer](Unit-tests.md#install_composer) to manage Shaarli dependencies.
41 * Install [python3-virtualenv](https://pypi.python.org/pypi/virtualenv) to build the local HTML documentation.
42
35``` 43```
36$ mkdir -p /path/to/shaarli && cd /path/to/shaarli/ 44$ mkdir -p /path/to/shaarli && cd /path/to/shaarli/
37$ git clone -b v0.9 https://github.com/shaarli/Shaarli.git . 45$ git clone -b latest https://github.com/shaarli/Shaarli.git .
38$ composer install --no-dev --prefer-dist 46$ composer install --no-dev --prefer-dist
47$ make translate
48$ make htmldoc
39``` 49```
40 50
51--------------------------------------------------------------------------------
52
41## Stable version 53## Stable version
42 54
43The stable version has been experienced by Shaarli users, and will receive security updates. 55The stable version has been experienced by Shaarli users, and will receive security updates.
44 56
57
45### Download as an archive 58### Download as an archive
46 59
47As a .zip archive: 60As a .zip archive:
@@ -60,9 +73,9 @@ $ tar xvf stable.tar.gz
60$ mv Shaarli-stable /path/to/shaarli/ 73$ mv Shaarli-stable /path/to/shaarli/
61``` 74```
62 75
63### Clone with Git 76### Using git
64 77
65[Composer](https://getcomposer.org/) is required to build a functional Shaarli installation when pulling from git. 78Install [Composer](Unit-tests.md#install_composer) to manage Shaarli dependencies.
66 79
67```bash 80```bash
68$ git clone https://github.com/shaarli/Shaarli.git -b stable /path/to/shaarli/ 81$ git clone https://github.com/shaarli/Shaarli.git -b stable /path/to/shaarli/
@@ -71,10 +84,15 @@ $ cd /path/to/shaarli/
71$ composer install --no-dev --prefer-dist 84$ composer install --no-dev --prefer-dist
72``` 85```
73 86
87
88--------------------------------------------------------------------------------
89
74## Development version (mainline) 90## Development version (mainline)
75 91
76_Use at your own risk!_ 92_Use at your own risk!_
77 93
94Install [Composer](Unit-tests.md#install_composer) to manage Shaarli dependencies.
95
78To get the latest changes from the `master` branch: 96To get the latest changes from the `master` branch:
79 97
80```bash 98```bash
@@ -83,13 +101,17 @@ $ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/
83# install/update third-party dependencies 101# install/update third-party dependencies
84$ cd /path/to/shaarli 102$ cd /path/to/shaarli
85$ composer install --no-dev --prefer-dist 103$ composer install --no-dev --prefer-dist
104$ make translate
105$ make htmldoc
86``` 106```
87 107
108-------------------------------------------------------------------------------
109
88## Finish Installation 110## Finish Installation
89 111
90Once Shaarli is downloaded and files have been placed at the correct location, open it this location your favorite browser. 112Once Shaarli is downloaded and files have been placed at the correct location, open it this location your favorite browser.
91 113
92![install screenshot](http://i.imgur.com/wuMpDSN.png) 114![install screenshot](images/install-shaarli.png)
93 115
94Setup your Shaarli installation, and it's ready to use! 116Setup your Shaarli installation, and it's ready to use!
95 117
diff --git a/doc/md/Firefox-share.md b/doc/md/Firefox-share.md
index 878884a4..9a46b185 100644
--- a/doc/md/Firefox-share.md
+++ b/doc/md/Firefox-share.md
@@ -1,3 +1,6 @@
1| Note | Firefox Share is no longer available for Firefox 57 and later versions. |
2|---------|---------|
3
1### Add Shaarli as a sharing service to Firefox 4### Add Shaarli as a sharing service to Firefox
2 5
3- Open your Shaarli and `Login` 6- Open your Shaarli and `Login`
diff --git a/doc/md/Server-requirements.md b/doc/md/Server-requirements.md
index 707af762..400b85a9 100644
--- a/doc/md/Server-requirements.md
+++ b/doc/md/Server-requirements.md
@@ -39,3 +39,4 @@ Extension | Required? | Usage
39[`php-gd`](http://php.net/manual/en/book.image.php) | optional | thumbnail resizing 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`) 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 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/Shaarli-configuration.md b/doc/md/Shaarli-configuration.md
index 99b25ba7..920c7e27 100644
--- a/doc/md/Shaarli-configuration.md
+++ b/doc/md/Shaarli-configuration.md
@@ -81,6 +81,20 @@ _These settings should not be edited_
81- **page_cache**: Shaarli's internal cache directory. 81- **page_cache**: Shaarli's internal cache directory.
82- **ban_file**: Banned IP file path. 82- **ban_file**: Banned IP file path.
83 83
84### Translation
85
86- **language**: translation language (also see [Translations](Translations))
87 - **auto** (default): The translation language is chosen from the browser locale.
88 It means that the language can be different for 2 different visitors depending on their locale.
89 - **en**: Use the English translation.
90 - **fr**: Use the French translation.
91- **mode**:
92 - **auto** or **php** (default): Use the PHP implementation of gettext (slower)
93 - **gettext**: Use PHP builtin gettext extension
94 (faster, but requires `php-gettext` to be installed and to reload the web server on update)
95- **extension**: Translation extensions for custom themes or plugins.
96Must be an associative array: `translation domain => translation path`.
97
84### Updates 98### Updates
85 99
86- **check_updates**: Enable or disable update check to the git repository. 100- **check_updates**: Enable or disable update check to the git repository.
@@ -211,6 +225,13 @@ _These settings should not be edited_
211 "plugins": { 225 "plugins": {
212 "WALLABAG_URL": "http://demo.wallabag.org", 226 "WALLABAG_URL": "http://demo.wallabag.org",
213 "WALLABAG_VERSION": "1" 227 "WALLABAG_VERSION": "1"
228 },
229 "translation": {
230 "language": "fr",
231 "mode": "php",
232 "extensions": {
233 "demo": "plugins/demo_plugin/languages/"
234 }
214 } 235 }
215} ?> 236} ?>
216``` 237```
diff --git a/doc/md/Translations.md b/doc/md/Translations.md
new file mode 100644
index 00000000..54a36655
--- /dev/null
+++ b/doc/md/Translations.md
@@ -0,0 +1,152 @@
1## Translations
2
3Shaarli supports [gettext](https://www.gnu.org/software/gettext/manual/gettext.html) translations
4since `>= v0.9.2`.
5
6Note that only the `default` theme supports translations.
7
8### Contributing
9
10We encourage the community to contribute to Shaarli's translation either by improving existing
11translations or submitting a new language.
12
13Contributing to the translation does not require development skill.
14
15Please submit a pull request with the `.po` file updated/created. Note that the compiled file (`.mo`)
16is not stored on the repository, and is generated during the release process.
17
18### How to
19
20First, install [Poedit](https://poedit.net/) tool.
21
22Poedit will extract strings to translate from the PHP source code.
23
24**Important**: due to the usage of a template engine, it's important to generate PHP cache files to extract
25every translatable string.
26
27You can either use [this script](https://gist.github.com/ArthurHoaro/5d0323f758ab2401ef444a53f54e9a07) (recommended)
28or visit every template page in your browser to generate cache files, while logged in.
29
30Here is a list :
31
32```
33http://<replace_domain>/
34http://<replace_domain>/?nonope
35http://<replace_domain>/?do=addlink
36http://<replace_domain>/?do=changepasswd
37http://<replace_domain>/?do=changetag
38http://<replace_domain>/?do=configure
39http://<replace_domain>/?do=tools
40http://<replace_domain>/?do=daily
41http://<replace_domain>/?post
42http://<replace_domain>/?do=export
43http://<replace_domain>/?do=import
44http://<replace_domain>/?do=login
45http://<replace_domain>/?do=picwall
46http://<replace_domain>/?do=pluginadmin
47http://<replace_domain>/?do=tagcloud
48http://<replace_domain>/?do=taglist
49```
50
51#### Improve existing translation
52
53In Poedit, click on "Edit a Translation", and from Shaarli's directory open
54`inc/languages/<lang>/LC_MESSAGES/shaarli.po`.
55
56The existing list of translatable strings should have been loaded, then click on the "Update" button.
57
58You can start editing the translation.
59
60![poedit-screenshot](images/poedit-1.jpg)
61
62Save when you're done, then you can submit a pull request containing the updated `shaarli.po`.
63
64#### Add a new language
65
66Open Poedit and select "Create New Translation", then from Shaarli's directory open
67`inc/languages/<lang>/LC_MESSAGES/shaarli.po`.
68
69Then select the language you want to create.
70
71Click on `File > Save as...`, and save your file in `<shaarli directory>/inc/language/<new language>/LC_MESSAGES/shaarli.po`.
72`<new language>` here should be the language code respecting the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-2)
73format in lowercase (e.g. `de` for German).
74
75Then click on the "Update" button, and you can start to translate every available string.
76
77Save when you're done, then you can submit a pull request containing the new `shaarli.po`.
78
79### Extend Shaarli's translation
80
81If you're writing a custom theme, or a non official plugin, you might want to use the translation system,
82but you won't be able to able to override Shaarli's translation.
83
84However, you can add your own translation domain which extends the main translation list.
85
86> Note that you can find a live example of translation extension in the `demo_plugin`.
87
88First, create your translation files tree directory:
89
90```
91<your_module>/languages/<ISO 3166-1 alpha-2 language code>/LC_MESSAGES/
92```
93
94Your `.po` files must be named like your domain. E.g. if your translation domain is `my_theme`, then your file will be
95`my_theme.po`.
96
97Users have to register your extension in their configuration with the parameter
98`translation.extensions.<domain>: <translation files path>`.
99
100Example:
101
102```php
103if (! $conf->exists('translation.extensions.my_theme')) {
104 $conf->set('translation.extensions.my_theme', '<your_module>/languages/');
105 $conf->write(true);
106}
107```
108
109> Note that the page needs to be reloaded after the registration.
110
111It is then recommended to create a custom translation function which will call the `t()` function with your domain.
112For example :
113
114```php
115function my_theme_t($text, $nText = '', $nb = 1)
116{
117 return t($text, $nText, $nb, 'my_theme'); // the last parameter is your translation domain.
118}
119```
120
121All strings which can be translated should be processed through your function:
122
123```php
124my_theme_t('Comment');
125my_theme_t('Comment', 'Comments', 2);
126```
127
128Or in templates:
129
130```php
131{'Comment'|my_theme_t}
132{function="my_theme_t('Comment', 'Comments', 2)"}
133```
134
135> Note than in template, you need to visit your page at least once to generate a cache file.
136
137When you're done, open Poedit and load translation strings from sources:
138
139 1. `File > New`
140 2. Choose your language
141 3. Save your `PO` file in `<your_module>/languages/<language code>/LC_MESSAGES/my_theme.po`.
142 4. Go to `Catalog > Properties...`
143 5. Fill the `Translation Properties` tab
144 6. Add your source path in the `Sources Paths` tab
145 7. In the `Sources Keywords` tab uncheck "Also use default keywords" and add the following lines:
146
147```
148my_theme_t
149my_theme_t:1,2
150```
151
152Click on the "Update" button and you're free to start your translations!
diff --git a/doc/md/Unit-tests.md b/doc/md/Unit-tests.md
index d200634f..f6030d5c 100644
--- a/doc/md/Unit-tests.md
+++ b/doc/md/Unit-tests.md
@@ -2,12 +2,12 @@
2 2
3The framework used is [PHPUnit](https://phpunit.de/); it can be installed with [Composer](https://getcomposer.org/), which is a dependency management tool. 3The framework used is [PHPUnit](https://phpunit.de/); it can be installed with [Composer](https://getcomposer.org/), which is a dependency management tool.
4 4
5Regarding Composer, you can either use: 5### Install composer
6 6
7- a system-wide version, e.g. installed through your distro's package manager 7You can either use:
8- a local version, downloadable [here](https://getcomposer.org/download/)
9 8
10#### Sample usage 9- a system-wide version, e.g. installed through your distro's package manager
10- a local version, downloadable [here](https://getcomposer.org/download/).
11 11
12```bash 12```bash
13# system-wide version 13# system-wide version
@@ -29,6 +29,8 @@ $ composer update
29 29
30#### Install and enable Xdebug to generate PHPUnit coverage reports 30#### Install and enable Xdebug to generate PHPUnit coverage reports
31 31
32See http://xdebug.org/docs/install
33
32For Debian-based distros: 34For Debian-based distros:
33```bash 35```bash
34$ aptitude install php5-xdebug 36$ aptitude install php5-xdebug
diff --git a/doc/md/Upgrade-and-migration.md b/doc/md/Upgrade-and-migration.md
index 7033cd41..1dc07339 100644
--- a/doc/md/Upgrade-and-migration.md
+++ b/doc/md/Upgrade-and-migration.md
@@ -39,7 +39,10 @@ We recommend that you use the latest release tarball with the `-full` suffix. It
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
42After 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). 42If you use translations in gettext mode - meaning you manually changed the default mode -,
43reload your web server.
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).
43 46
44## Upgrading with Git 47## Upgrading with Git
45 48
@@ -72,6 +75,14 @@ Updating dependencies
72 Downloading: 100% 75 Downloading: 100%
73``` 76```
74 77
78Shaarli >= `v0.9.2` supports translations:
79
80```bash
81$ make translate
82```
83
84If you use translations in gettext mode, reload your web server.
85
75### Migrating and upgrading from Sebsauvage's repository 86### Migrating and upgrading from Sebsauvage's repository
76 87
77If 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. 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.
@@ -151,6 +162,14 @@ Updating dependencies
151 Downloading: 100% 162 Downloading: 100%
152``` 163```
153 164
165Shaarli >= `v0.9.2` supports translations:
166
167```bash
168$ make translate
169```
170
171If you use translations in gettext mode, reload your web server.
172
154Optionally, you can delete information related to the legacy version: 173Optionally, you can delete information related to the legacy version:
155 174
156```bash 175```bash
diff --git a/doc/md/docker/reverse-proxy-configuration.md b/doc/md/docker/reverse-proxy-configuration.md
index 91ffecff..6066140e 100644
--- a/doc/md/docker/reverse-proxy-configuration.md
+++ b/doc/md/docker/reverse-proxy-configuration.md
@@ -1,6 +1,120 @@
1## Foreword
2
3This guide assumes that:
4
5- Shaarli runs in a Docker container
6- The host's `10080` port is mapped to the container's `80` port
7- Shaarli's Fully Qualified Domain Name (FQDN) is `shaarli.domain.tld`
8- HTTP traffic is redirected to HTTPS
9
10## Apache
11
12- [Apache 2.4 documentation](https://httpd.apache.org/docs/2.4/)
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)
15
16The following HTTP headers are set by using the `ProxyPass` directive:
17
18- `X-Forwarded-For`
19- `X-Forwarded-Host`
20- `X-Forwarded-Server`
21
22```apache
23<VirtualHost *:80>
24 ServerName shaarli.domain.tld
25 Redirect permanent / https://shaarli.domain.tld
26</VirtualHost>
27
28<VirtualHost *:443>
29 ServerName shaarli.domain.tld
30
31 SSLEngine on
32 SSLCertificateFile /path/to/cert
33 SSLCertificateKeyFile /path/to/certkey
34
35 LogLevel warn
36 ErrorLog /var/log/apache2/shaarli-error.log
37 CustomLog /var/log/apache2/shaarli-access.log combined
38
39 RequestHeader set X-Forwarded-Proto "https"
40
41 ProxyPass / http://127.0.0.1:10080/
42 ProxyPassReverse / http://127.0.0.1:10080/
43</VirtualHost>
44```
1 45
2TODO, see https://github.com/shaarli/Shaarli/issues/888
3 46
4## HAProxy 47## HAProxy
5 48
49- [HAProxy documentation](https://cbonte.github.io/haproxy-dconv/)
50
51```conf
52global
53 [...]
54
55defaults
56 [...]
57
58frontend http-in
59 bind :80
60 redirect scheme https code 301 if !{ ssl_fc }
61
62 bind :443 ssl crt /path/to/cert.pem
63
64 default_backend shaarli
65
66
67backend shaarli
68 mode http
69 option http-server-close
70 option forwardfor
71 reqadd X-Forwarded-Proto: https
72
73 server shaarli1 127.0.0.1:10080
74```
75
76
6## Nginx 77## Nginx
78
79- [Nginx documentation](https://nginx.org/en/docs/)
80
81```nginx
82http {
83 [...]
84
85 index index.html index.php;
86
87 root /home/john/web;
88 access_log /var/log/nginx/access.log;
89 error_log /var/log/nginx/error.log;
90
91 server {
92 listen 80;
93 server_name shaarli.domain.tld;
94 return 301 https://shaarli.domain.tld$request_uri;
95 }
96
97 server {
98 listen 443 ssl http2;
99 server_name shaarli.domain.tld;
100
101 ssl_certificate /path/to/cert
102 ssl_certificate_key /path/to/certkey
103
104 location / {
105 proxy_set_header X-Real-IP $remote_addr;
106 proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
107 proxy_set_header X-Forwarded-Proto $scheme;
108 proxy_set_header X-Forwarded-Host $host;
109
110 proxy_pass http://localhost:10080/;
111 proxy_set_header Host $host;
112 proxy_connect_timeout 30s;
113 proxy_read_timeout 120s;
114
115 access_log /var/log/nginx/shaarli.access.log;
116 error_log /var/log/nginx/shaarli.error.log;
117 }
118 }
119}
120```
diff --git a/doc/md/docker/shaarli-images.md b/doc/md/docker/shaarli-images.md
index 6d108d21..5491ee76 100644
--- a/doc/md/docker/shaarli-images.md
+++ b/doc/md/docker/shaarli-images.md
@@ -1,3 +1,6 @@
1A brief guide on getting starting using docker is given in [Docker 101](docker-101.md).
2To learn more about user data and how to keep it across versions, please see [Upgrade and Migration](../Upgrade-and-migration.md).
3
1## Get and run a Shaarli image 4## Get and run a Shaarli image
2 5
3### DockerHub repository 6### DockerHub repository
@@ -5,14 +8,23 @@ The images can be found in the [`shaarli/shaarli`](https://hub.docker.com/r/shaa
5repository. 8repository.
6 9
7### Available image tags 10### Available image tags
8- `latest`: master branch (tarball release) 11- `latest`: latest branch (tarball release)
12- `master`: master branch (tarball release)
9- `stable`: stable branch (tarball release) 13- `stable`: stable branch (tarball release)
10 14
11All images rely on: 15The `latest` and `master` images rely on:
16
17- [Alpine Linux](https://www.alpinelinux.org/)
18- [PHP7-FPM](http://php-fpm.org/)
19- [Nginx](http://nginx.org/)
20
21The `stable` image relies on:
22
12- [Debian 8 Jessie](https://hub.docker.com/_/debian/) 23- [Debian 8 Jessie](https://hub.docker.com/_/debian/)
13- [PHP5-FPM](http://php-fpm.org/) 24- [PHP5-FPM](http://php-fpm.org/)
14- [Nginx](http://nginx.org/) 25- [Nginx](http://nginx.org/)
15 26
27
16### Download from DockerHub 28### Download from DockerHub
17```bash 29```bash
18$ docker pull shaarli/shaarli 30$ docker pull shaarli/shaarli
@@ -69,3 +81,14 @@ backstabbing_galileo
69$ docker ps -a 81$ docker ps -a
70CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES 82CONTAINER ID IMAGE COMMAND CREATED STATUS PORTS NAMES
71``` 83```
84
85### Automatic builds
86
87Docker 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):
88```
89MY_SHAARLI_VOLUME=$(cd /path/to/shaarli/data/ && pwd -P)
90docker run -ti --rm \
91 -p 8000:80 \
92 -v $MY_SHAARLI_VOLUME:/var/www/shaarli/data \
93 shaarli/shaarli
94```
diff --git a/doc/md/images/install-shaarli.png b/doc/md/images/install-shaarli.png
new file mode 100644
index 00000000..7ae33816
--- /dev/null
+++ b/doc/md/images/install-shaarli.png
Binary files differ
diff --git a/doc/md/images/poedit-1.jpg b/doc/md/images/poedit-1.jpg
new file mode 100644
index 00000000..673ae6d6
--- /dev/null
+++ b/doc/md/images/poedit-1.jpg
Binary files differ
diff --git a/doc/md/index.md b/doc/md/index.md
index 2b7d0f00..e77b4d3a 100644
--- a/doc/md/index.md
+++ b/doc/md/index.md
@@ -22,20 +22,25 @@ It runs the latest development version of Shaarli and is updated/reset daily.
22 22
23Login: `demo`; Password: `demo` 23Login: `demo`; Password: `demo`
24 24
25Docker 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):
26```
27MY_SHAARLI_VOLUME=$(cd /path/to/shaarli/data/ && pwd -P)
28docker run -ti --rm \
29 -p 8000:80 \
30 -v $MY_SHAARLI_VOLUME:/var/www/shaarli/data \
31 shaarli/shaarli
32```
33
34A brief guide on getting starting using docker is given in [Docker 101](docker/docker-101).
35To learn more about user data and how to keep it across versions, please see [Upgrade and Migration](Upgrade-and-migration) documentation.
36
37## Features 25## Features
38 26
27Shaarli can be used:
28
29- to share, comment and save interesting links and news.
30- to bookmark useful/frequent personal links (as private links) and share them between computers.
31- as a minimal blog/microblog/writing platform (no character limit).
32- as a read-it-later list (for example items tagged `readlater`).
33- to draft and save articles/posts/ideas.
34- to keep code snippets.
35- to keep notes and documentation.
36- as a shared clipboard/notepad/pastebin between machines.
37- as a todo list.
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 track of ongoing discussions (for example items tagged `discussion`).
41- [to feed RSS aggregators](http://shaarli.chassegnouf.net/?9Efeiw) (planets) with specific tags.
42- to feed other social networks, blogs... using RSS feeds and external services (dlvr.it, ifttt.com ...).
43
39### Interface 44### Interface
40- minimalist design (simple is beautiful) 45- minimalist design (simple is beautiful)
41- FAST 46- FAST
@@ -89,14 +94,12 @@ Easily extensible by any client using the REST API exposed by Shaarli.
89 94
90See the [API documentation](http://shaarli.github.io/api-documentation/). 95See the [API documentation](http://shaarli.github.io/api-documentation/).
91 96
92### Other usages 97### Using Shaarli as a blog, notepad, pastebin...
93Though Shaarli is primarily a bookmarking application, it can serve other purposes 98- Go to your Shaarli setup and log in
94(see [Features](Features)): 99- Click the `Add Link` button
95 100- To share text only, do not enter any URL in the corresponding input field and click `Add Link`
96- micro-blogging 101- Pick a title and enter your article, or note, in the description field; add a few tags; optionally check `Private` then click `Save`
97- pastebin 102- VoilĂ ! Your article is now published (privately if you selected that option) and accessible using its permalink.
98- online notepad
99- snippet archive
100 103
101## About 104## About
102### Shaarli community fork 105### Shaarli community fork