check(playbook): print all held packages

Document the role arguments in the README instead of in the
argument_specs for better discoverability and readability.

inventories/chaosknoten/host_vars/eh22-wiki.yaml

@@ -9,3 +9,6 @@ certbot__certificate_domains:
   - "eh22.easterhegg.eu"
 certbot__new_cert_commands:
   - "systemctl reload nginx.service"
+dokuwiki__custom_theme_git_url: "https://git.hamburg.ccc.de/EH22/dokuwiki-template-sprintdoc-modified.git"
+dokuwiki__custom_theme_version: "eh22"
+dokuwiki__custom_theme_name: "sprintdoc"

playbooks/check.yaml

@@ -29,3 +29,14 @@
     - name: Print .dpkg-* files list
       ansible.builtin.debug:
         var: check__dpkg_files_list
+
+    - name: Get all held packages
+      ansible.builtin.command: apt-mark showhold
+      when: ansible_facts['pkg_mgr'] == "apt"
+      changed_when: false
+      register: check__apt_mark_showhold
+
+    - name: Print all held packages
+      ansible.builtin.debug:
+        var: check__apt_mark_showhold.stdout_lines
+      when: check__apt_mark_showhold.stdout_lines != []

roles/dokuwiki/README.md

@@ -22,6 +22,12 @@ None.
 - `dokuwiki__php_version`: Your PHP version, default `7.4` for Debian 11 and `8.2` for Debian 12
 - `dokuwiki__php_user`: User of your php-fpm process, default `www-data`
 - `dokuwiki__nginx_user`: User of your nginx process, default `nginx`
+- `dokuwiki__custom_theme_git_url`: Clone URL of custom theme (HTTPS only)
+- `dokuwiki__custom_theme_version`: Version (git branch, tag, ...) to checkout, default main
+- `dokuwiki__custom_theme_name`: Name of the directory into which the custom theme is cloned
+
+Warning: if a directory of the same name as `dokuwiki__custom_theme_name` already exists in the same directory, the task will fail.
+This needs to be manually deleted first before the first run with the the custom theme enabled.
 
 ## nginx Configuration
 

roles/dokuwiki/defaults/main.yml

@@ -3,3 +3,6 @@ dokuwiki__installpath: "/var/www/dokuwiki"
 dokuwiki__php_version: "{{ dokuwiki__php_versions[ansible_distribution + '-' + ansible_distribution_major_version] }}"
 dokuwiki__php_user: "www-data"
 dokuwiki__nginx_user: "nginx"
+dokuwiki__custom_theme_git_url: ""
+dokuwiki__custom_theme_version: "main"
+dokuwiki__custom_theme_name: ""

roles/dokuwiki/tasks/main.yml

@@ -1,4 +1,4 @@
-- name: Install php-fpm
+- name: Install dependencies
   become: true
   ansible.builtin.apt:
     name:
@@ -9,6 +9,7 @@
       - php-intl
       - php-gd
       - php-sqlite3
+      - git
   diff: false
 
 - name: Ensure `php-fpm` is enabled
@@ -42,3 +43,17 @@
     owner: root
     group: root
     mode: "0644"
+
+- name: checkout custom theme git repo
+  become: true
+  ansible.builtin.git:
+    repo: "{{ dokuwiki__custom_theme_git_url }}"
+    dest: "{{ dokuwiki__installpath }}/lib/tpl/{{ dokuwiki__custom_theme_name }}"
+    version: "{{ dokuwiki__custom_theme_version }}"
+    force: true
+    depth: 1
+    single_branch: true
+    track_submodules: true
+  when:
+    - dokuwiki__custom_theme_git_url != ""
+    - dokuwiki__custom_theme_name != ""

roles/nginx/README.md

@@ -1,32 +1,39 @@
 # Role `nginx`
 
-Makes sure the `nginx` package is installed from the NGINX repos on the specified hosts.
+Ensures nginx is installed from the NGINX repos and setup as specified via the arguments.
-Also makes sure a desirable baseline of NGINX configs is deployed on the specified hosts.
-For the NGINX site configurations the config template below can be used.
-
-## Entry Points
-
-The entry points available for external use are:
-
-- `main`
 
 ## Supported Distributions
 
 The following distributions are supported:
 
 - Debian 11
