From e61ef82f17fbfe024e0520e1fb4cc14ecf4dc65b Mon Sep 17 00:00:00 2001 From: Kevin Veen-Birkenbach Date: Sun, 6 Jul 2025 21:44:50 +0200 Subject: [PATCH] Optimized READMEs --- roles/cleanup-certs/README.md | 38 ++++++---- roles/client-bluray-player/README.md | 56 +++++++-------- roles/docker-fusiondirectory/README.md | 41 +++++------ roles/driver-intel/README.md | 25 ++++++- roles/driver-non-free/README.md | 28 ++++++++ roles/sshd/README.md | 41 ++++++----- tests/integration/Todo.md | 2 + .../disabled_test_readme_schema.py | 72 +++++++++++++++++++ 8 files changed, 221 insertions(+), 82 deletions(-) create mode 100644 roles/driver-non-free/README.md create mode 100644 tests/integration/Todo.md create mode 100644 tests/integration/disabled_test_readme_schema.py diff --git a/roles/cleanup-certs/README.md b/roles/cleanup-certs/README.md index 79e17f0c..d256578a 100644 --- a/roles/cleanup-certs/README.md +++ b/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. \ No newline at end of file +- **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) diff --git a/roles/client-bluray-player/README.md b/roles/client-bluray-player/README.md index 2b1d4bb2..ed8181bf 100644 --- a/roles/client-bluray-player/README.md +++ b/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. \ No newline at end of file +## 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/) diff --git a/roles/docker-fusiondirectory/README.md b/roles/docker-fusiondirectory/README.md index ac676136..2dfbf3a5 100644 --- a/roles/docker-fusiondirectory/README.md +++ b/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) \ No newline at end of file +- [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) diff --git a/roles/driver-intel/README.md b/roles/driver-intel/README.md index 5b9f3a95..f654e000 100644 --- a/roles/driver-intel/README.md +++ b/roles/driver-intel/README.md @@ -1 +1,24 @@ -# driver-intel \ No newline at end of file +# 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) diff --git a/roles/driver-non-free/README.md b/roles/driver-non-free/README.md new file mode 100644 index 00000000..55f6c9bc --- /dev/null +++ b/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) diff --git a/roles/sshd/README.md b/roles/sshd/README.md index 2a0313a6..c6cf9ff2 100644 --- a/roles/sshd/README.md +++ b/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) diff --git a/tests/integration/Todo.md b/tests/integration/Todo.md new file mode 100644 index 00000000..bc2b187e --- /dev/null +++ b/tests/integration/Todo.md @@ -0,0 +1,2 @@ +# Todo +- Activate Disabled Test \ No newline at end of file diff --git a/tests/integration/disabled_test_readme_schema.py b/tests/integration/disabled_test_readme_schema.py new file mode 100644 index 00000000..ff4a6ec0 --- /dev/null +++ b/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()