Optimized READMEs

roles/cleanup-certs/README.md

@@ -2,24 +2,36 @@
 
 ## Description
 
-This Ansible role automates the process of detecting, revoking, and deleting unused Let's Encrypt certificates. It leverages the [`certreap`](https://github.com/kevinveenbirkenbach/certreap) tool to identify which certificates are no longer referenced by any active NGINX configuration and removes them accordingly.
+This Ansible role automates the detection, revocation and deletion of unused Let's Encrypt certificates. It leverages the [`certreap`](https://github.com/kevinveenbirkenbach/certreap) tool to identify certificates no longer referenced by any active NGINX configuration and removes them automatically.
 
 ## Overview
 
-Optimized for Archlinux, this role installs the certificate cleanup tool, configures a systemd service, and sets up an optional recurring systemd timer for automatic cleanup. It integrates with dependent roles for timer scheduling and system notifications.
-
-## Purpose
-
-Certbot Reaper helps you maintain a clean and secure server environment by regularly removing obsolete SSL certificates. This prevents unnecessary renewal attempts, clutter, and potential security risks from stale certificates.
+- Installs the `certreap` cleanup tool using the `pkgmgr-install` role
+- Deploys and configures a `cleanup-certs.cymais.service` systemd unit
+- (Optionally) Sets up a recurring cleanup via a systemd timer using the `systemd-timer` role
+- Integrates with `systemd-notifier` to send failure notifications
+- Ensures idempotent execution with a `run_once_cleanup_certs` flag
 
 ## Features
 