+- Debian 12
 
 ## Required Arguments
 
-For the required arguments look at the [`argument_specs.yaml`](./meta/argument_specs.yaml).
+None.
 
-## Updates
+## Optional Arguments
 
-This role updates NGINX to the latest version covered by the provided version spec., if needed.
+- `nginx__deploy_redirect_conf`: Whether or not to deploy a config redirecting from HTTP to HTTPS, while still forwarding the `/.well-known/acme-challenge/` to localhost Port 31820 for certificate issuing.  
-
+  See [`files/redirect.conf`](./files/redirect.conf) for the configuration that would be deployed.  
-## `hosts`
+  Defaults to `true`.
-
+- `nginx__deploy_tls_conf`: Whether or not to deploy a config configuring some TLS settings reasonably.  
-The `hosts` for this role need to be the machines, for which you want to make sure the `nginx` package is installed from the NGINX repos and a desirable baseline of NGINX configs is deployed.
+  See [`files/tls.conf`](./files/tls.conf) for the configuration that would be deployed.  
+  Defaults to `true`.
+- `nginx__deploy_logging_conf`: Whether or not to deploy a config configuring logging to journald.  
+  See [`files/logging.conf`](./files/logging.conf) for the configuration that would be deployed.  
+  Defaults to `true`.
+- `nginx__configurations`: List of nginx configurations to ensure are deployed.
+- `nginx__configurations.*.name`: This name with `.conf` appended will be used for the configurations file name under `/etc/nginx/conf.d/`.  
+  `tls`, `redirect` and `logging` are reserved names.
+- `nginx__configurations.*.content`: This configurations content.  
+- `nginx__use_custom_nginx_conf`: Whether or not to use a custom `/etc/nginx/nginx.conf`.
+  If set to true, you must provide the content for a custom `nginx.conf` via `nginx__custom_nginx_conf`.  
+  Defaults to `false`.
+- `nginx__custom_nginx_conf`: The content to use for the custom `nginx.conf`.
+  Needs `nginx__use_custom_nginx_conf` to be set to true to work.  
+  You should probably still make sure that your custom `nginx.conf` includes `/etc/nginx/conf.d/*.conf`, so that the other configuration files still work.
 
 ## Config Template
 

roles/nginx/handlers/main.yaml

@@ -1,10 +1,5 @@
-- name: Restart `nginx.service`
+- name: Restart nginx
   ansible.builtin.systemd:
     name: nginx.service
     state: restarted
   become: true
-
-- name: apt-get update
-  ansible.builtin.apt:
-    update_cache: true
-  become: true

roles/nginx/meta/argument_specs.yaml

@@ -1,31 +1,15 @@
 argument_specs:
   main:
     options:
-      nginx__version_spec:
-        description: >-
-          The version specification to use for installing the `nginx` package. The
-          provided version specification will be used like the following: `nginx={{
-          nginx__version_spec }}*`. This makes it possible to e.g. specify
-          until a minor version (like `1.3.`) and then have patch versions be
-          installed automatically (like `1.3.1` and so on).
-        type: str
-        required: true
       nginx__deploy_redirect_conf:
-        description: >-
-          Whether or not to deploy a `redirect.conf` to
-          `/etc/nginx/conf.d/redirect.conf`.
         type: bool
         required: false
         default: true
       nginx__deploy_tls_conf:
-        description: >-
-          Whether or not to deploy a `tls.conf` to `/etc/nginx/conf.d/tls.conf`.
         type: bool
         required: false
         default: true
       nginx__deploy_logging_conf:
-        description: >-
-          Whether or not to deploy a `logging.conf` to `/etc/nginx/conf.d/logging.conf`.
         type: bool
         required: false
         default: true
@@ -37,34 +21,16 @@ argument_specs:
         default: [ ]
         options:
           name:
-            description: >-
-              The name of the configuration file, where the configuration should
-              be deployed to. The file will be placed under `/etc/nginx/conf.d/`
-              and `.conf` will be appended to the given name. So in the end the
-              path will be like this: `/etc/nginx/conf.d/\{\{ name \}\}.conf`.
-              Note that the names `tls` and `redirect` aren't allowed.
             type: str
             required: true
           content:
-            description: The content of the configuration.
             type: str
             required: true
       nginx__use_custom_nginx_conf:
