From 328f3af68b6cf7ba9f020ee213575fcea6718d94 Mon Sep 17 00:00:00 2001
From: Raphael Dannecker <raphael.dannecker@steinbeisschule-reutlingen.de>
Date: Wed, 8 Jul 2026 12:00:40 +0200
Subject: [PATCH] Add documentation about automatic client updater

---
 README.md       |  4 ++++
 doc/extrapkg.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++
 doc/updater.md  | 61 +++++++++++++++++++++++++++++++++++++++++++++++
 3 files changed, 128 insertions(+)
 create mode 100644 doc/extrapkg.md
 create mode 100644 doc/updater.md

diff --git a/README.md b/README.md
index 07ad798..8354b94 100644
--- a/README.md
+++ b/README.md
@@ -18,6 +18,8 @@ Ansible playbooks and roles to deploy Debian clients for LinuxMuster.
   Runs own ansible roles.
 * [exam_mode](doc/exam_mode.md)
   Starts local firewall and removes local directories of exam users the day after.
+* [extrapkg](doc/extrapkg.md)
+  Installs additional packages from stable or backports repositories.
 * [localhome](doc/localhome.md)
   Sometimes a local home directory makes more sense than the home on a network share.
 * [localproxy](doc/localproxy.md)
@@ -26,6 +28,8 @@ Ansible playbooks and roles to deploy Debian clients for LinuxMuster.
   Creates a local guest user with home on tmpfs.
 * [misc_clonescreen](doc/misc_clonescreen.md)
   CloneScreen on presenter PCs
+* [updater](doc/updater.md)
+  Changes in the Ansible playbook or inventory are applied automatically to all configured clients
 * [vm_support](doc/vm_support.md)
   VMs based on Qemu/KVM in school network.
 * [vpn](doc/vpn.md)
diff --git a/doc/extrapkg.md b/doc/extrapkg.md
new file mode 100644
index 0000000..e4766b7
--- /dev/null
+++ b/doc/extrapkg.md
@@ -0,0 +1,63 @@
+# Extra_pkg
+
+Installs additional packages from stable or backports repositories.
+
+## Configuration / Variables
+
+* **extra_pkg**  
+  List of packages from the stable repository to be installed.  
+  Type: **List of Strings**  
+  Default: `[]`
+
+* **extra_pkg1**  
+  List of packages from the stable repository to be installed.  
+  Type: **List of Strings**  
+  Default: `[]`
+
+* **extra_pkg2**  
+  List of packages from the stable repository to be installed.  
+  Type: **List of Strings**  
+  Default: `[]`
+
+* **extra_pkg_bpo**  
+  List of packages from the backports repository to be installed.  
+  Type: **List of Strings**  
+  Default: `[]`
+
+* **extra_pkg_bpo1**  
+  List of packages from the backports repository to be installed.  
+  Type: **List of Strings**  
+  Default: `[]`
+
+* **extra_pkg_bpo2**  
+  List of packages from the backports repository to be installed.  
+  Type: **List of Strings**  
+  Default: `[]`
+
+## Example
+
+All hosts receive the following packages:
+* kicad
+* freecad
+
+Devices in the teacherlaptops group additionally receive:
+* plasma-discover
+* nextcloud-desktop
+* dolphin-nextcloud
+
+```yaml
+inventory.yml
+all:
+  vars:
+    extra_pkg:
+      - kicad
+      - freecad
+teacherlaptops:
+  hosts:
+    - nbt[001:999]:
+  vars:
+    extra_pkg1:
+      - plasma-discover
+      - nextcloud-desktop
+      - dolphin-nextcloud
+```
diff --git a/doc/updater.md b/doc/updater.md
new file mode 100644
index 0000000..6bcd665
--- /dev/null
+++ b/doc/updater.md
@@ -0,0 +1,61 @@
+# Updater
+
+## Description / Use Cases
+
+The updater service allows clients to be updated automatically. Changes in the Ansible playbook or inventory are applied automatically to all configured clients.
+
+## Requirements
+
+* The Ansible playbook must be available via a **public Git repository**.
+* Hosts in the inventory must be specified by their **hostname**, not by their IP address.
+
+## Activation / Default
+
+To install the updater service on clients, set the variable `misc_updater_repository` to a valid Git repository URL. If not set (default: **false**), the service will not be installed.
+
+To enable the updater service on clients, set the variable `misc_updater_autostart` to **true**.
+
+## Configuration / Variables
+
+* **misc_updater_inventory**  
+  Name of the Ansible inventory file.  
+  Type: **String**
+
+* **misc_updater_inventory_password**  
+  Password for the inventory file if it is protected or encrypted via Ansible Vault.  
+  Type: **String**
+
+* **misc_updater_repository**  
+  URL of the public Git repository.  
+  Type: **String**
+
+* **misc_updater_branch**  
+  Name of the Git branch.  
+  Type: **String**
+
+* **misc_updater_autostart**  
+  Flag to enable the updater service. The updater starts 5 minutes after boot.  
+  Type: **Boolean**  
+  Values:
+  * `false` — default
+  * `true`
+
+## Example
+
+All computers receive the updater service.
+Automatic updates are installed on all computers except those in the teacherlaptops group.
+
+```
+inventory.yml
+all:
+  vars:
+    misc_updater_inventory: inventory-myschool.yml
+    misc_updater_inventory_password: top-secret
+    misc_updater_repository: https://git.example.com/it-team/lmn-client.git
+    misc_updater_branch: myschool
+    misc_updater_autostart: true
+
+teacherlaptops:
+  vars:
+    misc_updater_autostart: false
+```