From b4507182aefa3ba9337a7d3c4e449245b8869d7e Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?J=C3=B6rg=20Sachse?= <joerg.sachse@slub-dresden.de>
Date: Tue, 21 Jan 2025 11:16:00 +0100
Subject: [PATCH] doc: improve task descriptions to make their respective
 purpose and context more clear

---
 tasks/compile_callas_binaries.yml   | 26 ++++++++++-----
 tasks/configure_apache.yml          | 28 +++++++++-------
 tasks/configure_crontab.yml         |  2 +-
 tasks/configure_iptables.yml        |  2 +-
 tasks/configure_local_mounts.yml    |  2 +-
 tasks/configure_nfs_mounts.yml      |  7 ++--
 tasks/create_users_groups.yml       |  4 +--
 tasks/install_callas_pdf_engine.yml | 52 +++++++++++++++++------------
 tasks/install_converters.yml        |  4 ++-
 tasks/install_fonts.yml             |  3 +-
 tasks/install_packages.yml          |  4 +--
 tasks/install_validators.yml        |  5 +--
 tasks/main.yml                      | 34 ++++++++++++-------
 13 files changed, 105 insertions(+), 68 deletions(-)

diff --git a/tasks/compile_callas_binaries.yml b/tasks/compile_callas_binaries.yml
index 19741fa..e2d9c8d 100644
--- a/tasks/compile_callas_binaries.yml
+++ b/tasks/compile_callas_binaries.yml
@@ -8,7 +8,7 @@
 # version is used, the CGI-Binaries for validation and repair fail. Make sure
 # to keep the package on the Debian repo server up to date with the latest
 # Debian releases.
-- name: install prerequisite packages for compilation
+- name: Install prerequisite packages for compilation.
   ansible.builtin.apt:
     name: [
       'g++',
@@ -18,19 +18,22 @@
     ]
     state: present
 
-- name: setup deploy key
+- name: >
+    Setup SSH deploy key that is needed to authenticate against SLUB's local
+    GitLab instance when cloning the PDF/A-Webservice Git repo.
   ansible.builtin.copy:
     src: "{{ role_path }}/../ansible_vaults/{{ role_name }}/id_ed25519_deploykey"
     dest: "/tmp/id_ed25519_deploykey"
     mode: "0600"
 
-- name: clear Git repo directory for fresh checkout
+- name: Clear Git repo directory for fresh checkout.
   ansible.builtin.file:
     path: "/opt/pdfa_webservice/"
     state: absent
-  changed_when: false    # This cannot be idempotent, because later tasks change the repo content.
+  changed_when: false    # This cannot be idempotent, because later tasks
+                         # change the repo content.
 
-- name: checkout PDF/A-Webservice Git repo
+- name: Clone PDF/A-Webservice Git repo.
   ansible.builtin.git:
     repo: "git@git.slub-dresden.de:slub-digitalpreservation/pdfa_webservice.git"
     dest: "/opt/pdfa_webservice/"
@@ -39,9 +42,12 @@
     key_file: "/tmp/id_ed25519_deploykey"
     ssh_opts: "-o StrictHostKeyChecking=accept-new"
     update: true
-  changed_when: false    # This cannot be idempotent, because later tasks change the repo content.
+  changed_when: false    # This cannot be idempotent, because later tasks
+                         # change the repo content.
 
-- name: set symlinks for Callas PDF Engine
+- name: >
+    Set symlinks for Callas PDF Engine, so files can be found at their
+    respective standard paths.
   ansible.builtin.file:
     state: link
     src: "/usr/local/lib/callas_pdfEngine_SDK_x64/callas_pdfEngineSDK_x64_Linux_{{ callas_sdk_version }}/{{ item }}"
@@ -54,7 +60,9 @@
     - "var"
   changed_when: false    # This always changes, because the dest path is fresh.
 
-- name: remove libstdc++ that is delivered with CallasSDK to ensure that local system lib is used
+- name: >
+    Remove libstdc++ that is shipped with CallasSDK to ensure that the local
+    system library is used.
   ansible.builtin.file:
     name: "/usr/lib/cgi-bin/lib/libstdc++.so.6"
     state: absent
@@ -63,7 +71,7 @@
 # We need to use the ansible.builtin.shell module here, because the
 # ansible.builtin.command module does not accept setting environment variables
 # inline. Molecule errors are turned off for this.