-        description: >-
-          Whether or not to use a custom `/etc/nginx/nginx.conf`. If set to
-          true, you must provide a custom `nginx.conf` via
-          `nginx__custom_nginx_conf`.
         type: bool
         required: false
         default: false
       nginx__custom_nginx_conf:
-        description: >-
-          The value for a `nginx.conf` to be placed at `/etc/nginx/nginx.conf`.
-          You must set `nginx__use_custom_nginx_conf` to true for this value to
-          be used.
-          You should probably make sure that your custom `nginx.conf` still
-          includes `/etc/nginx/conf.d/*.conf` so that the configuration provided
-          using `nginx__configurations` still work.
         type: str
         required: false
         default: ""

roles/nginx/tasks/main.yaml

@@ -1,19 +1,11 @@
-- name: make sure nginx configuration names are valid
+- name: Ensure valid configuration names
-  ansible.builtin.include_role:
+  ansible.builtin.import_tasks:
-    name: nginx
+    file: main/01_validate_config_names.yaml
-    tasks_from: make_sure_nginx_configuration_names_are_valid
 
-- name: make sure NGINX repos are setup
+- name: Ensure nginx is installed
-  ansible.builtin.include_role:
+  ansible.builtin.import_tasks:
-    name: nginx
+    file: main/02_nginx_install.yaml
-    tasks_from: main/repo_setup
 
-- name: make sure NGINX is installed
+- name: Ensure configuration deployment
-  ansible.builtin.include_role:
+  ansible.builtin.import_tasks:
-    name: nginx
+    file: main/03_config_deploy.yaml
-    tasks_from: main/nginx_install
-
-- name: make sure desirable NGINX configs are deployed
-  ansible.builtin.include_role:
-    name: nginx
-    tasks_from: main/config_deploy

roles/nginx/tasks/main/01_validate_config_names.yaml

@@ -0,0 +1,7 @@
+- name: Ensure that the given configuration names are valid
+  ansible.builtin.fail:
+    msg: "You used one of the reserved configuration names: '{{ item.name }}'."
+  when: item.name == "tls"
+        or item.name == "redirect"
+        or item.name == "logging"
+  loop: "{{ nginx__configurations }}"

roles/nginx/tasks/main/02_nginx_install.yaml

@@ -1,16 +1,10 @@
-- name: gather package facts
+- name: Ensure gnupg is installed
-  ansible.builtin.package_facts:
-    manager: apt
-
-- name: make sure `gnupg` package is installed
   ansible.builtin.apt:
     name: gnupg
     state: present
-    update_cache: true
   become: true
-  when: "'gnupg' not in ansible_facts.packages"
 
-- name: make sure NGINX signing key is added
+- name: Ensure NGINX signing key is added
   ansible.builtin.get_url:
     url: https://nginx.org/keys/nginx_signing.key
     dest: /etc/apt/trusted.gpg.d/nginx.asc
@@ -18,23 +12,20 @@
     owner: root
     group: root
   become: true
-  notify: apt-get update
 
-- name: make sure NGINX APT repository is added
+- name: Ensure NGINX APT repository is added
   ansible.builtin.apt_repository:
     repo: "deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/nginx.asc] https://nginx.org/packages/debian/ {{ ansible_distribution_release }} nginx"
     state: present
   become: true
-  notify: apt-get update
 
-- name: make sure NGINX APT source repository is added
+- name: Ensure NGINX APT source repository is added
   ansible.builtin.apt_repository:
     repo: "deb-src [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/nginx.asc] https://nginx.org/packages/debian/ {{ ansible_distribution_release }} nginx"
     state: present
   become: true
-  notify: apt-get update
 
-- name: set up repository pinning to make sure nginx package gets installed from NGINX repositories
+- name: Ensure repository pinning to make sure nginx package gets installed from NGINX repositories is set up
   ansible.builtin.copy:
     content: |
       Package: *
@@ -47,5 +38,9 @@
     mode: "0644"
   become: true
 
-- name: Flush handlers to make sure "apt-get update" handler runs, if needed
+- name: Ensure nginx is installed
-  ansible.builtin.meta: flush_handlers
+  ansible.builtin.apt:
+    name: nginx
+    state: present
+    update_cache: true
+  become: true

