12 files changed, 485 insertions, 11 deletions

diff --git a/doc/md/Download-and-Installation.md b/doc/md/Download-and-Installation.md
index e5e929ef..be848c97 100644
--- a/doc/md/Download-and-Installation.md
+++ b/doc/md/Download-and-Installation.md
@@ -4,11 +4,18 @@ Document Root (or directly at the document root).
 Also, please make sure your server meets the [requirements](Server-requirements)
 and is properly [configured](Server-configuration).
 
-Several releases are available:
+Multiple releases branches are available:
+
+- latest (last release)
+- stable (previous major release)
+- master (development)
+
+Using one of the following methods:
 
 - by downloading full release archives including all dependencies
 - by downloading Github archives
 - by cloning the Git repository
+- using Docker: [see the documentation](docker/shaarli-images)
 
 ---
 
@@ -28,14 +35,16 @@ $ unzip shaarli-v0.9.1-full.zip
 $ mv Shaarli /path/to/shaarli/
 ```
 
-In 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).|
+In 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).
 
 ### Using git
 
 ```
 $ mkdir -p /path/to/shaarli && cd /path/to/shaarli/
-$ git clone -b v0.9 https://github.com/shaarli/Shaarli.git .
+$ git clone -b latest https://github.com/shaarli/Shaarli.git .
 $ composer install --no-dev --prefer-dist
+$ make translate
 ```
 
 ## Stable version
@@ -83,13 +92,14 @@ $ git clone https://github.com/shaarli/Shaarli.git -b master /path/to/shaarli/
 # install/update third-party dependencies
 $ cd /path/to/shaarli
 $ composer install --no-dev --prefer-dist
+$ make translate
 ```
 
 ## Finish Installation
 
 Once Shaarli is downloaded and files have been placed at the correct location, open it this location your favorite browser.
 