-- name: compile PDF/A-Webservice binary    # noqa command-instead-of-shell
+- name: Compile PDF/A-Webservice binaries.    # noqa command-instead-of-shell
   ansible.builtin.shell:
     cmd: 'make --directory /opt/pdfa_webservice/src/'
   changed_when: false    # This always changes, because the dest path is fresh.
diff --git a/tasks/configure_apache.yml b/tasks/configure_apache.yml
index d66b4a9..79e4f2d 100644
--- a/tasks/configure_apache.yml
+++ b/tasks/configure_apache.yml
@@ -1,17 +1,20 @@
 ---
-### APACHE KONFIGURIEREN ###
 # symlink /etc/apache2/mods-available/cgi.load to /etc/apache2/mods-enabled/
-- name: CGI-Extension-Modul aktivieren
+- name: >
+    Activate CGI-Extension-Module and SSL-Extension-Module in order to be able
+    to run the Services as cgi-bin scripts secured by TLS.
   community.general.apache2_module:
     name: "{{ item }}"
   loop:
     - "cgid"
     - "ssl"
   notify: restart apache
-- name: Restart apache immediately to make sure mod_ssl is running before configuring TLS.
+- name: >
+    Restart apache immediately to make sure mod_ssl is running before
+    configuring TLS.
   ansible.builtin.meta: flush_handlers
 
-- name: Apache-Konfigurationsdateien einspielen (copied)
+- name: Deploy Apache config files (copied).
   ansible.builtin.copy:
     src: "{{ item.src }}"
     dest: "{{ item.dest }}"
@@ -24,7 +27,7 @@
   notify:
     - restart apache
 
-- name: Apache-Konfigurationsdateien einspielen (templated)
+- name: Deploy Apache config files (templated).
   ansible.builtin.template:
     src: "{{ item.src }}.j2"
     dest: "{{ item.dest }}"
@@ -35,13 +38,13 @@
   notify:
     - restart apache
 
-- name: check if config needs to be enabled
+- name: Check if config needs to be enabled.
   ansible.builtin.command: "/usr/sbin/a2query -c serve-cgi-bin"
   register: a2query
   changed_when: false
 
 # symlink /etc/apache2/conf-available/serve-cgi-bin.conf to /etc/apache2/conf-enabled/
-- name: CGI-Extension-Config aktivieren
+- name: Activate CGI-Extension-Config.
   ansible.builtin.command: "/usr/sbin/a2enconf serve-cgi-bin"        # noqa no-changed-when
   when: not "(enabled by site administrator)" in a2query.stdout
   register: a2enconf
@@ -49,14 +52,13 @@
   notify:
     - restart apache
 
-### STARTSEITE INSTALLIEREN ###
-- name: alte Startseite löschen
+- name: Delete default/old index page. It will be replaced by a custom file.
   ansible.builtin.file:
     path: "/var/www/html/index.html"
     state: absent
   changed_when: false
 
-- name: Startseite neu installieren
+- name: Install new landing page that links to the services offered here.
   ansible.builtin.blockinfile:
     dest: "/var/www/html/index.html"
     backup: false
@@ -87,7 +89,9 @@
     insertafter: EOF
   changed_when: false
 
-- name: set HTTP timeout
+- name: >
+    Set custom HTTP timeout. We want to keep connections open longer than the
+    default 60 seconds, because file uploads might take longer.
   ansible.builtin.lineinfile:
     path: "/etc/apache2/apache2.conf"
     regexp: "^Timeout [0-9]+$"
@@ -96,7 +100,7 @@
   notify:
     - restart apache
 
-- name: copy server certificates
+- name: Install TLS server certificates for providing TLS connections.
   ansible.builtin.copy:
     src: "{{ role_path }}/../ansible_vaults/{{ role_name }}/{{ ansible_hostname }}/{{ item }}"
     dest: "/etc/ssl/certs/{{ item }}"
diff --git a/tasks/configure_crontab.yml b/tasks/configure_crontab.yml
index 2cbbed8..e85fded 100644
--- a/tasks/configure_crontab.yml
+++ b/tasks/configure_crontab.yml
@@ -3,7 +3,7 @@
 - name: DEBUG
   ansible.builtin.debug:
     var: users
-- name: Cronjob zum Löschen alter tmpfiles aus /tmp erstellen
+- name: Create Cronjob for deleting old tmpfiles from /tmp/.
   ansible.builtin.cron:
     name: "delete old tmpfiles from /tmp"
     hour: "0"
