mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2025-07-07 09:05:15 +02:00
Optimized READMEs
This commit is contained in:
parent
acad3f217f
commit
e61ef82f17
@ -2,24 +2,36 @@
|
|||||||
|
|
||||||
## Description
|
## 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
|
## 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.
|
- Installs the `certreap` cleanup tool using the `pkgmgr-install` role
|
||||||
|
- Deploys and configures a `cleanup-certs.cymais.service` systemd unit
|
||||||
## Purpose
|
- (Optionally) Sets up a recurring cleanup via a systemd timer using the `systemd-timer` role
|
||||||
|
- Integrates with `systemd-notifier` to send failure notifications
|
||||||
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.
|
- Ensures idempotent execution with a `run_once_cleanup_certs` flag
|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
- **Certificate Cleanup Tool Installation:** Installs `certreap` using [pkgmgr](https://github.com/kevinveenbirkenbach/package-manager)
|
- **Certificate Cleanup Tool Installation**
|
||||||
- **Systemd Service Configuration:** Deploys and manages `cleanup-certs.cymais.service`
|
Uses `pkgmgr-install` to install the `certreap` binary.
|
||||||
- **Systemd Timer Scheduling:** Optional timer via the `systemd-timer` role
|
|
||||||
- **Smart Execution Logic:** Ensures idempotent configuration using a `run_once` flag
|
|
||||||
|
|
||||||
## 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).
|
- **Systemd Timer Scheduling**
|
||||||
Commercial use is not permitted without explicit permission.
|
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)
|
||||||
|
|||||||
@ -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
|
## 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
|
- Uses the `community.general.pacman` module to install:
|
||||||
The `main.yml` file in this role consists of tasks that automate the installation of the following packages:
|
- `vlc` (media player with Blu-ray support)
|
||||||
1. **Install VLC and Blu-ray Software**:
|
- `libaacs` (AACS decryption library)
|
||||||
- `vlc`: A versatile media player that supports Blu-ray playback.
|
- `libbluray` (Blu-ray playback support library)
|
||||||
- `libaacs`: A library for Blu-ray disc encryption handling.
|
- Contains commented-out tasks for optional AUR packages (`aacskeys`, `libbdplus`) you can enable as needed.
|
||||||
- `libbluray`: A library for Blu-ray disc playback support.
|
- 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
|
- **VLC Installation**
|
||||||
For more in-depth information and guidance on Blu-ray playback and software configuration, the following resources can be consulted:
|
Installs `vlc` for general media and Blu-ray playback.
|
||||||
- [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/)
|
|
||||||
|
|
||||||
## Dependencies
|
- **AACS & BD+ Support**
|
||||||
This role depends on the `java` role, which ensures the Java runtime is available – a requirement for certain Blu-ray playback tools and functionalities.
|
Installs `libaacs` and `libbluray` to handle Blu-ray disc encryption and playback.
|
||||||
|
|
||||||
## Prerequisites
|
- **Optional AUR Packages**
|
||||||
- **Ansible**: Ansible must be installed on your system to use this role.
|
Drop-in tasks for `aacskeys` and `libbdplus` via AUR (commented out by default).
|
||||||
- **Arch Linux-based System**: Designed for Arch Linux distributions, using the `pacman` package manager.
|
|
||||||
|
|
||||||
## Running the Role
|
- **Idempotent Role**
|
||||||
To utilize this role:
|
Safe to run multiple times without unintended side effects.
|
||||||
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.
|
|
||||||
|
|
||||||
## Customization
|
- **Arch Linux–Optimized**
|
||||||
You can customize this role by enabling or adding additional tasks for other AUR packages related to Blu-ray playback as needed.
|
Leverages Pacman for fast and reliable package management.
|
||||||
|
|
||||||
## Support and Contributions
|
## Further Resources
|
||||||
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.
|
|
||||||
|
- [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/)
|
||||||
|
|||||||
@ -1,34 +1,29 @@
|
|||||||
# FusionDirectory (DRAFT)
|
# FusionDirectory
|
||||||
|
|
||||||
# Warning
|
|
||||||
This application isn't implemented yet
|
|
||||||
|
|
||||||
## Description
|
## 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
|
## Overview
|
||||||
|
|
||||||
Designed to simplify LDAP management, this role:
|
- Loads and templating of FusionDirectory-specific variables
|
||||||
- Loads necessary FusionDirectory-specific variables.
|
- Generates a `.env` file for the container environment
|
||||||
- Generates an environment file based on a template.
|
- Deploys the FusionDirectory container via Docker Compose
|
||||||
- Deploys a FusionDirectory Docker container via Docker Compose.
|
- Configures NGINX (via the `nginx-domain-setup` role) to expose the service
|
||||||
- Integrates with your existing central LDAP service.
|
- Integrates with your central LDAP server for authentication
|
||||||
|
|
||||||
## 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.
|
|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
- **Easy Deployment:** Minimal manual setup via pre-configured templates and variables.
|
- **Easy Deployment:** Runs FusionDirectory in Docker Compose with minimal manual steps
|
||||||
- **LDAP Integration:** Connects seamlessly with your existing central LDAP server.
|
- **LDAP Integration:** Connects to your existing LDAP backend for user management
|
||||||
- **Web Interface:** Provides an intuitive GUI for LDAP administration.
|
- **Environment Management:** Builds an environment file from role variables and templates
|
||||||
- **Docker Compose Integration:** Automates container creation and restart.
|
- **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**.
|
- [FusionDirectory Official Website](https://www.fusiondirectory.org/)
|
||||||
Learn more at [www.veen.world](https://www.veen.world)
|
- [FusionDirectory Docker Image (tiredofit/fusiondirectory)](https://hub.docker.com/r/tiredofit/fusiondirectory)
|
||||||
Part of the [CyMaIS Project](https://github.com/kevinveenbirkenbach/cymais)
|
- [Role Source & Documentation (CyMaIS)](https://github.com/kevinveenbirkenbach/cymais/tree/main/roles/docker-fusiondirectory)
|
||||||
License: [CyMaIS NonCommercial License (CNCL)](https://s.veen.world/cncl)
|
- [CyMaIS NonCommercial License (CNCL)](https://s.veen.world/cncl)
|
||||||
|
|||||||
@ -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)
|
||||||
|
|||||||
28
roles/driver-non-free/README.md
Normal file
28
roles/driver-non-free/README.md
Normal file
@ -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)
|
||||||
@ -1,26 +1,35 @@
|
|||||||
# SSHD
|
# sshd
|
||||||
|
|
||||||
## Description
|
## 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
|
## Overview
|
||||||
|
|
||||||
Optimized for secure remote access, this role:
|
- Renders `sshd_config.j2` into `/etc/ssh/sshd_config` with customizable options
|
||||||
- Generates an SSH daemon configuration file from a Jinja2 template.
|
- Sets file ownership (`root:root`) and permissions (`0644`)
|
||||||
- Sets appropriate ownership and permissions on the configuration file.
|
- Automatically reloads and restarts the SSH service via a Systemd handler
|
||||||
- Notifies systemd to restart the SSH daemon when changes are made.
|
- Uses a `run_once_sshd` fact to ensure idempotent execution
|
||||||
|
|
||||||
## 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.
|
|
||||||
|
|
||||||
## Features
|
## Features
|
||||||
|
|
||||||
- **SSH Configuration Deployment:** Creates an sshd_config file with best-practice settings.
|
- **Templated Configuration**
|
||||||
- **Systemd Integration:** Automatically restarts the SSH service upon configuration changes.
|
Delivers a Jinja2-based `sshd_config` with variables for debug logging and PAM support.
|
||||||
- **Security Enhancements:** Enforces secure defaults such as disabled root login and public key authentication.
|
|
||||||
|
|
||||||
## Other Resources
|
- **Security Defaults**
|
||||||
- https://www.google.com/search?client=firefox-b-d&q=sshd+why+to+deactivate+pam
|
- Disables password (`PasswordAuthentication no`) and root login (`PermitRootLogin no`)
|
||||||
- https://man7.org/linux/man-pages/man5/sshd_config.5.html
|
- 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)
|
||||||
|
|||||||
2
tests/integration/Todo.md
Normal file
2
tests/integration/Todo.md
Normal file
@ -0,0 +1,2 @@
|
|||||||
|
# Todo
|
||||||
|
- Activate Disabled Test
|
||||||
72
tests/integration/disabled_test_readme_schema.py
Normal file
72
tests/integration/disabled_test_readme_schema.py
Normal file
@ -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()
|
||||||
Loading…
x
Reference in New Issue
Block a user