-![install screenshot](http://i.imgur.com/wuMpDSN.png)
+![install screenshot](images/install-shaarli.png)
 
 Setup your Shaarli installation, and it's ready to use!
 
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
 [`php-gd`](http://php.net/manual/en/book.image.php) | optional | thumbnail resizing
 [`php-intl`](http://php.net/manual/en/book.intl.php) | optional | localized text sorting (e.g. `e->è->f`)
 [`php-curl`](http://php.net/manual/en/book.curl.php) | optional | using cURL for fetching webpages and thumbnails in a more robust way
+[`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 d90e95eb..920c7e27 100644
--- a/doc/md/Shaarli-configuration.md
+++ b/doc/md/Shaarli-configuration.md
@@ -55,6 +55,7 @@ _These settings should not be edited_
 - **links_per_page**: Number of shaares displayed per page.  
 - **timezone**: See [the list of supported timezones](http://php.net/manual/en/timezones.php).  
 - **enabled_plugins**: List of enabled plugins.
+- **default_note_title**: Default title of a new note.
 
 ### Security
 
@@ -80,6 +81,20 @@ _These settings should not be edited_
 - **page_cache**: Shaarli's internal cache directory.  
 - **ban_file**: Banned IP file path.
 
+### Translation
+
+- **language**: translation language (also see [Translations](Translations))
+    - **auto** (default): The translation language is chosen from the browser locale. 
+    It means that the language can be different for 2 different visitors depending on their locale.  
+    - **en**: Use the English translation.
+    - **fr**: Use the French translation.
+- **mode**: 
+    - **auto** or **php** (default): Use the PHP implementation of gettext (slower)
+    - **gettext**: Use PHP builtin gettext extension 
+    (faster, but requires `php-gettext` to be installed and to reload the web server on update)
+- **extension**: Translation extensions for custom themes or plugins. 
+Must be an associative array: `translation domain => translation path`.
+
 ### Updates
 
 - **check_updates**: Enable or disable update check to the git repository.  
@@ -90,6 +105,7 @@ _These settings should not be edited_
 
 - **default_private_links**: Check the private checkbox by default for every new link.  
 - **hide_public_links**: All links are hidden while logged out.  
+- **force_login**: if **hide_public_links** and this are set to `true`, all anonymous users are redirected to the login page.
 - **hide_timestamps**: Timestamps are hidden.
 - **remember_user_default**: Default state of the login page's *remember me* checkbox
     - `true`: checked by default, `false`: unchecked by default
@@ -194,6 +210,7 @@ _These settings should not be edited_
     "privacy": {
         "default_private_links": true,
         "hide_public_links": false,
+        "force_login": false,
         "hide_timestamps": false,
         "remember_user_default": true
     },
@@ -208,6 +225,13 @@ _These settings should not be edited_
     "plugins": {
         "WALLABAG_URL": "http://demo.wallabag.org",
         "WALLABAG_VERSION": "1"
+    },
+    "translation": {
+        "language": "fr",
+        "mode": "php",
+        "extensions": {
+            "demo": "plugins/demo_plugin/languages/"
+        }
     }
 } ?>
 ```
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 @@
+## Translations
+
+Shaarli supports [gettext](https://www.gnu.org/software/gettext/manual/gettext.html) translations
+since `>= v0.9.2`.
+
+Note that only the `default` theme supports translations.
+
+### Contributing
+
+We encourage the community to contribute to Shaarli's translation either by improving existing 
+translations or submitting a new language. 
+
+Contributing to the translation does not require development skill.
+
+Please submit a pull request with the `.po` file updated/created. Note that the compiled file (`.mo`)
+is not stored on the repository, and is generated during the release process.
+
+### How to
+
+First, install [Poedit](https://poedit.net/) tool.
+
+Poedit will extract strings to translate from the PHP source code.
+
+**Important**: due to the usage of a template engine, it's important to generate PHP cache files to extract 
+every translatable string. 
+
+You can either use [this script](https://gist.github.com/ArthurHoaro/5d0323f758ab2401ef444a53f54e9a07)  (recommended)
+or visit every template page in your browser to generate cache files, while logged in.
+
+Here is a list :
+
+```
+http://<replace_domain>/
+http://<replace_domain>/?nonope
+http://<replace_domain>/?do=addlink
+http://<replace_domain>/?do=changepasswd
+http://<replace_domain>/?do=changetag
+http://<replace_domain>/?do=configure
+http://<replace_domain>/?do=tools
+http://<replace_domain>/?do=daily
+http://<replace_domain>/?post
+http://<replace_domain>/?do=export
+http://<replace_domain>/?do=import
+http://<replace_domain>/?do=login
+http://<replace_domain>/?do=picwall
+http://<replace_domain>/?do=pluginadmin
+http://<replace_domain>/?do=tagcloud
+http://<replace_domain>/?do=taglist
+```
+
+#### Improve existing translation
+
+In Poedit, click on "Edit a Translation", and from Shaarli's directory open 
+`inc/languages/<lang>/LC_MESSAGES/shaarli.po`. 
+
+The existing list of translatable strings should have been loaded, then click on the "Update" button.
+
+You can start editing the translation.
+
+![poedit-screenshot](images/poedit-1.jpg)
+
+Save when you're done, then you can submit a pull request containing the updated `shaarli.po`.
+
+#### Add a new language
+
+Open Poedit and select "Create New Translation", then from Shaarli's directory open 
+`inc/languages/<lang>/LC_MESSAGES/shaarli.po`.
+
+Then select the language you want to create. 
+
+Click on `File > Save as...`, and save your file in `<shaarli directory>/inc/language/<new language>/LC_MESSAGES/shaarli.po`.  
+`<new language>` here should be the language code respecting the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-2) 
+format in lowercase (e.g. `de` for German).
+
+Then click on the "Update" button, and you can start to translate every available string.
+
+Save when you're done, then you can submit a pull request containing the new `shaarli.po`.
+
+### Extend Shaarli's translation
+
+If you're writing a custom theme, or a non official plugin, you might want to use the translation system,
+but you won't be able to able to override Shaarli's translation.
+
+However, you can add your own translation domain which extends the main translation list.
+
+> Note that you can find a live example of translation extension in the `demo_plugin`.
+
+First, create your translation files tree directory:
+
+```
+<your_module>/languages/<ISO 3166-1 alpha-2 language code>/LC_MESSAGES/
+```
+
+Your `.po` files must be named like your domain. E.g. if your translation domain is `my_theme`, then your file will be
+`my_theme.po`.
+
+Users have to register your extension in their configuration with the parameter 
+`translation.extensions.<domain>: <translation files path>`.
+
+Example:
+
+```php
+if (! $conf->exists('translation.extensions.my_theme')) {
+    $conf->set('translation.extensions.my_theme', '<your_module>/languages/');
+    $conf->write(true);
+}
+```
+
+> Note that the page needs to be reloaded after the registration.
+
+It is then recommended to create a custom translation function which will call the `t()` function with your domain.
+For example :
+
+```php
+function my_theme_t($text, $nText = '', $nb = 1)
+{
+    return t($text, $nText, $nb, 'my_theme'); // the last parameter is your translation domain.
+}
+```
+
+All strings which can be translated should be processed through your function:
+
+```php
+my_theme_t('Comment');
+my_theme_t('Comment', 'Comments', 2);
+```
+
+Or in templates:
+
+```php
+{'Comment'|my_theme_t}
+{function="my_theme_t('Comment', 'Comments', 2)"}
+```
+
+> Note than in template, you need to visit your page at least once to generate a cache file.
+
+When you're done, open Poedit and load translation strings from sources:
+
+  1. `File > New`
+  2. Choose your language
+  3. Save your `PO` file in `<your_module>/languages/<language code>/LC_MESSAGES/my_theme.po`.
+  4. Go to `Catalog > Properties...` 
+  5. Fill the `Translation Properties` tab
+  6. Add your source path in the `Sources Paths` tab
+  7. In the `Sources Keywords` tab uncheck "Also use default keywords" and add the following lines:
+  
+```
+my_theme_t
+my_theme_t:1,2
+```
+
+Click on the "Update" button and you're free to start your translations!
diff --git a/doc/md/Unit-tests-Docker.md b/doc/md/Unit-tests-Docker.md
new file mode 100644
index 00000000..c2de7cc7
--- /dev/null
+++ b/doc/md/Unit-tests-Docker.md
@@ -0,0 +1,56 @@
+## Running tests inside Docker containers
+
+Read first:
+
+- [Docker 101](docker/docker-101.md)
+- [Docker resources](docker/resources.md)
+- [Unit tests](Unit-tests.md)
+
+### Docker test images
+
+Test Dockerfiles are located under `docker/tests/<distribution>/Dockerfile`,
+and can be used to build Docker images to run Shaarli test suites under common
+Linux environments.
+
+Dockerfiles are provided for the following environments:
+
+- `alpine36` - [Alpine 3.6](https://www.alpinelinux.org/downloads/)
+- `debian8` - [Debian 8 Jessie](https://www.debian.org/DebianJessie) (oldstable)
+- `debian9` - [Debian 9 Stretch](https://wiki.debian.org/DebianStretch) (stable)
+- `ubuntu16` - [Ubuntu 16.04 Xenial Xerus](http://releases.ubuntu.com/16.04/) (LTS)
+
+What's behind the curtains:
+
+- each image provides:
+    - a base Linux OS
+    - Shaarli PHP dependencies (OS packages)
+    - test PHP dependencies (OS packages)
+    - Composer
+- the local workspace is mapped to the container's `/shaarli/` directory,
+- the files are rsync'd to so tests are run using a standard Linux user account
+  (running tests as `root` would bypass permission checks and may hide issues)
+- the tests are run inside the container.
+
+### Building test images
+
+```bash
+# build the Debian 9 Docker image
+$ cd /path/to/shaarli
+$ cd docker/test/debian9
+$ docker build -t shaarli-test:debian9 .
+```
+
+### Running tests
+
+```bash
+$ cd /path/to/shaarli
+
+# install/update 3rd-party test dependencies
+$ composer install --prefer-dist
+
+# run tests using the freshly built image
+$ docker run -v $PWD:/shaarli shaarli-test:debian9 docker_test
+
+# run the full test campaign
+$ docker run -v $PWD:/shaarli shaarli-test:debian9 docker_all_tests
+```
diff --git a/doc/md/Upgrade-and-migration.md b/doc/md/Upgrade-and-migration.md
index b3a08764..1dc07339 100644
--- a/doc/md/Upgrade-and-migration.md
+++ b/doc/md/Upgrade-and-migration.md
@@ -14,7 +14,7 @@ Shaarli stores all user data under the `data` directory:
 - `data/ipbans.php` - banned IP addresses
 - `data/updates.txt` - contains all automatic update to the configuration and datastore files already run
 
-See [Shaarli configuration](Shaarli configuration) for more information about Shaarli resources.
+See [Shaarli configuration](Shaarli-configuration) for more information about Shaarli resources.
 
 It is recommended to backup this repository _before_ starting updating/upgrading Shaarli:
 
@@ -27,7 +27,7 @@ As all user data is kept under `data`, this is the only directory you need to wo
 
 - backup the `data` directory
 - install or update Shaarli:
-    - fresh installation - see [Download and installation](Download and installation)
+    - fresh installation - see [Download and installation](Download-and-installation)
     - update - see the following sections
 - check or restore the `data` directory
 
@@ -35,10 +35,13 @@ As all user data is kept under `data`, this is the only directory you need to wo
 
 All tagged revisions can be downloaded as tarballs or ZIP archives from the [releases](https://github.com/shaarli/Shaarli/releases) page.
 
-We 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.
+We 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.
 
 Once downloaded, extract the archive locally and update your remote installation (e.g. via FTP) -be sure you keep the content of the `data` directory!
 
+If you use translations in gettext mode - meaning you manually changed the default mode -, 
+reload your web server.
+
 After 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).
 
 ## Upgrading with Git
@@ -72,6 +75,14 @@ Updating dependencies
     Downloading: 100%
 ```
 
+Shaarli >= `v0.9.2` supports translations:
+
+```bash
+$ make translate
+```
+
+If you use translations in gettext mode, reload your web server.
+
 ### Migrating and upgrading from Sebsauvage's repository
 
 If 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
     Downloading: 100%
 ```
 
+Shaarli >= `v0.9.2` supports translations:
+
+```bash
+$ make translate
+```
+
+If you use translations in gettext mode, reload your web server.
+
 Optionally, you can delete information related to the legacy version:
 
 ```bash
@@ -173,7 +192,7 @@ Total 3317 (delta 2050), reused 3301 (delta 2034)to
 
 #### Step 3: configuration
 
-After 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).
+After 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).
 
 ## Troubleshooting
 
diff --git a/doc/md/docker/docker-101.md b/doc/md/docker/docker-101.md
index b02dd149..a9c00b85 100644
--- a/doc/md/docker/docker-101.md
+++ b/doc/md/docker/docker-101.md
@@ -60,3 +60,81 @@ wheezy: Pulling from debian
 Digest: sha256:c584131da2ac1948aa3e66468a4424b6aea2f33acba7cec0b631bdb56254c4fe
 Status: Downloaded newer image for debian:wheezy
 ```
+
+Docker re-uses layers already downloaded. In other words if you have images based on Alpine or some Ubuntu version for example, those can share disk space.
+
+### Start a container
+A container is an instance created from an image, that can be run and that keeps running until its main process exits. Or until the user stops the container. 
+
+The simplest way to start a container from image is ``docker run``. It also pulls the image for you if it is not locally available. For more advanced use, refer to ``docker create``.
+
+Stopped containers are not destroyed, unless you specify ``--rm``. To view all created, running and stopped containers, enter:
+```bash
+$ docker ps -a
+```
+
+Some containers may be designed or configured to be restarted, others are not. Also remember both network ports and volumes of a container are created on start, and not editable later.
+
+### Access a running container
+A running container is accessible using ``docker exec``, or ``docker copy``. You can use ``exec`` to start a root shell in the Shaarli container:
+```bash
+$ docker exec -ti <container-name-or-id> bash
+```
+Note the names and ID's of containers are listed in ``docker ps``. You can even type only one or two letters of the ID, given they are unique.
+
+Access can also be through one or more network ports, or disk volumes. Both are specified on and fixed on ``docker create`` or ``run``.
+
+You can view the console output of the main container process too:
+```bash
+$ docker logs -f <container-name-or-id>
+```
+
+### Docker disk use
+Trying out different images can fill some gigabytes of disk quickly. Besides images, the docker volumes usually take up most disk space.
+
+If you care only about trying out docker and not about what is running or saved, the following commands should help you out quickly if you run low on disk space:
+
+```bash
+$ docker rmi -f $(docker images -aq) # remove or mark all images for disposal
+$ docker volume rm $(docker volume ls -q) # remove all volumes
+```
+
+### Systemd config
+Systemd is the process manager of choice on Debian-based distributions. Once you have a ``docker`` service installed, you can use the following steps to set up Shaarli to run on system start.
+
+```bash
+systemctl enable /etc/systemd/system/docker.shaarli.service
+systemctl start docker.shaarli
+systemctl status docker.*
+journalctl -f # inspect system log if needed
+```
+
+You will need sudo or a root terminal to perform some or all of the steps above. Here are the contents for the service file:
+```
+[Unit]
+Description=Shaarli Bookmark Manager Container
+After=docker.service
+Requires=docker.service
+
+
+[Service]
+Restart=always
+
+# Put any environment you want in an included file, like $host- or $domainname in this example
+EnvironmentFile=/etc/sysconfig/box-environment
+
+# It's just an example..
+ExecStart=/usr/bin/docker run \
+  -p 28010:80 \
+  --name ${hostname}-shaarli \
+  --hostname shaarli.${domainname} \
+  -v /srv/docker-volumes-local/shaarli-data:/var/www/shaarli/data:rw \
+  -v /etc/localtime:/etc/localtime:ro \
+  shaarli/shaarli:latest
+
+ExecStop=/usr/bin/docker rm -f ${hostname}-shaarli
+
+
+[Install]
+WantedBy=multi-user.target
+```
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 @@
+## Foreword
+
+This guide assumes that:
+
+- Shaarli runs in a Docker container
+- The host's `10080` port is mapped to the container's `80` port
+- Shaarli's Fully Qualified Domain Name (FQDN) is `shaarli.domain.tld`
+- HTTP traffic is redirected to HTTPS
+
+## Apache
+
+- [Apache 2.4 documentation](https://httpd.apache.org/docs/2.4/)
+    - [mod_proxy](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html)
+    - [Reverse Proxy Request Headers](https://httpd.apache.org/docs/2.4/mod/mod_proxy.html#x-headers)
+
+The following HTTP headers are set by using the `ProxyPass` directive:
+
+- `X-Forwarded-For`
+- `X-Forwarded-Host`
+- `X-Forwarded-Server`
+
+```apache
+<VirtualHost *:80>
+    ServerName shaarli.domain.tld
+    Redirect permanent / https://shaarli.domain.tld
+</VirtualHost>
+
+<VirtualHost *:443>
+    ServerName shaarli.domain.tld
+
+    SSLEngine on
+    SSLCertificateFile    /path/to/cert
+    SSLCertificateKeyFile /path/to/certkey
+
+    LogLevel warn
+    ErrorLog  /var/log/apache2/shaarli-error.log
+    CustomLog /var/log/apache2/shaarli-access.log combined
+
+    RequestHeader set X-Forwarded-Proto "https"
+
+    ProxyPass        / http://127.0.0.1:10080/
+    ProxyPassReverse / http://127.0.0.1:10080/
+</VirtualHost>
+```
 
-TODO, see https://github.com/shaarli/Shaarli/issues/888
 
 ## HAProxy
 
+- [HAProxy documentation](https://cbonte.github.io/haproxy-dconv/)
+
+```conf
+global
+    [...]
+
+defaults
+    [...]
+
+frontend http-in
+    bind :80
+        redirect scheme https code 301 if !{ ssl_fc }
+
+        bind :443 ssl crt /path/to/cert.pem
+
+        default_backend shaarli
+
+
+backend shaarli
+    mode http
+    option http-server-close
+    option forwardfor
+    reqadd X-Forwarded-Proto: https
+
+    server shaarli1 127.0.0.1:10080
+```
+
+
 ## Nginx
+
+- [Nginx documentation](https://nginx.org/en/docs/)
+
+```nginx
+http {
+    [...]
+
+    index index.html index.php;
+
+    root        /home/john/web;
+    access_log  /var/log/nginx/access.log;
+    error_log   /var/log/nginx/error.log;
+
+        server {
+                listen       80;
+                server_name  shaarli.domain.tld;
+                return       301 https://shaarli.domain.tld$request_uri;
+        }
+
+        server {
+                listen       443 ssl http2;
+                server_name  shaarli.domain.tld;
+
+        ssl_certificate       /path/to/cert
+        ssl_certificate_key   /path/to/certkey
+
+                location / {
+                        proxy_set_header  X-Real-IP         $remote_addr;
+                        proxy_set_header  X-Forwarded-For   $proxy_add_x_forwarded_for;
+                        proxy_set_header  X-Forwarded-Proto $scheme;
+                        proxy_set_header  X-Forwarded-Host  $host;
+
+                        proxy_pass             http://localhost:10080/;
+                        proxy_set_header Host  $host;
+                        proxy_connect_timeout  30s;
+                        proxy_read_timeout     120s;
+
+                        access_log      /var/log/nginx/shaarli.access.log;
+                        error_log       /var/log/nginx/shaarli.error.log;
+                }
+        }
+}
+```
diff --git a/doc/md/docker/shaarli-images.md b/doc/md/docker/shaarli-images.md
index 6d108d21..1d19510a 100644
--- a/doc/md/docker/shaarli-images.md
+++ b/doc/md/docker/shaarli-images.md
@@ -5,14 +5,23 @@ The images can be found in the [`shaarli/shaarli`](https://hub.docker.com/r/shaa
 repository.
 
 ### Available image tags
-- `latest`: master branch (tarball release)
+- `latest`: latest branch (tarball release)
+- `master`: master branch (tarball release)
 - `stable`: stable branch (tarball release)
 
-All images rely on:
+The `latest` and `master` images rely on:
+
+- [Alpine Linux](https://www.alpinelinux.org/)
+- [PHP7-FPM](http://php-fpm.org/)
+- [Nginx](http://nginx.org/)
+
+The `stable` image relies on:
+
 - [Debian 8 Jessie](https://hub.docker.com/_/debian/)
 - [PHP5-FPM](http://php-fpm.org/)
 - [Nginx](http://nginx.org/)
 
+
 ### Download from DockerHub
 ```bash
 $ docker pull shaarli/shaarli
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
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
diff --git a/doc/md/index.md b/doc/md/index.md
index 24ada6c7..2b7d0f00 100644
--- a/doc/md/index.md
+++ b/doc/md/index.md
@@ -22,6 +22,17 @@ It runs the latest development version of Shaarli and is updated/reset daily.
 
 Login: `demo`; Password: `demo`
 
+Docker 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):
+```
+MY_SHAARLI_VOLUME=$(cd /path/to/shaarli/data/ && pwd -P)
+docker run -ti --rm \
+         -p 8000:80 \
+         -v $MY_SHAARLI_VOLUME:/var/www/shaarli/data \
+         shaarli/shaarli
+```
+
+A brief guide on getting starting using docker is given in [Docker 101](docker/docker-101).
+To learn more about user data and how to keep it across versions, please see [Upgrade and Migration](Upgrade-and-migration) documentation.
 
 ## Features