diff --git a/tasks/configure_iptables.yml b/tasks/configure_iptables.yml
index 32d13f9..30cdffe 100644
--- a/tasks/configure_iptables.yml
+++ b/tasks/configure_iptables.yml
@@ -1,5 +1,5 @@
 ---
-- name: iptables-Regeln setzen
+- name: Configure iptables rules.
   ansible.builtin.iptables:
     action: "insert"
     chain: "INPUT"
diff --git a/tasks/configure_local_mounts.yml b/tasks/configure_local_mounts.yml
index 0ea27b9..4330579 100644
--- a/tasks/configure_local_mounts.yml
+++ b/tasks/configure_local_mounts.yml
@@ -1,5 +1,5 @@
 ---
-- name: Mount tmpfs for non-persistent and fast /tmp directory
+- name: Mount tmpfs for non-persistent and fast /tmp/ directory.
   ansible.posix.mount:
     boot: true
     fstype: "tmpfs"
diff --git a/tasks/configure_nfs_mounts.yml b/tasks/configure_nfs_mounts.yml
index a3c217f..c848b40 100644
--- a/tasks/configure_nfs_mounts.yml
+++ b/tasks/configure_nfs_mounts.yml
@@ -1,11 +1,14 @@
 ---
-- name: Mountpoint fuer Logging anlegen
+- name: >
+    Explicitely create mountpoint for logging. We do this to be able to set
+    restrictive permissions, so a failed log share can be easily detected due
+    to the write errors that will occur if the NFS share fails.
   ansible.builtin.file:
     path: "{{ nfs_mounts.log.mountpoint }}{{ ansible_hostname }}"
     state: directory
     mode: "0400"
 
-- name: NFS-Shares fuer Logging mounten
+- name: Mount NFS-Share for logging.
   ansible.posix.mount:
     name: "{{ nfs_mounts.log.mountpoint }}{{ ansible_hostname }}"
     src: "{{ nfs_mounts.log.share }}/{{ ansible_hostname }}"
diff --git a/tasks/create_users_groups.yml b/tasks/create_users_groups.yml
index 9162d9f..2d5589e 100644
--- a/tasks/create_users_groups.yml
+++ b/tasks/create_users_groups.yml
@@ -1,12 +1,12 @@
 ---
-- name: Gruppen erstellen
+- name: Create groups.
   ansible.builtin.group:
     name: "{{ item.name }}"
     gid: "{{ item.gid | default(omit) }}"
     state: "{{ item.state | default('present') }}"
   loop: "{{ grouplist | flatten(levels=1) }}"
 
-- name: User in Gruppen einfügen und primäre Gruppe setzen
+- name: Add users to groups and set their respective primary group.
   ansible.builtin.user:
     name: "{{ item.name }}"
     group: "{{ item.group }}"
diff --git a/tasks/install_callas_pdf_engine.yml b/tasks/install_callas_pdf_engine.yml
index c51c211..b35322b 100644
--- a/tasks/install_callas_pdf_engine.yml
+++ b/tasks/install_callas_pdf_engine.yml
@@ -1,5 +1,24 @@
 ---
-- name: remove old version of callas PDFEngine
+# get latest version of callas PDFEngine at
+# http://www.callassoftware.com/extranet/callas_pdfEngineSDK/callas_pdfEngineSDK_x64_Linux.tar.gz
+# downloading with unarchive will be deprecated, so we use a separate copy task
+# !!! CAUTION: DO NOT AUTOMATICALLY INSTALL NEW SDK VERSIONS WITHOUT RECOMPILING
+#              CGI-BIN FILES!!!
+- name: Download Callas PDFEngine.
+  ansible.builtin.get_url:
+    url: "http://www.callassoftware.com/extranet/callas_pdfEngineSDK/callas_pdfEngineSDK_x64_Linux.tar.gz"
+    dest: "/usr/local/lib/callas_pdfEngineSDK_x64_Linux_{{ callas_sdk_version }}.tar.gz"
+    mode: "0644"
+  changed_when: false    # This will always change, because we're installing a
+                         # fresh version of Callas into a cleaned directory
+                         # (see tasks below, where we delete the .tar.gz).
+
+- name: >
+    Remove old version of callas PDFEngine. Callas only provide a universal URL
+    that will redirect to the latest version of the library, so we cannot
+    select a specific Callas version and always have to install the latest
+    version. To do this, we first have to make sure that there are no remains
+    of older versions on the system.
   ansible.builtin.file:
     path: "/usr/local/lib/callas_pdfEngine_SDK_x64"
     state: absent
