chore: Move in deb, docker, rpm and script Update Modules fro…

…m `mender`

See:
* mendersoftware/mender#1693

The content for the README is taken from the following Mender Hub posts:
* https://hub.mender.io/t/deb-packages/326
* https://hub.mender.io/t/docker/324
* https://hub.mender.io/t/rpm-packages/494
* https://hub.mender.io/t/script/328

And changing:
* The URLs for the modules and the generators,
* Update the `mender-artifact read` output, and
* Minor wording details to align them.

Ticket: MEN-7672

Signed-off-by: Lluis Campos <[email protected]>

deb/README.md

@@ -0,0 +1,92 @@
+### Description
+
+The Deb Update Module updates software on the device using the native local package manager.
+
+A Mender Artifact containing one or more software packages is sent to the device, where the Update Module will call the package manager to install them in alphabetical order.
+
+### Specification
+
+|||
+| --- | --- |
+|Module name|deb|
+|Supports rollback|no|
+|Requires restart|no|
+|Artifact generation script|no|
+|Full operating system updater|no|
+|Source code|[Update Module](https://github.com/mendersoftware/mender-update-modules/tree/master/deb/module/deb)|
+|Maintainer|Community|
+
+## Prepare the device
+
+This section describes how to setup your target device, i.e. the device to be updated. This will also be referred to as the device environment.
+
+All commands outlined in this section should be run in the device environment.
+
+### Prerequisites
+
+This update module has the following prerequisites for the device environment:
+* [Install the Mender client](https://docs.mender.io/client-installation/install-with-debian-package), version 2.0 or later
+
+### Install the Update Module
+
+Download the latest version of this Update Module by running:
+
+    mkdir -p /usr/share/mender/modules/v3 && wget -P /usr/share/mender/modules/v3 https://raw.githubusercontent.com/mendersoftware/mender-update-modules/master/deb/module/deb
+
+## Prepare the development environment on your workstation
+
+This section describes how to set up your development environment on your workstation.
+
+All commands outlined in this section should be run in the development environment.
+
+### Prerequisites
+
+This Update Modules has the following prerequisites for the development environment:
+* [Install mender-artifact ](https://docs.mender.io/downloads), version 3.1.0 or later
+
+### Create Mender Artifacts
+
+The Artifact can be generated using the `mender-artifact` tool.
+
+Now generate a Mender Artifact using the following command:
+
+```bash
+ARTIFACT_NAME="my-update-1.0"
+DEVICE_TYPE="my-device-type"
+OUTPUT_PATH="my-update-1.0.mender"
+PACKAGES="my-package-1.deb my-package-2.deb"
+mender-artifact write module-image -T deb -n ${ARTIFACT_NAME} -t ${DEVICE_TYPE} -o ${OUTPUT_PATH} -f $(echo "$PACKAGES" | sed -e 's/ / -f /g')
+```
+
+* `ARTIFACT_NAME`  - The name of the Mender Artifact
+* `DEVICE_TYPE`  - The compatible device type of this Mender Artifact
+* `OUTPUT_PATH`  - The path where to place the output Mender Artifact. This should always have a  `.mender`  suffix
+* `PACKAGES` - List of all .deb packages to be contained in the Artifact.
+
+You can either deploy this Artifact in managed mode with the Mender server (upload it under Releases in the server UI) or by using the Mender client only in [Standalone deployments](https://docs.mender.io/artifact-creation/standalone-deployment).
+
+
+### Artifact technical details
+
+The Mender Artifact used by this Update Module has a payload with as many files as software packages we are contained in the Artifact.
+
+The Mender Artifact contents will look like:
+
+```bash
+Updates:
+  - Type: deb
+    Provides:
+      rootfs-image.deb.version: my-update-1.0
+    Depends: {}
+    Clears Provides: [rootfs-image.deb.*]
+    Metadata: {}
+    Files:
+      - checksum: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
+        modified: 2024-11-07 12:00:03 +0100 CET
+        name: my-package-1.deb
+        size: 0
+      - checksum: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
+        modified: 2024-11-07 12:00:03 +0100 CET
+        name: my-package-2.deb
+        size: 0
+```

deb/module/deb

@@ -0,0 +1,13 @@
+#!/bin/sh
+
+set -e
+
+STATE="$1"
+FILES="$2"
+
+case "$STATE" in
+    ArtifactInstall)
+        dpkg -i "$FILES"/files/*.deb
+        ;;
+esac
+exit 0

docker/README.md

@@ -0,0 +1,108 @@
+### Description
+
+The Docker Update Module handles the Docker images that shall be running in the device. A deployment with this module will stop all currently running Docker containers in the device, and start new containers with the provided list of Docker images in the Mender Artifact.
+
+In case of an unforeseen error during the process, the module will use the rollback mechanism of the Mender client to restore the previously running Docker containers.
+
+### Specification
+|||
+| --- | --- |
+|Module name|docker|
+|Supports rollback|yes|
+|Requires restart|no|
+|Artifact generation script|yes|
+|Full operating system updater|no|
+|Source code|[Update Module](https://github.com/mendersoftware/mender-update-modules/tree/master/docker/module/docker), [Artifact Generator](https://github.com/mendersoftware/mender-update-modules/tree/master/docker/module-artifact-gen/docker-artifact-gen)|
+|Maintainer|Community|
+
+## Prepare the device
+
+This section describes how to setup your target device, i.e. the device to be updated. This will also be referred to as the device environment.
+
+All commands outlined in this section should be run in the device environment.
+
+### Prerequisites
+
+This update module has the following prerequisites for the device environment:
+
+* [Install Docker Engine](https://docs.docker.com/engine/installation/linux/docker-ce/ubuntu/), version 17.03 or later.
+* A recent version of the JSON parser  `jq`  needs to be installed in the device. 
+* Ensure the device has a Bash Unix shell
+
+How to install these depends on which OS you are running.
+
+### Install the Update Module
+
+Download the latest version of this Update Module by running:
+
+    mkdir -p /usr/share/mender/modules/v3 && wget -P /usr/share/mender/modules/v3 https://raw.githubusercontent.com/mendersoftware/mender-update-modules/master/docker/module/docker
+
+## Prepare the development environment on your workstation
+
+This section describes how to set up your development environment on your workstation.
+
+All commands outlined in this section should be run in the development environment.
+
+### Prerequisites
+
+This Update Module has the following prerequisites for the development environment:
+
+* [Install mender-artifact ](https://docs.mender.io/downloads), version 3.1.0 or later
+
+### Artifact creation
+
+For convenience, an Artifact generator tool `docker-artifact-gen` is provided along the module. This tool will generate Mender Artifacts in the same format that the Update Module expects them.
+
+Download `docker-artifact-gen`, by running the following command:
+
+```bash
+wget https://raw.githubusercontent.com/mendersoftware/mender-update-modules/master/docker/module-artifact-gen/docker-artifact-gen
+```
+
+Make it executable:
+
+```bash
+chmod +x docker-artifact-gen
+```
+
+Now generate a Mender Artifact using the following command:
+
+```bash
+ARTIFACT_NAME="my-container-update-1.0"
+DEVICE_TYPE="my-device-type"
+OUTPUT_PATH=my-container-update-1.0.mender
+DOCKER_IMAGES="docker-image-1 docker-image2"
+./docker-artifact-gen -n ${ARTIFACT_NAME} -t ${DEVICE_TYPE} -o ${OUTPUT_PATH} ${DOCKER_IMAGES}
+```
+* `ARTIFACT_NAME`  - The name of the Mender Artifact
+* `DEVICE_TYPE`  - The compatible device type of this Mender Artifact
+* `OUTPUT_PATH`  - The path where to place the output Mender Artifact. This should always have a  `.mender`  suffix
+* `DOCKER_IMAGES` - The list of Docker images that we want the target to run. Each item can be any valid name for Docker to pull images from (tags or digests). For example debian, debian:jessie, debian:latest, debian:sha256@…, etc
+
+Note that the actual image id that will be added in the Artifact is the digest (sha256 hash) of the image, regardless of the tag used to pull it in. This will ensure that the device will pull the exact same version of each image than the generation tool used when preparing the Artifact.
+
+You can either deploy this Artifact in managed mode with the Mender server (upload it under Releases in the server UI) or by using the Mender client only in [Standalone deployments](https://docs.mender.io/artifact-creation/standalone-deployment).
+
+#### Artifact technical details
+
+The Mender Artifact used by this Update Module has no payload files. Instead it uses the `Metadata` field to list the Docker images, which will be downloaded by the device. This meta-data is composed by a single `containers` JSON key with the array of images digests to be installed in the update.
+
+As an example, the following update will install two specific versions of Docker images debian and ubuntu:
+
+```bash
+Updates:
+  - Type: docker
+    Provides:
+      rootfs-image.docker.version: my-container-update-1.0
+    Depends: {}
+    Clears Provides: [rootfs-image.docker.*]
+    Metadata:
+      {
+        "containers": [
+          "debian@sha256:e11072c1614c08bf88b543fcfe09d75a0426d90896408e926454e88078274fcb",
+          "ubuntu@sha256:99c35190e22d294cdace2783ac55effc69d32896daaa265f0bbedbcde4fbe3e5"
+        ],
+        "run_args": ""
+      }
+    Files: []
+```

docker/module-artifact-gen/docker-artifact-gen

@@ -0,0 +1,177 @@
+#!/bin/sh
+
+set -e
+
+show_help() {
+  cat << EOF
+
+Simple tool to generate Mender Artifact suitable for docker Update Module
+
+Usage: $0 [options] IMAGE [IMAGES...] [-- [options-for-mender-artifact] ]
+
+    Options: [ -n|artifact-name -t|--device-type --software-name --software-version --software-filesystem --run-args -o|--output_path -h|--help ]
+
+        --artifact-name       - Artifact name
+        --device-type         - Target device type identification (can be given more than once)
+        --software-name       - Name of the key to store the software version: rootfs-image.NAME.version,
+                                instead of rootfs-image.docker.version
+        --software-version    - Value for the software version, defaults to the name of the artifact
+        --software-filesystem - If specified, is used instead of rootfs-image
+        --run-args            - Command line args to add when running the container(s)
+        --output-path         - Path to output file. Default: docker-artifact.mender
+        --help                - Show help and exit
+        IMAGE [IMAGES...]     - Docker container images to add to the Artifact
+
+Anything after a '--' gets passed directly to the mender-artifact tool.
+
+EOF
+}
+
+show_help_and_exit_error() {
+  show_help
+  exit 1
+}
+
+check_dependency() {
+  if ! which "$1" > /dev/null; then
+    echo "The $1 utility is not found but required to generate Artifacts." 1>&2
+    return 1
+  fi
+}
+
+if ! check_dependency mender-artifact; then
+  echo "Please follow the instructions here to install mender-artifact and then try again: https://docs.mender.io/downloads#mender-artifact" 1>&2
+  exit 1
+fi
+check_dependency docker
+check_dependency jq
+
+device_types=""
+artifact_name=""
+output_path="docker-artifact.mender"
+meta_data_file="meta-data.json"
+IMAGES=""
+passthrough_args=""
+
+while [ -n "$1" ]; do
+  case "$1" in
+    --device-type | -t)
+      if [ -z "$2" ]; then
+        show_help_and_exit_error
+      fi
+      device_types="$device_types $1 $2"
+      shift 2
+      ;;
+    --artifact-name | -n)
+      if [ -z "$2" ]; then
+        show_help_and_exit_error
+      fi
+      artifact_name=$2
+      shift 2
+      ;;
+    --software-name | --software-version | --software-filesystem)
+      if [ -z "$2" ]; then
+        show_help_and_exit_error
+      fi
+      passthrough_args="$passthrough_args $1 $2"
+      shift 2
+      ;;
+    --run-args)
+      if [ -z "$2" ]; then
+        show_help_and_exit_error
+      fi
+      run_args=$2
+      shift 2
+      ;;
+    --output-path | -o)
+      if [ -z "$2" ]; then
+        show_help_and_exit_error
+      fi
+      output_path=$2
+      shift 2
+      ;;
+    -h | --help)
+      show_help
+      exit 0
+      ;;
+    --)
+      shift
+      passthrough_args="$passthrough_args $@"
+      break
+      ;;
+    -*)
+      echo "Error: unsupported option $1"
+      show_help_and_exit_error
+      ;;
+    *)
+      IMAGES="$IMAGES $1"
+      shift
+      ;;
+  esac
+done
+
+if [ -z "${artifact_name}" ]; then
+  echo "Artifact name not specified. Aborting."
+  show_help_and_exit_error
+fi
+
+if [ -z "${device_types}" ]; then
+  echo "Device type not specified. Aborting."
+  show_help_and_exit_error
+fi
+
+if [ -z "${IMAGES}" ]; then
+  echo "At least one Docker image must be specified. Aborting."
+  show_help_and_exit_error
+fi
+
+HASHES=""
+for image in $IMAGES; do
+    docker pull $image
+    HASHES="$HASHES\"$(docker inspect --format='{{index .RepoDigests 0}}' $image)\" "
+done
+HASHES=$(echo $HASHES | tr ' ' ',')
+
+eval "jq -n --argjson c '[$HASHES]' '{\"containers\": \$c, \"run_args\": \"${run_args}\"}'" > $meta_data_file
+
+# Check the the passthrough_args and potentially modify them
+# to avoid conflicts or to let them override the already args
+# provided to mender-artifact
+# # Runs in a subshell to allow overriding some parameters passed
+# to mender-artifact
+passthrough_args_modified=" "
+echo -n $passthrough_args | xargs -n 2 printf "%s %s\n" | (while read -r flag arg; do
+  if [ -n "$flag" ] && [ -n "$arg" ]; then
+    case $flag in
+      -T | --type | -m | --meta-data)
+        echo "Error: Conflicting flag '$flag'. Already specified by the script."
+        exit 1
+        ;;
+      -o | --output-path)
+        output_path=$arg
+        ;;
+      -n | --name)
+        artifact_name=$arg
+        ;;
+      *)
+        passthrough_args_modified="$passthrough_args_modified $flag $arg"
+        ;;
+    esac
+  fi
+done
+
+mender-artifact write module-image \
+  -T docker \
+  $device_types \
+  -o $output_path \
+  -n $artifact_name \
+  -m $meta_data_file \
+  $passthrough_args_modified
+
+
+echo "Artifact $output_path generated successfully:"
+mender-artifact read $output_path
+# End of subshell
+)
+rm $meta_data_file
+exit 0