roles/nginx/tasks/main/03_config_deploy.yaml

@@ -1,13 +1,13 @@
-- name: check, if a save of a previous `nginx.conf` is present
+- name: Check, if a save of a previous `nginx.conf` is present
   ansible.builtin.stat:
     path: /etc/nginx/nginx.conf.ansiblesave
-  register: nginx__nginx_conf_ansiblesave_stat_result
+  register: nginx__nginx_conf_ansiblesave_stat
 
-- name: handle the case, where a custom `nginx.conf` is to be used
+- name: Handle the case, where a custom `nginx.conf` is to be used
   when: nginx__use_custom_nginx_conf
   block:
-    - name: when no `nginx.conf.ansiblesave` is present, save the current `nginx.conf`
+    - name: When no `nginx.conf.ansiblesave` is present, save the current `nginx.conf`
-      when: not nginx__nginx_conf_ansiblesave_stat_result.stat.exists
+      when: not nginx__nginx_conf_ansiblesave_stat.stat.exists
       ansible.builtin.copy:
         force: true
         dest: /etc/nginx/nginx.conf.ansiblesave
@@ -18,7 +18,7 @@
         src: /etc/nginx/nginx.conf
       become: true
 
-    - name: deploy the custom `nginx.conf`
+    - name: Ensure the custom `nginx.conf` is deployed
       ansible.builtin.copy:
         content: "{{ nginx__custom_nginx_conf }}"
         dest: "/etc/nginx/nginx.conf"
@@ -26,13 +26,13 @@
         owner: root
         group: root
       become: true
-      notify: Restart `nginx.service`
+      notify: Restart nginx
 
-- name: handle the case, where no custom `nginx.conf` is to be used
+- name: Handle the case, where no custom `nginx.conf` is to be used
   when: not nginx__use_custom_nginx_conf
   block:
-    - name: when a `nginx.conf.ansiblesave` is present, copy it to `nginx.conf`
+    - name: When a `nginx.conf.ansiblesave` is present, copy it to `nginx.conf`
-      when: nginx__nginx_conf_ansiblesave_stat_result.stat.exists
+      when: nginx__nginx_conf_ansiblesave_stat.stat.exists
       ansible.builtin.copy:
         force: true
         dest: /etc/nginx/nginx.conf
@@ -42,32 +42,32 @@
         remote_src: true
         src: /etc/nginx/nginx.conf.ansiblesave
       become: true
-      notify: Restart `nginx.service`
+      notify: Restart nginx
 
-    - name: delete the `nginx.conf.ansiblesave`, if it is present
+    - name: Ensure no `nginx.conf.ansiblesave` is present
-      when: nginx__nginx_conf_ansiblesave_stat_result.stat.exists
+      when: nginx__nginx_conf_ansiblesave_stat.stat.exists
       ansible.builtin.file:
         path: /etc/nginx/nginx.conf.ansiblesave
         state: absent
       become: true
 
-- name: make sure mozilla dhparam is deployed
+- name: Ensure mozilla dhparam is deployed
   ansible.builtin.get_url:
     force: true
     dest: /etc/nginx-mozilla-dhparam
     mode: "0644"
     url: https://ssl-config.mozilla.org/ffdhe2048.txt
   become: true
-  notify: Restart `nginx.service`
+  notify: Restart nginx
 
-- name: set `nginx__config_files_to_exist` fact initially to an empty list
+- name: Set `nginx__config_files_to_exist` fact initially to an empty list
   ansible.builtin.set_fact:
     nginx__config_files_to_exist: [ ]
 
-- name: handle the case, where tls.conf should be deployed
+- name: Handle the case, where tls.conf should be deployed
   when: nginx__deploy_tls_conf
   block:
-    - name: make sure tls.conf is deployed
+    - name: Ensure tls.conf is deployed
       ansible.builtin.copy:
         force: true
         dest: /etc/nginx/conf.d/tls.conf
@@ -76,16 +76,16 @@
         group: root
         src: tls.conf
       become: true
-      notify: Restart `nginx.service`
+      notify: Restart nginx
 
-    - name: add tls.conf to nginx__config_files_to_exist
+    - name: Add tls.conf to nginx__config_files_to_exist
       ansible.builtin.set_fact:
         nginx__config_files_to_exist: "{{ nginx__config_files_to_exist + [ 'tls.conf' ] }}"  # noqa: jinja[spacing]
 