@@ -7,7 +26,7 @@
                          # idempotent, because we install a new version in
                          # later tasks.
 
-- name: create directories for CGI-BIN and callas PDFEngine
+- name: Create directories for CGI-BIN and Callas PDFEngine.
   ansible.builtin.file:
     path: "{{ item }}"
     state: directory
@@ -18,23 +37,9 @@
   changed_when: false    # This will always change, because we just removed the
                          # dir in the previous task to clean up.
 
-# get latest version of callas PDFEngine at
-# http://www.callassoftware.com/extranet/callas_pdfEngineSDK/callas_pdfEngineSDK_x64_Linux.tar.gz
-# downloading with unarchive will be deprecated, so we use a separate copy task
-# !!! CAUTION: DO NOT AUTOMATICALLY INSTALL NEW SDK VERSIONS WITHOUT RECOMPILING
-#              CGI-BIN FILES!!!
-- name: copy callas PDFEngine
-  ansible.builtin.get_url:
-    url: "http://www.callassoftware.com/extranet/callas_pdfEngineSDK/callas_pdfEngineSDK_x64_Linux.tar.gz"
-    dest: "/usr/local/lib/callas_pdfEngineSDK_x64_Linux_{{ callas_sdk_version }}.tar.gz"
-    mode: "0644"
-  changed_when: false    # This will always change, because we're installing a
-                         # fresh version of Callas into a cleaned directory
-                         # (see tasks below, where we delete the .tar.gz).
-
 # !!! CAUTION: DO NOT EXTRACT TO /tmp/
 # (https://github.com/ansible/ansible/issues/28569)
-- name: unpack callas PDFEngine
+- name: Unpack callas PDFEngine...
   ansible.builtin.unarchive:
     src: "/usr/local/lib/callas_pdfEngineSDK_x64_Linux_{{ callas_sdk_version }}.tar.gz"
     dest: "/usr/local/lib/callas_pdfEngine_SDK_x64"
@@ -48,7 +53,7 @@
   changed_when: false    # This will always change. We just downloaded a fresh
                          # archive that now needs to be cleaned up.
 
-- name: set permissions for PDFEngine
+- name: Set permissions for PDFEngine.
   ansible.builtin.file:
     path: "/usr/local/lib/callas_pdfEngine_SDK_x64"
     group: "www-data"
@@ -56,7 +61,10 @@
     state: directory
   changed_when: false    # This will always change.
 
-- name: symlink callas PDFEngine from '/usr/local/lib/callas_pdfEngine_SDK_x64/*' to '/usr/lib/cgi-bin/*'
+- name: >
+    Symlink callas PDFEngine from '/usr/local/lib/callas_pdfEngine_SDK_x64/*'
+    to '/usr/lib/cgi-bin/*', so Callas libraries can be found below standard
+    paths.
   ansible.builtin.file:
     src: "/usr/local/lib/callas_pdfEngine_SDK_x64/callas_pdfEngineSDK_x64_Linux_{{ callas_sdk_version }}/{{ item }}"
     dest: "/usr/lib/cgi-bin/{{ item }}"
@@ -65,12 +73,14 @@
     - "lib"
     - "lang"
 
-- name: install libstdc++
+- name: Install libstdc++.
   ansible.builtin.apt:
     name: "libstdc++-11-dev"
     state: present
 
-- name: remove symlinks to distro version of libstdc++, because we need to use what's provided with PDFEngine
+- name: >
+    Remove symlinks to distro version of libstdc++, because we need to use
+    what's provided with PDFEngine.
   ansible.builtin.file:
     path: "{{ item }}"
     state: absent
diff --git a/tasks/install_converters.yml b/tasks/install_converters.yml
index 66c7a1a..d675ab9 100644
--- a/tasks/install_converters.yml
+++ b/tasks/install_converters.yml
@@ -1,5 +1,7 @@
 ---
-- name: "'convert_pdfa.bin' nach '/usr/lib/cgi-bin/convert_to_pdfa' kopieren & umbenennen, Rechte setzen"
+- name: >
+    "Copy 'convert_pdfa.bin' to '/usr/lib/cgi-bin/convert_to_pdfa', rename it
+    to match URLs and set permissions."
   ansible.builtin.copy:
     src: "/opt/pdfa_webservice/src/unix/convert_to_pdfa.bin"
     dest: "/usr/lib/cgi-bin/convert_to"