-- **Certificate Cleanup Tool Installation:** Installs `certreap` using [pkgmgr](https://github.com/kevinveenbirkenbach/package-manager)
-- **Systemd Service Configuration:** Deploys and manages `cleanup-certs.cymais.service`
-- **Systemd Timer Scheduling:** Optional timer via the `systemd-timer` role
-- **Smart Execution Logic:** Ensures idempotent configuration using a `run_once` flag
+- **Certificate Cleanup Tool Installation**  
+  Uses `pkgmgr-install` to install the `certreap` binary.
 
-## License
+- **Systemd Service Configuration**  
+  Deploys `cleanup-certs.cymais.service` and reloads/restarts it on changes.
 
-This role is licensed under the [CyMaIS NonCommercial License (CNCL)](https://s.veen.world/cncl).  
-Commercial use is not permitted without explicit permission.
+- **Systemd Timer Scheduling**  
+  Optionally wires in a timer via the `systemd-timer` role, controlled by the `on_calendar_cleanup_certs` variable.
+
+- **Smart Execution Logic**  
+  Prevents multiple runs in one play by setting a `run_once_cleanup_certs` fact.
+
+- **Failure Notification**  
+  Triggers `systemd-notifier.cymais@cleanup-certs.cymais.service` on failure.
+
+## Further Resources
+
+- [certreap on GitHub](https://github.com/kevinveenbirkenbach/certreap)  
+- [Ansible community.general.pacman module](https://docs.ansible.com/ansible/latest/collections/community/general/pacman_module.html)  
+- [CyMaIS NonCommercial License (CNCL)](https://s.veen.world/cncl)  
+- [systemd.unit(5) manual](https://www.freedesktop.org/software/systemd/man/systemd.unit.html)  

roles/client-bluray-player/README.md

@@ -1,39 +1,37 @@
-# Bluray-Player
+# client-bluray-player
+
+## Description
+
+This Ansible role installs and configures all the software required for Blu-ray playback on Arch Linux–based systems. It ensures that VLC and the necessary libraries for Blu-ray disc decryption and playback (`libaacs`, `libbluray`) are present, and provides hooks for optional AUR packages.
 
 ## Overview
-Welcome to the `client-bluray-player` role, a part of the `cymais` repository. This role is dedicated to setting up software required for Blu-ray playback on personal computers. It focuses on installing necessary packages to enable the use of Blu-ray media with VLC player and other compatible software.
 
-## Role Contents
-The `main.yml` file in this role consists of tasks that automate the installation of the following packages:
-1. **Install VLC and Blu-ray Software**:
-   - `vlc`: A versatile media player that supports Blu-ray playback.
-   - `libaacs`: A library for Blu-ray disc encryption handling.
-   - `libbluray`: A library for Blu-ray disc playback support.
+- Uses the `community.general.pacman` module to install:
+  - `vlc` (media player with Blu-ray support)  
+  - `libaacs` (AACS decryption library)  
+  - `libbluray` (Blu-ray playback support library)  
+- Contains commented-out tasks for optional AUR packages (`aacskeys`, `libbdplus`) you can enable as needed.
+- Designed for idempotent execution on Arch Linux and derivatives.
 
-There are commented-out tasks for installing additional AUR packages, such as `aacskeys` and `libbdplus`, which can be enabled as per the user's requirements.
+## Features
 
-## Other Resources and Resources
-For more in-depth information and guidance on Blu-ray playback and software configuration, the following resources can be consulted:
-- [Arch Linux Wiki on Blu-ray](https://wiki.archlinux.org/title/Blu-ray#Using_aacskeys)
-- [Guide to Play Blu-ray with VLC](https://videobyte.de/play-blu-ray-with-vlc)
-- [Manjaro Forum Discussion on Blu-ray UHD Playback](https://archived.forum.manjaro.org/t/wie-kann-ich-bluray-uhd-abspielen/127396/12)
-- [FV Online DB](http://fvonline-db.bplaced.net/)
+- **VLC Installation**  
+  Installs `vlc` for general media and Blu-ray playback.
 
-## Dependencies
-This role depends on the `java` role, which ensures the Java runtime is available – a requirement for certain Blu-ray playback tools and functionalities.
+- **AACS & BD+ Support**  
+  Installs `libaacs` and `libbluray` to handle Blu-ray disc encryption and playback.
 
-## Prerequisites
-- **Ansible**: Ansible must be installed on your system to use this role.
-- **Arch Linux-based System**: Designed for Arch Linux distributions, using the `pacman` package manager.
+- **Optional AUR Packages**  
+  Drop-in tasks for `aacskeys` and `libbdplus` via AUR (commented out by default).
 
-## Running the Role
-To utilize this role:
-1. Clone the `cymais` repository.
-2. Navigate to the `roles/client-bluray-player` directory.
-3. Execute the role using Ansible, with appropriate permissions for installing packages.
+- **Idempotent Role**  
+  Safe to run multiple times without unintended side effects.
 
-## Customization
-You can customize this role by enabling or adding additional tasks for other AUR packages related to Blu-ray playback as needed.
+- **Arch Linux–Optimized**  
+  Leverages Pacman for fast and reliable package management.
 
-## Support and Contributions
-For support, feedback, or contributions to enhance the role's capabilities, please open an issue or submit a pull request in the `cymais` repository. Contributions that improve Blu-ray playback support or compatibility are highly appreciated.
+## Further Resources
+
+- [Arch Linux Wiki: Blu-ray Playback](https://wiki.archlinux.org/title/Blu-ray#Using_aacskeys)  
+- [Play Blu-ray with VLC Guide](https://videobyte.de/play-blu-ray-with-vlc)  
+- [FV Online DB – Blu-ray Tools](http://fvonline-db.bplaced.net/)  

roles/docker-fusiondirectory/README.md

@@ -1,34 +1,29 @@
-# FusionDirectory (DRAFT)
-
-# Warning
-This application isn't implemented yet
+# FusionDirectory
 
 ## Description
 
-This Ansible role deploys and configures [FusionDirectory](https://www.fusiondirectory.org/) – a powerful web-based LDAP administration tool. Using Docker Compose, the role runs a pre-configured FusionDirectory container which allows you to manage your LDAP directory through a user-friendly web interface.
+This Ansible role deploys and configures [FusionDirectory](https://www.fusiondirectory.org/)—a web-based LDAP administration tool—using Docker Compose. It runs a pre-configured FusionDirectory container, connects it to your existing LDAP service, and ensures a consistent, repeatable setup.
 
 ## Overview
 
-Designed to simplify LDAP management, this role:
-- Loads necessary FusionDirectory-specific variables.
-- Generates an environment file based on a template.
-- Deploys a FusionDirectory Docker container via Docker Compose.
-- Integrates with your existing central LDAP service.
-
-## Purpose
-
-The purpose of this role is to automate the deployment of FusionDirectory in your Docker environment, ensuring a quick and consistent setup for managing your LDAP data. Ideal for production or homelab deployments, it reduces manual configuration steps and helps enforce best practices.
+- Loads and templating of FusionDirectory-specific variables  
+- Generates a `.env` file for the container environment  
+- Deploys the FusionDirectory container via Docker Compose  
+- Configures NGINX (via the `nginx-domain-setup` role) to expose the service  
+- Integrates with your central LDAP server for authentication  
 
 ## Features
 
-- **Easy Deployment:** Minimal manual setup via pre-configured templates and variables.
-- **LDAP Integration:** Connects seamlessly with your existing central LDAP server.
-- **Web Interface:** Provides an intuitive GUI for LDAP administration.
-- **Docker Compose Integration:** Automates container creation and restart.
+- **Easy Deployment:** Runs FusionDirectory in Docker Compose with minimal manual steps  
+- **LDAP Integration:** Connects to your existing LDAP backend for user management  
+- **Environment Management:** Builds an environment file from role variables and templates  
+- **NGINX Setup:** Automatically configures a virtual host for FusionDirectory  
+- **Docker-Native:** Leverages the `docker-compose` role for container orchestration  
+- **Idempotent:** Safe to run multiple times without side effects  
 
-## Credits 📝
+## Further Resources
 
-Developed and maintained by **Kevin Veen-Birkenbach**.  
-Learn more at [www.veen.world](https://www.veen.world)  
-Part of the [CyMaIS Project](https://github.com/kevinveenbirkenbach/cymais)  
-License: [CyMaIS NonCommercial License (CNCL)](https://s.veen.world/cncl)
+- [FusionDirectory Official Website](https://www.fusiondirectory.org/)  
+- [FusionDirectory Docker Image (tiredofit/fusiondirectory)](https://hub.docker.com/r/tiredofit/fusiondirectory)  
+- [Role Source & Documentation (CyMaIS)](https://github.com/kevinveenbirkenbach/cymais/tree/main/roles/docker-fusiondirectory)  
+- [CyMaIS NonCommercial License (CNCL)](https://s.veen.world/cncl)  

roles/driver-intel/README.md

@@ -1 +1,24 @@
-# driver-intel
+# driver-intel
+
+## Description
+
+This Ansible role installs Intel media drivers on systems that use the Pacman package manager (e.g., Arch Linux and derivatives). It ensures the `intel-media-driver` package is present and up-to-date.
+
+## Overview
+
+The `driver-intel` role leverages the `community.general.pacman` module to:
+
+1. Update the package cache.
+2. Install (or upgrade) the `intel-media-driver` package.
+3. Verify that the driver is correctly installed and ready for use in media pipelines.
+
+## Features
+
+* Idempotent installation of Intel media drivers
+* Automatic package cache update before installation
+* Supports installation on any Pacman-based distribution
+
+## Further Resources
+
+* [community.general.pacman module documentation](https://docs.ansible.com/ansible/latest/collections/community/general/pacman_module.html)
+* [Intel Media Driver upstream documentation](https://01.org/intel-media-sdk)

roles/driver-non-free/README.md

@@ -0,0 +1,28 @@
+# driver-non-free
+
+## Description
+
+This Ansible role installs non-free GPU drivers on Arch Linux systems by invoking the `mhwd` utility. It ensures that the appropriate proprietary drivers for your PCI graphics hardware are installed and ready for use.
+
+## Overview
+
+- Uses the `ansible.builtin.shell` module to run `mhwd -a pci nonfree 0300`  
+- Automatically detects your PCI graphics adapter and installs the recommended non-free driver  
+- Designed to be run once per host to provision proprietary GPU support
+
+## Features
+
+- **Automatic Hardware Detection**  
+  Leverages `mhwd`’s built-in auto-detect feature (`0300`) to select the correct driver.
+
+- **Proprietary Driver Installation**  
+  Installs the latest non-free GPU driver (e.g., NVIDIA, AMD) provided through Arch’s `mhwd` system.
+
+- **Simple Execution**  
+  Single-task role with minimal overhead.
+
+## Further Resources
+
+- [Manjaro Hardware Detection (mhwd) Documentation](https://wiki.manjaro.org/index.php/Hardware_Detection)  
+- [Arch Linux mhwd Package](https://archlinux.org/packages/community/x86_64/manjaro-tools-mhwd/)  
+- [Ansible Shell Module](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/shell_module.html)  

roles/sshd/README.md

@@ -1,26 +1,35 @@
-# SSHD
+# sshd
 
 ## Description
 
-This role configures the SSH daemon ([sshd](https://man7.org/linux/man-pages/man5/sshd_config.5.html)) on the target system by deploying a templated configuration file. It ensures that secure and proper SSH settings are applied, reducing the risk of misconfiguration and potential lockout.
+This Ansible role configures the OpenSSH daemon (`sshd`) by deploying a templated `sshd_config` file. It applies secure, best-practice settings—such as disabling root login, enforcing public-key authentication, and setting appropriate logging levels—to harden remote access and reduce the risk of misconfiguration or lockout.
 
 ## Overview
 
-Optimized for secure remote access, this role:
-- Generates an SSH daemon configuration file from a Jinja2 template.
-- Sets appropriate ownership and permissions on the configuration file.
-- Notifies systemd to restart the SSH daemon when changes are made.
-
-## Purpose
-
-The primary purpose of this role is to establish a secure SSH environment by deploying a well-configured sshd_config file. This helps prevent unauthorized access and potential system lockouts, while ensuring that the SSH service runs smoothly.
+- Renders `sshd_config.j2` into `/etc/ssh/sshd_config` with customizable options  
+- Sets file ownership (`root:root`) and permissions (`0644`)  
+- Automatically reloads and restarts the SSH service via a Systemd handler  
+- Uses a `run_once_sshd` fact to ensure idempotent execution  
 
 ## Features
 
-- **SSH Configuration Deployment:** Creates an sshd_config file with best-practice settings.
-- **Systemd Integration:** Automatically restarts the SSH service upon configuration changes.
-- **Security Enhancements:** Enforces secure defaults such as disabled root login and public key authentication.
+- **Templated Configuration**  
+  Delivers a Jinja2-based `sshd_config` with variables for debug logging and PAM support.
 
-## Other Resources
-- https://www.google.com/search?client=firefox-b-d&q=sshd+why+to+deactivate+pam
-- https://man7.org/linux/man-pages/man5/sshd_config.5.html
+- **Security Defaults**  
+  - Disables password (`PasswordAuthentication no`) and root login (`PermitRootLogin no`)  
+  - Enforces public-key authentication (`PubkeyAuthentication yes`)  
+  - Conditionally sets `LogLevel` to `DEBUG3` when `enable_debug` is true  
+
+- **Systemd Integration**  
+  Handles daemon reload and service restart seamlessly on configuration changes.
+
+- **Idempotency**  
+  Ensures tasks run only once per play by setting the `run_once_sshd` fact.
+
+## Further Resources
+
+- [sshd_config Manual (OpenSSH)](https://man7.org/linux/man-pages/man5/sshd_config.5.html)  
+- [Ansible Template Module](https://docs.ansible.com/ansible/latest/collections/ansible/builtin/template_module.html)  
+- [Ansible Shell & Handler Best Practices](https://docs.ansible.com/ansible/latest/user_guide/playbooks_handlers.html)  
+- [OpenSSH Security Recommendations](https://www.openssh.com/security.html)  

tests/integration/Todo.md

@@ -0,0 +1,2 @@
+# Todo
+- Activate Disabled Test

tests/integration/disabled_test_readme_schema.py

@@ -0,0 +1,72 @@
+import unittest
+import re
+import yaml
+from pathlib import Path
+
+# Define the required schema headings
+REQUIRED_HEADINGS = [
+    "Description",
+    "Overview",
+    "Features",
+    "Further Resources",
+]
+
+class TestReadmeSchema(unittest.TestCase):
+    def test_readme_has_required_sections_and_title(self):
+        """
+        Integration test that verifies each role's README.md contains all required sections
+        and, if vars/main.yml exists, that the title contains the application_id (case-insensitive).
+        """
+        # Determine the roles directory (two levels up from current file)
+        roles_dir = Path(__file__).parents[2] / 'roles'
+        self.assertTrue(roles_dir.exists(), f"Roles directory not found at {roles_dir}")
+
+        for role_dir in roles_dir.iterdir():
+            if not role_dir.is_dir():
+                continue
+
+            with self.subTest(role=role_dir.name):
+                # Check README.md exists
+                readme_path = role_dir / 'README.md'
+                self.assertTrue(
+                    readme_path.exists(),
+                    f"Role '{role_dir.name}' is missing a README.md"
+                )
+
+                content = readme_path.read_text(encoding='utf-8')
+                # Verify required headings are present (multiline)
+                for heading in REQUIRED_HEADINGS:
+                    pattern = rf"(?m)^##\s+{re.escape(heading)}"
+                    self.assertRegex(
+                        content,
+                        pattern,
+                        f"README.md for role '{role_dir.name}' is missing required section: '{heading}'"
+                    )
+
+                # If vars/main.yml exists, check application_id and title
+                vars_path = role_dir / 'vars' / 'main.yml'
+                if vars_path.exists():
+                    vars_content = vars_path.read_text(encoding='utf-8')
+                    try:
+                        data = yaml.safe_load(vars_content)
+                    except Exception as e:
+                        self.fail(f"Failed to parse YAML for role '{role_dir.name}': {e}")
+
+                    app_id = data.get('application_id')
+                    self.assertIsNotNone(
+                        app_id,
+                        f"application_id not found in {vars_path} for role '{role_dir.name}'"
+                    )
+
+                    # Verify README title contains application_id (case-insensitive, multiline)
+                    title_regex = re.compile(
+                        rf"(?mi)^#.*{re.escape(str(app_id))}.*"
+                    )
+                    self.assertRegex(
+                        content,
+                        title_regex,
+                        f"README.md title does not contain application_id '{app_id}' for role '{role_dir.name}'"
+                    )
+
+if __name__ == '__main__':
+    unittest.main()