-- name: handle the case, where redirect.conf should be deployed
+- name: Handle the case, where redirect.conf should be deployed
   when: nginx__deploy_redirect_conf
   block:
-    - name: make sure redirect.conf is deployed
+    - name: Ensure redirect.conf is deployed
       ansible.builtin.copy:
         force: true
         dest: /etc/nginx/conf.d/redirect.conf
@@ -94,16 +94,16 @@
         group: root
         src: redirect.conf
       become: true
-      notify: Restart `nginx.service`
+      notify: Restart nginx
 
-    - name: add redirect.conf to nginx__config_files_to_exist
+    - name: Add redirect.conf to nginx__config_files_to_exist
       ansible.builtin.set_fact:
         nginx__config_files_to_exist: "{{ nginx__config_files_to_exist + [ 'redirect.conf' ] }}"  # noqa: jinja[spacing]
 
-- name: handle the case, where logging.conf should be deployed
+- name: Handle the case, where logging.conf should be deployed
   when: nginx__deploy_logging_conf
   block:
-    - name: make sure logging.conf is deployed
+    - name: Ensure logging.conf is deployed
       ansible.builtin.copy:
         force: true
         dest: /etc/nginx/conf.d/logging.conf
@@ -112,13 +112,13 @@
         group: root
         src: logging.conf
       become: true
-      notify: Restart `nginx.service`
+      notify: Restart nginx
 
-    - name: add logging.conf to nginx__config_files_to_exist
+    - name: Add logging.conf to nginx__config_files_to_exist
       ansible.builtin.set_fact:
         nginx__config_files_to_exist: "{{ nginx__config_files_to_exist + [ 'logging.conf' ] }}"  # noqa: jinja[spacing]
 
-- name: make sure all given configuration files are deployed
+- name: Ensure all given configuration files are deployed
   ansible.builtin.copy:
     content: "{{ item.content }}"
     dest: "/etc/nginx/conf.d/{{ item.name }}.conf"
@@ -127,24 +127,24 @@
     group: root
   become: true
   loop: "{{ nginx__configurations }}"
-  notify: Restart `nginx.service`
+  notify: Restart nginx
 
-- name: add names plus suffix from `nginx__configurations` to `nginx__config_files_to_exist` fact
+- name: Add names with suffixes from `nginx__configurations` to `nginx__config_files_to_exist` fact
   ansible.builtin.set_fact:
     nginx__config_files_to_exist: "{{ nginx__config_files_to_exist + [ item.name + '.conf' ] }}"  # noqa: jinja[spacing]
   loop: "{{ nginx__configurations }}"
 
-- name: find configuration files to remove
+- name: Find configuration files to remove
   ansible.builtin.find:
     paths: /etc/nginx/conf.d/
     recurse: false
     excludes: "{{ nginx__config_files_to_exist }}"
   register: nginx__config_files_to_remove
 
-- name: remove all configuration file, which should be removed
+- name: Remove all configuration file, which should be removed
   ansible.builtin.file:
     path: "{{ item.path }}"
     state: absent
   become: true
   loop: "{{ nginx__config_files_to_remove.files }}"
-  notify: Restart `nginx.service`
+  notify: Restart nginx

roles/nginx/tasks/main/nginx_install.yaml

@@ -1,13 +0,0 @@
-- name: make sure the `nginx` package is installed
-  ansible.builtin.apt:
-    name: nginx={{ nginx__version_spec }}*
-    state: present
-    allow_change_held_packages: true
-    update_cache: true
-  become: true
-
-- name: apt-mark hold `nginx`
-  ansible.builtin.dpkg_selections:
-    name: nginx
-    selection: hold
-  become: true

roles/nginx/tasks/make_sure_nginx_configuration_names_are_valid.yaml

@@ -1,6 +0,0 @@
-- name: make sure nginx configuration names are valid
-  ansible.builtin.fail:
-    msg: "You used the following name: `{{ item.name }}`. Please make sure to not use the following names: `tls`, `redirect`."
-  when: item.name == "tls"
-        or item.name == "redirect"
-  loop: "{{ nginx__configurations }}"