diff --git a/tasks/install_fonts.yml b/tasks/install_fonts.yml
index 3293c79..6ada7c1 100644
--- a/tasks/install_fonts.yml
+++ b/tasks/install_fonts.yml
@@ -1,6 +1,5 @@
 ---
-# install applefonts
-- name: install applefonts package
+- name: Install applefonts package.
   ansible.builtin.package:
     name: "applefonts"
     state: latest
diff --git a/tasks/install_packages.yml b/tasks/install_packages.yml
index 357e536..f4a4b01 100644
--- a/tasks/install_packages.yml
+++ b/tasks/install_packages.yml
@@ -1,5 +1,5 @@
 ---
-- name: Install/Update Debian packages
+- name: Install/Update Debian packages.
   ansible.builtin.apt:
     update_cache: true
     state: present
@@ -39,7 +39,7 @@
       'unzip'
     ]
 
-- name: remove unnecessary packages
+- name: Remove unnecessary packages.
   ansible.builtin.apt:
     state: absent
     name: [
diff --git a/tasks/install_validators.yml b/tasks/install_validators.yml
index 821c010..6bd2ba8 100644
--- a/tasks/install_validators.yml
+++ b/tasks/install_validators.yml
@@ -1,6 +1,7 @@
 ---
-### INSTALLATION VALIDATOREN ###
-- name: "'validate_pdfa.bin' nach '/usr/lib/cgi-bin/is_valid' kopieren & umbenennen, Rechte setzen"
+- name: >
+    "Copy 'validate_pdfa.bin' to '/usr/lib/cgi-bin/is_valid', rename it to
+    match URLs and set permissions."
   ansible.builtin.copy:
     src: "/opt/pdfa_webservice/src/unix/validate_pdfa.bin"
     dest: "/usr/lib/cgi-bin/is_valid"
diff --git a/tasks/main.yml b/tasks/main.yml
index 3f76f45..8d86977 100644
--- a/tasks/main.yml
+++ b/tasks/main.yml
@@ -5,50 +5,60 @@
     - "validator.vault"
   tags: [always]
 
-- name: install packages
+- name: >
+    Install packages that are necessary for running and testing the validation/
+    conversion services.
   ansible.builtin.import_tasks: "install_packages.yml"
   tags: [apt, package, packages]
 
-- name: create users and groups
+- name: Create users and groups.
   ansible.builtin.import_tasks: "create_users_groups.yml"
   tags: [user, users, group, groups]
 
-- name: configure local mounts
+- name: >
+    Configure local mounts. To increase performance, we use a RAMdisk to store
+    temporary files.
   ansible.builtin.import_tasks: "configure_local_mounts.yml"
   tags: [mount]
 
-- name: configure nfs mounts
+- name: Configure NFS mounts. Logs are currently written to an NFS share.
   ansible.builtin.import_tasks: "configure_nfs_mounts.yml"
   tags: [nfs]
 
-- name: configure Apache webserver
+- name: >
+    Configure Apache webserver. Converters and validators run as Apache cgi-bin
+    scripts and should be reachable via HTTPS only.
   ansible.builtin.import_tasks: "configure_apache.yml"
   tags: [apache]
 
-- name: install Callas PDF Engine SDK
+- name: >
+    Install Callas PDF Engine SDK. This is a prerequisite to run any
+    PDF-related services.
   ansible.builtin.import_tasks: "install_callas_pdf_engine.yml"
   tags: [callas, callaspdf, callassdk]
 
-- name: compile Callas binaries
+- name: Compile Callas binaries.
   ansible.builtin.import_tasks: "compile_callas_binaries.yml"
   tags: [callas, callaspdf, callassdk]
 
-- name: install fonts
+- name: Install fonts. Conversion requires installed fonts to work.
   ansible.builtin.import_tasks: "install_fonts.yml"
   tags: [fonts]
 
-- name: install validators
+- name: Install validators.
   ansible.builtin.import_tasks: "install_validators.yml"
   tags: [validators]
 
-- name: install converters
+- name: Install converters.
   ansible.builtin.import_tasks: "install_converters.yml"
   tags: [converters]
 
-- name: configure Crontab
+- name: >
+    Configure Crontab for cleanup tasks in order to prevent clogging the
+    temporary file storage.
   ansible.builtin.import_tasks: "configure_crontab.yml"
   tags: [cron]
 
-- name: configure iptables
+- name: Configure iptables.
   ansible.builtin.import_tasks: "configure_iptables.yml"
   tags: [firewall, iptables]
-- 
GitLab