doc: refactor/simplify docker documentation

doc/md/Docker.md

@@ -1,39 +1,19 @@
 
 # Docker
 
-[Docker](https://docs.docker.com/get-started/overview/) is an open platform for developing, shipping, and running applications
+[Docker](https://docs.docker.com/get-started/overview/) is an open platform for developing, shipping, and running applications in lightweight containers.
 
 ## Install Docker
 
-Install [Docker](https://docs.docker.com/engine/install/), by following the instructions relevant to your OS / distribution, and start the service. For example on [Debian](https://docs.docker.com/engine/install/debian/):
+Install [Docker](https://docs.docker.com/engine/install/), by following the instructions relevant to your OS / distribution, and start the service.
 
-```bash
-# update your package lists
-sudo apt update
-# remove old versions
-sudo apt-get remove docker docker-engine docker.io containerd runc
-# install requirements
-sudo apt-get install apt-transport-https ca-certificates curl gnupg-agent software-properties-common
-# add docker's GPG signing key
-curl -fsSL https://download.docker.com/linux/debian/gpg | sudo apt-key add -
-# add the repository
-sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/debian $(lsb_release -cs) stable"
-# install docker engine
-sudo apt-get update
-sudo apt-get install docker-ce docker-ce-cli containerd.io
-# Start and enable Docker service
-sudo systemctl enable docker && sudo systemctl start docker
-# verify that Docker is properly configured
-sudo docker run hello-world
-```
-
-In order to run Docker commands as a non-root user, you must add the `docker` group to this user:
+_Optional:_ In order to run Docker commands as a non-root user (i.e. without `sudo`), you must add your user account to the `docker` group. Keep in mind that this effectively gives this user account [full root privileges](https://docs.docker.com/engine/security/#docker-daemon-attack-surface), without password.
 
 ```bash
-# Add docker group as secondary group
+# add your user to the docker group
 sudo usermod -aG docker your-user
-# Reboot or logout
-# Then verify that Docker is properly configured, as "your-user"
+# reboot or logout
+# then verify that Docker is properly configured, as "your-user"
 docker run hello-world
 ```
 
@@ -48,20 +28,25 @@ Shaarli images are available on [GitHub Container Registry](https://github.com/s
 These images are built automatically on Github Actions and rely on:
 
 - [Alpine Linux](https://www.alpinelinux.org/)
-- [PHP7-FPM](https://php-fpm.org/)
+- [PHP-FPM](https://php-fpm.org/)
 - [Nginx](https://nginx.org/)
 
+These images are suitable for the `amd64`, `arm/v7` and `arm64` CPU architectures.
+
+```{note}
 Additional Dockerfiles 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://blog.balena.io/building-arm-containers-on-any-x86-machine-even-dockerhub/).
+```
 
-Here is an example of how to run Shaarli latest image using Docker:
+To run the `latest` Shaarli image using Docker:
 
 ```bash
 # download the 'latest' image from GitHub Container Registry
-docker pull ghcr.io/shaarli/shaarli
+docker pull ghcr.io/shaarli/shaarli:latest
 
-# create persistent data volumes/directories on the host
-docker volume create shaarli-data
-docker volume create shaarli-cache
+# create directories for persistent data/cache storage
+sudo mkdir /opt/shaarli
+sudo mkdir /opt/shaarli/data
+sudo mkdir /opt/shaarli/cache
 
 # create a new container using the Shaarli image
 # --detach: run the container in background
@@ -73,63 +58,57 @@ docker run --detach \
            --name myshaarli \
            --publish 8000:80 \
            --rm \
-           --volume shaarli-data:/var/www/shaarli/data \
-           --volume shaarli-cache:/var/www/shaarli/cache \
+           --volume /opt/shaarli/data:/var/www/shaarli/data \
+           --volume /opt/shaarli/cache:/var/www/shaarli/cache \
            ghcr.io/shaarli/shaarli:latest
 
 # verify that the container is running
 docker ps | grep myshaarli
+```
 
-# to completely remove the container
-docker stop myshaarli # stop the running container
-docker ps | grep myshaarli # verify the container is no longer running
-docker ps -a | grep myshaarli # verify the container is stopped
-docker rm myshaarli # destroy the container
-docker ps -a | grep myshaarli # verify th container has been destroyed
+Your Shaarli instance should be available on the host machine at [http://localhost:8000](http://localhost:8000). In order to access your instance through a reverse proxy, we recommend using our [Docker Compose](#docker-compose) build.
 
-```
+Stopping the container will also completely remove it (but not persistent volumes) since it was started with `--rm`:
 
-After running `docker run` command, your Shaarli instance should be available on the host machine at [localhost:8000](http://localhost:8000). In order to access your instance through a reverse proxy, we recommend using our [Docker Compose](#docker-compose) build.
+```bash
+docker stop myshaarli # stop the running container
+docker ps -a | grep myshaarli # verify the container has been destroyed
+```
 
 ## Docker Compose
 
 A [Compose file](https://docs.docker.com/compose/compose-file/) is a common format for defining and running multi-container Docker applications.
 
-A `docker-compose.yml` file can be used to run a persistent/autostarted shaarli service using [Docker Compose](https://docs.docker.com/compose/) or in a [Docker stack](https://docs.docker.com/engine/reference/commandline/stack_deploy/).
-
-Shaarli provides configuration file for Docker Compose, that will setup a Shaarli instance, a [Træfik](https://traefik.io/traefik/) instance (reverse proxy) with [Let's Encrypt](https://letsencrypt.org/) certificates, a Docker network, and volumes for Shaarli data and Træfik TLS configuration and certificates.
-
-Download docker-compose from the [release page](https://docs.docker.com/compose/install/):
-
-```bash
-$ sudo curl -L "https://github.com/docker/compose/releases/download/1.26.2/docker-compose-$(uname -s)-$(uname -m)" -o /usr/local/bin/docker-compose
-$ sudo chmod +x /usr/local/bin/docker-compose
-```
+Shaarli provides a `docker-compose.yml` file which can be used to run a persistent/autostarted shaarli service using [Docker Compose](https://docs.docker.com/compose/) or in a [Docker stack](https://docs.docker.com/engine/reference/commandline/stack_deploy/). It sets up a Shaarli instance, a [Træfik](https://traefik.io/traefik/) reverse proxy instance with [Let's Encrypt](https://letsencrypt.org/) certificates, a Docker network, and volumes for Shaarli data and Træfik TLS configuration and certificates.
 
-To run Shaarli container and its reverse proxy, you can execute the following commands:
+* Download docker-compose from the [release page](https://docs.docker.com/compose/install/).
+* Run the following commands to start Shaarli and its reverse proxy:
 
 ```bash
-# create a new directory to store the configuration:
-$ mkdir shaarli && cd shaarli
-# Download the latest version of Shaarli's docker-compose.yml
+# create a new directory to store your configuration and data
+$ sudo mkdir /opt/shaarli
+$ sudo mkdir /opt/shaarli/data
+$ cd /opt/shaarli
+# download the latest version of Shaarli's docker-compose.yml
 $ curl -L https://raw.githubusercontent.com/shaarli/Shaarli/latest/docker-compose.yml -o docker-compose.yml
-# Create the .env file and fill in your VPS and domain information
+# create the .env file and fill in your VPS and domain information
 # (replace <shaarli.mydomain.org>, <admin@mydomain.org> and <latest> with your actual information)
-$ echo 'SHAARLI_VIRTUAL_HOST=shaarli.mydomain.org' > .env
-$ echo 'SHAARLI_LETSENCRYPT_EMAIL=admin@mydomain.org' >> .env
-# Available Docker tags can be found at https://github.com/shaarli/Shaarli/pkgs/container/shaarli/versions?filters%5Bversion_type%5D=tagged
-$ echo 'SHAARLI_DOCKER_TAG=latest' >> .env
-# Pull the Docker images
+# available Docker tags can be found at https://github.com/shaarli/Shaarli/pkgs/container/shaarli/versions?filters%5Bversion_type%5D=tagged
+$ echo 'SHAARLI_VIRTUAL_HOST=shaarli.mydomain.org' | sudo tee .env
+$ echo 'SHAARLI_LETSENCRYPT_EMAIL=admin@mydomain.org' | sudo tee -a .env
+$ echo 'SHAARLI_DOCKER_TAG=latest' | sudo tee -a .env
+# pull the required images
 $ docker-compose pull
-# Run!
+# run!
 $ docker-compose up -d
 ```
 
-After a few seconds, you should be able to access your Shaarli instance at [https://shaarli.mydomain.org](https://shaarli.mydomain.org) (replace your own domain name).
+After a few seconds, you should be able to access your Shaarli instance at [https://shaarli.mydomain.org](https://shaarli.mydomain.org).
+
 
 ## Running dockerized Shaarli as a systemd service
 
-It is possible to start a dockerized Shaarli instance as a systemd service (systemd is the service management tool on several distributions). After installing Docker, use the following steps to run your shaarli container Shaarli to run on system start.
+It is possible to start a dockerized Shaarli instance as a systemd service (systemd is the service management tool on several distributions), that will start automatically on system boot:
 
 As root, create `/etc/systemd/system/docker.shaarli.service`:
 
@@ -139,19 +118,18 @@ 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
+EnvironmentFile=/opt/shaarli/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 /opt/shaarli/data:/var/www/shaarli/data:rw \
   -v /etc/localtime:/etc/localtime:ro \
   ghcr.io/shaarli/shaarli:latest
 
@@ -162,18 +140,16 @@ WantedBy=multi-user.target
 ```
 
 ```bash
-# reload systemd services definitions
+# reload systemd service definitions
 systemctl daemon-reload
-# start the servie and enable it a boot time
+# start the service and enable it a boot time
 systemctl enable docker.shaarli.service --now
 # verify that the service is running
 systemctl status docker.*
 # inspect system log if needed
 journalctl -f
 ```
 
-
-
 ## Docker cheatsheet
 
 ```bash

doc/md/REST-API.md

@@ -80,7 +80,7 @@ var_dump(getInfo($baseUrl, $secret));
 [header].[payload].[signature]
 ```
 
-##### Header
+#### Header
 
 Shaarli only allow one hash algorithm, so the header will always be the same:
 
@@ -97,7 +97,7 @@ Encoded in base64, it gives:
 ewogICAgICAgICJ0eXAiOiAiSldUIiwKICAgICAgICAiYWxnIjogIkhTNTEyIgogICAgfQ==
 ```
 
-##### Payload
+#### Payload
 
 Token expiration: To avoid infinite token validity, JWT tokens must include their creation date in UNIX timestamp format (timezone independent - UTC) under the key `iat` (issued at) field ([1](https://datatracker.ietf.org/doc/html/rfc7519)). This token will be valid during **9 minutes**.
 
@@ -107,7 +107,7 @@ Token expiration: To avoid infinite token validity, JWT tokens must include thei
 }
 ```
 
-##### Signature
+#### Signature
 
 The signature authenticates the token validity. It contains the base64 of the header and the body, separated by a dot `.`, hashed in SHA512 with the API secret available in Shaarli administration page.
 
@@ -119,7 +119,6 @@ $signature = hash_hmac('sha512', $content, $secret);
 ```
 
 
-
 ## Troubleshooting
 
 ### Debug mode