Optimized mds

.gitignore

@@ -1,5 +1,4 @@
 site.retry
 *__pycache__
 docs/*
-!docs/.gitkeep
 venv

01_FEATURES.md

@@ -0,0 +1,19 @@
+# Features
+
+**CyMaIS - Cyber Master Infrastructure Solution** revolutionizes IT infrastructure management, making it simpler, safer, and more adaptable for businesses of all sizes. Here's how it can benefit your organization:
+
+1. **Effortless Setup and Management**: CyMaIS makes setting up and managing IT systems a breeze. Whether you're using Linux servers or personal computers, our tool automates the process, saving you time and effort.
+
+2. **Everything You Need in One Place**: From the basics of system setup to advanced features like VPN and Docker, CyMaIS provides a complete range of tools. It's like having an IT expert at your fingertips, offering solutions for every need.
+
+3. **Tailored to Your Business**: We understand that every business is unique. That's why CyMaIS is designed to be flexible, with customizable options to fit your specific requirements, whether you're a start-up, a growing business, or an established enterprise.
+
+4. **Stay Ahead with Proactive Monitoring**: Our tool doesn't just set up your IT infrastructure; it keeps it running smoothly. With automated updates and proactive monitoring, you can rest assured that your systems are always up-to-date and performing optimally.
+
+5. **Uncompromised Security and Reliability**: Protecting your data is our top priority. CyMaIS comes with robust security features and comprehensive backup solutions, giving you peace of mind that your business's sensitive information is safe and secure.
+
+6. **User-Friendly with Expert Support**: While familiarity with Docker, Linux, and Ansible enhances your experience with CyMaIS, it's not a requirement. Our comprehensive roles for servers and end-user PCs simplify the setup process. With these intuitive tools and our detailed guides, managing your IT infrastructure becomes more accessible, even if you're not a seasoned IT professional. Plus, our support team is always ready to assist you, bridging any knowledge gaps and ensuring a smooth operation of your systems.
+
+7. **Open Source Trust and Transparency**: With CyMaIS, you benefit from the reliability and security of open-source software. Our tool is transparent, community-driven, and aligned with the highest standards of software ethics and security.
+
+CyMaIS is more than just an IT solution; it's a commitment to empowering your business with the technology it needs to thrive in today’s digital landscape, effortlessly and securely.

02_VISION.md

@@ -1,4 +1,4 @@
-# Vision Statement
+# Vision
 
 At the heart of our endeavor lies the creation of an unparalleled tool, designed to revolutionize the way IT infrastructure is deployed and managed in businesses of all scales and across various industries. Our vision is to develop a fully automated solution capable of establishing a secure and infinitely scalable corporate IT infrastructure.
 
@@ -9,9 +9,3 @@ We envision a future where businesses are no longer constrained by the complexit
 Our commitment is to break down barriers to advanced IT infrastructure, democratizing access to high-level technology solutions. By harnessing the power of Open Source, our solution will not only uphold the highest standards of security and scalability but also foster a community-driven approach to continuous improvement and innovation.
 
 In essence, our vision is to redefine the paradigm of IT infrastructure deployment, making it a swift, secure, and scalable journey for every business, and setting a new benchmark in the industry for efficiency and reliability.
-
----
-
-Kevin Veen-Birkenbach  
-Berlin  
-2023-12-13

03_INSTALLATION.md

@@ -0,0 +1,9 @@
+# Installation
+
+CyMaIS can be easily installed using [Kevin's Package Manager](https://github.com/kevinveenbirkenbach/package-manager). Once you have the package manager set up, simply run:
+
+```bash
+pkgmgr install cymais
+```
+
+This command will install CyMaIS on your system with the alias **cymais**.

04_SETUP.md

@@ -0,0 +1,127 @@
+# Setup Guide
+
+This guide explains how to deploy and manage the Cyber Master Infrastructure Solution (CyMaIS) using Ansible. CyMaIS is based on a collection of playbooks and an inventory (computer-inventory) that defines your servers and personal computers. The playbooks use different “modes” to control behavior such as updates, backups, resets, and cleanup tasks. This document outlines how to use Ansible Vault, describes the various operating modes, and shows example commands to run the playbooks.
+
+---
+
+## Prerequisites
+
+- **Ansible Installed:** Ensure that Ansible is installed on your control node.
+- **Inventory File:** Have an inventory file that lists your servers and PCs. (Paths in examples are general; adjust them to your environment.)
+- **Vault Password File (Optional):** Prepare a file with your vault password if you prefer not to enter it interactively.
+
+---
+
+## Ansible Vault Basics
+
+CyMaIS uses Ansible Vault to protect sensitive data (e.g. passwords). Use these common commands:
+
+### Edit an Encrypted File
+```bash
+ansible-vault edit <filename.yml> --vault-password-file <your-vault-pass-file>
+```
+
+### Decrypt a File
+```bash
+ansible-vault decrypt <filename.yml> --vault-password-file <your-vault-pass-file>
+```
+
+### Encrypt a File
+```bash
+ansible-vault encrypt <filename.yml> --vault-password-file <your-vault-pass-file>
+```
+
+### Encrypt a String
+```bash
+ansible-vault encrypt_string --vault-password-file <your-vault-pass-file> 'example' --name 'test'
+```
+
+---
+
+## Operating Modes
+
+CyMaIS playbooks support several modes that control which tasks are executed:
+
+- **mode_reset** (`true`/`false`):  
+  When enabled, cleans up all CyMaIS-related files. Use this mode when you need to reinitialize the system completely. _Note: Run the full playbook when using reset mode._
+
+- **mode_test** (`true`/`false`):  
+  Executes test routines instead of production routines. Useful for staging or validation.
+
+- **mode_update** (`true`/`false`):  
+  Enables update tasks to upgrade packages and Docker images. Set to `false` if you want to skip updates.
+
+- **mode_backup** (`true`/`false`):  
+  Activates backup procedures before applying updates. This ensures your data is backed up prior to any changes.
+
+- **mode_cleanup** (`true`/`false`):  
+  Performs cleanup of unused files and configurations (e.g., removing obsolete certificates or Docker volumes).
+
+These modes are defined in your group variables (e.g., in a file like `group_vars/all/01_modes.yml`) and can be overridden via extra variables when running playbooks.
+
+---
+
+## Deploying on Servers
+
+To deploy CyMaIS on your servers, use an Ansible playbook that targets your server inventory. Below are some example commands:
+
+### Configure All Servers
+```bash
+ansible-playbook -i /path/to/your/inventory/servers.yml "$(pkgmgr path cymais)playbook.servers.yml" --ask-vault-pass
+```
+
+### Configure a Specific Server
+For example, to target a server named `galaxyserver`:
+```bash
+ansible-playbook -i /path/to/your/inventory/servers.tmp "$(pkgmgr path cymais)playbook.servers.yml" --limit galaxyserver --ask-vault-pass
+```
+
+### Run in Temporary Mode Without Update
+```bash
+ansible-playbook -i /path/to/your/inventory/servers.tmp "$(pkgmgr path cymais)playbook.servers.yml" --limit galaxyserver -e "mode_update=false" --ask-vault-pass
+```
+
+### Run Without Update and Backup
+```bash
+ansible-playbook -i /path/to/your/inventory/servers.tmp "$(pkgmgr path cymais)playbook.servers.yml" --limit galaxyserver -e "mode_update=false" -e "mode_backup=false" --ask-vault-pass
+```
+
+### Run with Cleanup and Debug (Using a Vault Password File)
+```bash
+ansible-playbook -i /path/to/your/inventory/servers.tmp "$(pkgmgr path cymais)playbook.servers.yml" --limit galaxyserver -e "mode_update=false" -e "mode_backup=false" -e "mode_cleanup=true" -e "enable_debug=true" -v --vault-password-file /path/to/your/vault_pass.txt
+```
+
+---
+
+## Using a Vault Password File
+
+To avoid entering your vault password interactively every time, use the `--vault-password-file` option:
+```bash
+--vault-password-file /path/to/your/vault_pass.txt
+```
+Ensure the vault password file is stored securely.
+
+---
+
+## Password Generation
+
+You can generate a secure random password and encrypt it with Ansible Vault. For example:
+```bash
+ansible-vault encrypt_string "$(cat /dev/urandom | tr -dc 'A-Za-z0-9' | head -c 32)" --vault-password-file /path/to/your/vault_pass.txt | xclip -selection clipboard
+```
+This command generates a 32-character alphanumeric password, encrypts it, and copies the result to your clipboard.
+
+---
+
+## Final Notes
+
+- **Customizing Paths and Variables:**  
+  All file paths and configuration variables are defined in group variables (e.g., `group_vars/all/*.yml`) and role variable files. Adjust these to suit your deployment environment.
+
+- **Combining Modes:**  
+  The different modes (reset, test, update, backup, cleanup) can be combined by passing extra variables (using `-e`) on the command line. This flexibility allows you to tailor the playbook run to your current needs.
+
+- **Debugging:**  
+  If you need more verbose output or troubleshooting information, add the `-v` (or `-vvv`) option when running the playbook.
+
+This guide should give you a comprehensive starting point for managing your infrastructure with CyMaIS. For further details, consult the individual role documentation and the accompanying repository README files.

05_ENTERPRISE.md

@@ -0,0 +1,14 @@
+# Enterprise Solutions
+<img src="https://cybermaster.space/wp-content/uploads/sites/7/2023/11/FVG_8364BW-scaled.jpg" width="300" style="float: right; margin-left: 30px;">
+
+My name is Kevin Veen-Birkenbach and I'm glad to assist you in the implementation of your secure and scalable IT infrastrucutre solution with CyMaIS.
+
+My expertise in server administration, digital corporate infrastructure, custom software, and information security, all underpinned by a commitment to Open Source solutions, guarantees that your IT setup meets the highest industry standards.
+
+Discover how CyMaIS can transform your IT landscape. 
+
+Contact me for more details:
+
+🌍 Website: [www.CyberMaster.Space](https://cybermaster.space)<br />
+📧 Email: [kevin@veen.world](mailto:kevin@veen.world)<br />
+☎️ Phone: [+ 49 178 179 80 23](tel:00491781798023)

06_DONATE.md

@@ -0,0 +1,9 @@
+# Support Us
+
+CyMaIS is a transformative tool designed to redefine IT infrastructure setup for organizations and individuals alike. Your contributions directly support the ongoing development and innovation behind CyMaIS, ensuring that it continues to grow and serve its community effectively.
+
+If you enjoy using CyMaIS and would like to contribute to its improvement, please consider donating. Every contribution, no matter the size, helps us maintain and expand this project.
+
+[![GitHub Sponsors](https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-blue?logo=github)](https://github.com/sponsors/kevinveenbirkenbach) [![Patreon](https://img.shields.io/badge/Support-Patreon-orange?logo=patreon)](https://www.patreon.com/c/kevinveenbirkenbach) [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20Coffee-Funding-yellow?logo=buymeacoffee)](https://buymeacoffee.com/kevinveenbirkenbach) [![PayPal](https://img.shields.io/badge/Donate-PayPal-blue?logo=paypal)](https://s.veen.world/paypaldonate)
+
+Thank you for your support!

CODE_OF_CONDUCT.md

@@ -0,0 +1,38 @@
+# Code of Conduct
+
+In order to foster a welcoming, open, and respectful community for everyone, we expect all contributors and participants in the CyMaIS project to abide by the following Code of Conduct.
+
+## Our Pledge
+
+We are committed to creating a friendly, safe, and inclusive environment for all members of our community—regardless of age, race, gender, sexual orientation, disability, religion, or any other status. We pledge to treat everyone with respect and courtesy.
+
+## Expected Behavior
+
+- **Be Respectful:** Communicate and collaborate with courtesy, empathy, and respect. Listen to others’ opinions and value their input.
+- **Be Inclusive:** Welcome contributions from all backgrounds and experiences. Encourage diverse perspectives and engage in constructive dialogue.
+- **Practice Professionalism:** Use clear and professional language in all communications. Maintain focus on ideas and project goals rather than personal attributes.
+- **Be Collaborative:** Foster an environment where everyone can contribute freely. Offer help and constructive feedback, and work together towards common goals.
+- **Respect Boundaries:** Understand and honor others’ personal and professional boundaries.
+
+## Unacceptable Behavior
+
+- **Harassment and Discrimination:** Any form of harassment, hate speech, or discriminatory behavior will not be tolerated.
+- **Intimidation and Threats:** Verbal or written intimidation, threats, or aggressive behavior toward any community member is strictly prohibited.
+- **Personal Attacks:** Avoid personal insults or demeaning comments toward any contributor or participant.
+- **Exclusionary Behavior:** Do not engage in behaviors or comments that might exclude or isolate community members.
+
+## Reporting and Enforcement
+
+If you experience or witness any behavior that violates this Code of Conduct, please report it promptly. Reports should be sent to kevin@veen.world. All reports will be treated with discretion and confidentiality.
+
+Our project maintainers and community leaders will review all reports and take appropriate action, which may include warnings, temporary suspension, or permanent expulsion from the community if necessary.
+
+## Scope
+
+This Code of Conduct applies to all spaces managed by the CyMaIS project, including GitHub repositories, mailing lists, chat rooms, and other communication channels.
+
+## Acknowledgment
+
+By participating in the CyMaIS project, you agree to adhere to this Code of Conduct. We appreciate your cooperation in helping us build a positive and productive community.
+
+Thank you for contributing to a safe and inclusive CyMaIS community!

CONTRIBUTING.md

@@ -0,0 +1,57 @@
+# Contributing
+
+Thank you for your interest in contributing to CyMaIS! We welcome contributions from the community to help improve and enhance this project. Your input makes the project stronger and more adaptable to a wide range of IT infrastructure needs.
+
+## How to Contribute
+
+There are several ways you can help:
+- **Reporting Issues:** Found a bug or have a feature request? Please open an issue on our [GitHub Issues page](https://github.com/your-repo-link/issues) with a clear description and steps to reproduce the problem.
+- **Code Contributions:** If you'd like to contribute code, fork the repository, create a new branch for your feature or bug fix, and submit a pull request. Ensure your code adheres to our coding style and includes tests where applicable.
+- **Documentation:** Improving the documentation is a great way to contribute. Whether it's clarifying an existing section or adding new guides, your contributions help others understand and use CyMaIS effectively.
+- **Financial Contributions:** If you appreciate CyMaIS and want to support its ongoing development, consider making a financial contribution. For more details, please see our [06_DONATE.md](06_DONATE.md) file.
+
+## Code of Conduct
+
+All contributors are expected to adhere to our [Code of Conduct](CODE_OF_CONDUCT.md). Please review it to ensure that our community remains welcoming and respectful.
+
+## Pull Request Guidelines
+
+Before submitting a pull request, please ensure that:
+- Your code is well-documented and follows the project's coding standards.
+- All tests pass and, if necessary, new tests are added to cover your changes.
+- The commit messages are clear and descriptive.
+- The relevant documentation is updated to reflect your changes.
+
+## Reporting Issues
+
+When reporting an issue, please include:
+- A descriptive title and detailed explanation.
+- Steps to reproduce the issue.
+- Information about your environment (e.g., operating system, Docker version, Ansible version, etc.).
+- Any relevant logs or error messages.
+
+## Coding Style
+
+Please follow these guidelines when contributing code:
+- Write clean, readable code that integrates with the existing codebase.
+- Use descriptive names for variables and functions.
+- Comment your code where necessary, especially in complex sections.
+- Format your code according to the project's style guidelines.
+
+## License and Commercial Use
+
+CyMaIS is primarily designed for private use. Commercial use of CyMaIS is not permitted without a proper licensing agreement. By contributing to this project, you agree that your contributions will be licensed under the same terms as the rest of the project.
+
+## Getting Started
+
+1. **Fork** the repository on GitHub.
+2. **Clone** your fork to your local machine.
+3. **Create** a new branch for your feature or bug fix.
+4. **Implement** your changes and commit them with clear messages.
+5. **Push** your branch to GitHub and open a pull request.
+
+## Community and Support
+
+If you have any questions or need help, feel free to open an issue or join our community discussions. We appreciate your efforts and are here to support you.
+
+Thank you for contributing to CyMaIS and helping us build a better, more efficient IT infrastructure solution!

LICENSE.md

@@ -1,4 +1,6 @@
-# CyMaIS NonCommercial License (CNCL)
+# License Agreement 
+
+**CyMaIS NonCommercial License (CNCL)**
 
 ## Definitions
 - **"Software":** Refers to *"[CyMaIS - Cyber Master Infrastructure Solution](https://cymais.cloud/)"* and its associated source code.

README.md

@@ -1,65 +1,48 @@
 # CyMaIS - Cyber Master Infrastructure Solution
-[![GitHub Sponsors](https://img.shields.io/badge/Sponsor-GitHub%20Sponsors-blue?logo=github)](https://github.com/sponsors/kevinveenbirkenbach) [![Patreon](https://img.shields.io/badge/Support-Patreon-orange?logo=patreon)](https://www.patreon.com/c/kevinveenbirkenbach) [![Buy Me a Coffee](https://img.shields.io/badge/Buy%20me%20a%20Coffee-Funding-yellow?logo=buymeacoffee)](https://buymeacoffee.com/kevinveenbirkenbach) [![PayPal](https://img.shields.io/badge/Donate-PayPal-blue?logo=paypal)](https://s.veen.world/paypaldonate)
-
-
-<img src="https://cybermaster.space/wp-content/uploads/sites/7/2023/12/logo_cymais.png" width="300" style="float: right; margin-left: 10px;">
 
 Welcome to CyMaIS (Cyber Master Infrastructure Solution), a transformative tool designed to redefine IT infrastructure setup for organizations and individuals alike. 
 
 At its core, CyMaIS leverages the power of Docker, Linux, and Ansible to offer a streamlined, automated solution for deploying and managing IT systems. 
 
+<img src="https://cybermaster.space/wp-content/uploads/sites/7/2023/12/logo_cymais.png" width="300" style="float: right; margin-left: 10px;">
+
 Whether you're a small startup, a growing enterprise, or an individual seeking efficient IT management, CyMaIS provides a comprehensive suite of tools that cater to a wide range of needs. From simple system setups to complex server configurations and end-user PC management, CyMaIS simplifies the entire process. 
 
 Our intuitive interface, coupled with in-depth documentation, makes it accessible to both tech-savvy users and those with limited IT experience. 
 
 With CyMaIS, setting up a secure, scalable, and robust IT infrastructure is not just faster and easier, but also aligned with the best industry practices, ensuring that your organization stays ahead in the ever-evolving digital landscape.
 
-## Vision
-Our project is anchored in the vision of transforming IT infrastructure deployment into a seamless, secure, and scalable experience. 
+## Documentation
 
-We are committed to developing a fully automated solution that enables businesses of any size and industry to set up a 100% secure and infinitely scalable IT infrastructure in just 24 hours. 
+Explore the key documents for detailed information about CyMaIS:
 
-Leveraging the power of Open Source, our tool not only promises to uphold the highest standards of security and adaptability but also embodies a commitment to transparency and community-driven innovation. 
+- [Features](01_FEATURES.md)  
+  *Overview of the core features and capabilities of CyMaIS.*
 
-This is not just a step towards simplifying IT management – it's a leap towards democratizing access to advanced technology, ensuring every business can quickly adapt and thrive in the digital age.
+- [Vision](02_VISION.md)  
+  *Learn about the vision and long-term goals behind CyMaIS.*
 
-For a deeper understanding of our goals and the ethos driving our project, we invite you to explore our detailed **[Vision Statement](./VISION.md)**. Here, you'll find the cornerstone principles that guide our development process and our commitment to making a lasting impact in the realm of IT infrastructure.
+- [Installation](03_INSTALLATION.md)  
+  *Step-by-step instructions for installing the system and its dependencies.*
 
-## Key Benefits of CyMaIS for Your Business
+- [Setup](04_SETUP.md)  
+  *Detailed procedures for configuring and deploying CyMaIS.*
 
-**CyMaIS - Cyber Master Infrastructure Solution** revolutionizes IT infrastructure management, making it simpler, safer, and more adaptable for businesses of all sizes. Here's how it can benefit your organization:
+- [Enterprise](05_ENTERPRISE.md)  
+  *Guidance and best practices for enterprise deployments.*
 
-1. **Effortless Setup and Management**: CyMaIS makes setting up and managing IT systems a breeze. Whether you're using Linux servers or personal computers, our tool automates the process, saving you time and effort.
+- [Donate](06_DONATE.md)  
+  *Information on how to support and donate to the CyMaIS project.*
 
-2. **Everything You Need in One Place**: From the basics of system setup to advanced features like VPN and Docker, CyMaIS provides a complete range of tools. It's like having an IT expert at your fingertips, offering solutions for every need.
+- [Code of Conduct](CODE_OF_CONDUCT.md)  
+  *Our guidelines to ensure a respectful and collaborative community.*
 
-3. **Tailored to Your Business**: We understand that every business is unique. That's why CyMaIS is designed to be flexible, with customizable options to fit your specific requirements, whether you're a start-up, a growing business, or an established enterprise.
+- [Contributing](CONTRIBUTING.md)  
+  *Learn how to contribute to CyMaIS.*
 
-4. **Stay Ahead with Proactive Monitoring**: Our tool doesn't just set up your IT infrastructure; it keeps it running smoothly. With automated updates and proactive monitoring, you can rest assured that your systems are always up-to-date and performing optimally.
+- [License](LICENSE.md)  
+  *Legal information regarding the use and distribution of CyMaIS.*
 
-5. **Uncompromised Security and Reliability**: Protecting your data is our top priority. CyMaIS comes with robust security features and comprehensive backup solutions, giving you peace of mind that your business's sensitive information is safe and secure.
+---
 
-6. **User-Friendly with Expert Support**: While familiarity with Docker, Linux, and Ansible enhances your experience with CyMaIS, it's not a requirement. Our comprehensive roles for servers and end-user PCs simplify the setup process. With these intuitive tools and our detailed guides, managing your IT infrastructure becomes more accessible, even if you're not a seasoned IT professional. Plus, our support team is always ready to assist you, bridging any knowledge gaps and ensuring a smooth operation of your systems.
-
-7. **Open Source Trust and Transparency**: With CyMaIS, you benefit from the reliability and security of open-source software. Our tool is transparent, community-driven, and aligned with the highest standards of software ethics and security.
-
-CyMaIS is more than just an IT solution; it's a commitment to empowering your business with the technology it needs to thrive in today’s digital landscape, effortlessly and securely.
-
-## Professional CyMaIS Implementation
-<img src="https://cybermaster.space/wp-content/uploads/sites/7/2023/11/FVG_8364BW-scaled.jpg" width="300" style="float: right; margin-left: 30px;">
-
-My name is Kevin Veen-Birkenbach and I'm glad to assist you in the implementation of your secure and scalable IT infrastrucutre solution with CyMaIS.
-
-My expertise in server administration, digital corporate infrastructure, custom software, and information security, all underpinned by a commitment to Open Source solutions, guarantees that your IT setup meets the highest industry standards.
-
-Discover how CyMaIS can transform your IT landscape. 
-
-Contact me for more details:
-
-🌍 Website: [www.CyberMaster.Space](https://cybermaster.space)<br />
-📧 Email: [kevin@veen.world](mailto:kevin@veen.world)<br />
-☎️ Phone: [+ 49 178 179 80 23](tel:00491781798023)
-
-## License
-
-This project is licensed from Kevin Veen-Birkenbach. The full license is available in the [LICENSE.md](./LICENSE.md) of this repository. 
+Feel free to explore the individual documents for more detailed information. Enjoy using CyMaIS, and thank you for your interest in our project!

group_vars/README.md

@@ -0,0 +1 @@
+# Configuration

index.rst

@@ -1,10 +1,4 @@
-Cyber Master Infrastructure Solution documentation
-===========================================================
+About
+===============================
 
-.. toctree::
-   :maxdepth: 1
-   :caption: About CyMaIS:
-   :glob:
-
-   *
-   roles/index.rst
+.. markdown-include:: README.md

roles/README.md

@@ -1,2 +0,0 @@
-# Echo
-Hello World

roles/backup-data-to-usb/README.md

@@ -4,7 +4,7 @@
 
 This Ansible role automates data backups to a swappable USB device. It triggers the backup process automatically when the USB is mounted, allowing for customizable source and destination paths and integrating with systemd for reliable execution.
 
-## 📌 Overview
+## Overview
 
 Optimized for Archlinux, this role ensures that backups are performed consistently with minimal manual intervention. It leverages efficient synchronization methods and provides a seamless integration with systemd to manage the backup service.
 

roles/backup-directory-validator/README.md

@@ -4,7 +4,7 @@
 
 This Ansible role pulls the [directory-validator](https://github.com/kevinveenbirkenbach/directory-validator.git) repository to a predefined location. It is used by the backup-docker-to-local and cleanup-failed-docker-backups roles to verify whether backups have been successfully created.
 
-## 📌 Overview
+## Overview
 
 The role retrieves the latest version of the directory-validator from its Git repository and installs it into the designated folder (configured via the `backup_directory_validator_folder` variable). A fact is set to ensure that the repository is pulled only once per playbook run.
 

roles/backup-docker-to-local/README.md

@@ -4,7 +4,7 @@
 
 This Ansible role automates the process of backing up Docker volumes to a local folder. It pulls the [backup-docker-to-local repository](https://github.com/kevinveenbirkenbach/backup-docker-to-local.git), installs required software, configures systemd services for both standard and "everything" backup modes, and seeds backup database entries as needed.
 
-## 📌 Overview
+## Overview
 
 Optimized for Archlinux, this role ensures that Docker volume backups are performed reliably with minimal manual intervention. It integrates with several dependent roles to verify backup success and manage related tasks, including:
 - [backup-directory-validator](../backup-directory-validator/) – Validates backup directories.

roles/backup-remote-to-local/README.md

@@ -4,7 +4,7 @@
 
 This role pulls backups from a remote server and stores them locally using rsync with retry logic. It is designed to retrieve remote backup data and integrate with your overall backup scheme.
 
-## 📌 Overview
+## Overview
 
 Optimized for Archlinux, this role is a key component of a comprehensive backup system. It works in conjunction with other roles to ensure that backup data is collected, verified, and maintained. The role uses a Bash script to pull backups, manage remote connections, and handle incremental backup creation.
 

roles/backups-provider-user/README.md

@@ -4,7 +4,7 @@
 
 This role sets up a dedicated backup user (`backup`) for performing secure backup operations. It creates the user, configures a restricted SSH environment with a custom `authorized_keys` template and an SSH wrapper script, and grants necessary sudo rights for executing rsync. This configuration helps ensure controlled and secure access specifically for backup processes.
 
-## 📌 Overview
+## Overview
 
 The role is a critical component in a secure backup scheme. By isolating backup operations to a dedicated user, it minimizes the risk of unauthorized actions. The role configures the SSH environment so that only specific, allowed commands can be executed, and it sets up passwordless sudo rights for rsync, ensuring smooth and secure backup operations.
 

roles/backups-provider/README.md

@@ -4,7 +4,7 @@
 
 This role sets up and manages the host as a backup provider. It establishes the framework for secure backup operations and integrates with other roles to facilitate reliable backup data management.
 
-## 📌 Overview
+## Overview
 
 Optimized for automated backup processes, this role:
 - Configures the host to provide backup services.

roles/categories.rst

@@ -1,4 +1,4 @@
-Applications by Category
+Application Categories
 =========================
 
 .. roles-overview::

roles/cleanup-backups-service/README.md

@@ -4,7 +4,7 @@
 
 This role automates the cleanup of old backups by executing a Python script that deletes outdated backup versions based on disk usage thresholds. It ensures that backup storage does not exceed a defined usage percentage.
 
-## 📌 Overview
+## Overview
 
 Optimized for effective disk space management, this role:
 - Installs required packages (e.g. [lsof](https://en.wikipedia.org/wiki/Lsof) and [psutil](https://pypi.org/project/psutil/)) using pacman.

roles/cleanup-backups-timer/README.md

@@ -4,7 +4,7 @@
 
 This role sets up a systemd timer to schedule the periodic cleanup of old backups. It leverages the cleanup-backups-service role to perform the actual cleanup operation.
 
-## 📌 Overview
+## Overview
 
 Optimized for automated maintenance, this role:
 - Sets a fact for the service name.

roles/cleanup-disc-space/README.md

@@ -4,7 +4,7 @@
 
 This role frees disk space by executing a script that cleans up temporary files, clears package caches, and optionally cleans up backup directories and Docker resources when disk usage exceeds a specified threshold.
 
-## 📌 Overview
+## Overview
 
 Optimized for efficient storage management, this role:
 - Creates a directory for disk cleanup scripts.

roles/cleanup-failed-docker-backups/README.md

@@ -4,7 +4,7 @@
 
 This role cleans up failed Docker backups by pulling a [Git repository](https://github.com/kevinveenbirkenbach/cleanup-failed-docker-backups) that contains cleanup scripts and configuring a systemd service to execute them. It ensures that failed or incomplete backups are removed to free up disk space and maintain a healthy backup environment.
 
-## 📌 Overview
+## Overview
 
 Optimized for backup maintenance, this role:
 - Clones the cleanup-failed-docker-backups repository.

roles/client-wireguard-behind-firewall/README.md

@@ -4,7 +4,7 @@
 
 This role adapts iptables rules to enable proper connectivity for a WireGuard client running behind a NAT or firewall. It ensures that traffic is forwarded correctly by applying necessary masquerading rules.
 
-## 📌 Overview
+## Overview
 
 Optimized for environments with network address translation (NAT), this role:
 - Executes shell commands to modify iptables rules.

roles/client-wireguard/README.md

@@ -4,7 +4,7 @@
 
 This role manages WireGuard on a client system. It sets up essential services and scripts to configure and optimize WireGuard connectivity. Additionally, it provides a link to an Administration document for creating client keys.
 
-## 📌 Overview
+## Overview
 
 Optimized for client configurations, this role:
 - Deploys a systemd service (`set-mtu.cymais.service`) and its associated script to set the MTU on specified network interfaces.

roles/docker-central-database/README.md

@@ -4,7 +4,7 @@ This Ansible role provides the necessary tasks, files, templates, and variables
 
 ---
 
-## 📌 Overview
+## Overview
 
 - **Database Variables**  
   Defined in [./vars/database.yml](./vars/database.yml), these variables include:

roles/docker-friendica/README.md

@@ -2,7 +2,7 @@
 
 This role manages the setup, reset, and maintenance of a Friendica instance running with Docker.
 
-## 📌 Overview
+## Overview
 
 Friendica is a decentralized social networking platform. This role helps manage Friendica in a containerized environment with Docker and provides tools for debugging, resetting, and maintaining the installation.
 

roles/docker-gitlab/README.md

@@ -1,6 +1,6 @@
 # Docker-GitLab Ansible Role
 
-## 📌 Overview
+## Overview
 This Ansible role is designed for setting up and managing a GitLab server running in a Docker container. It automates the process of installing GitLab, configuring its environment, and managing dependencies such as a PostgreSQL database and an Nginx reverse proxy.
 
 ## Features

roles/docker-mariadb/README.md

@@ -1,6 +1,6 @@
 # MariaDB Docker Ansible Role
 
-## 📌 Overview
+## Overview
 This Ansible role facilitates the deployment of a MariaDB server using Docker. It is designed to ensure ease of installation and configuration, with the flexibility to adapt to different environments.
 
 ## Features

roles/docker-mastodon/README.md

@@ -1,6 +1,6 @@
 # 🚀 Docker Mastodon with OIDC Support
 
-## 📌 Overview
+## Overview
 This project provides a **Docker-based setup for Mastodon**, including full **OIDC (OpenID Connect) authentication support**. It is maintained by **[Kevin Veen-Birkenbach](https://www.veen.world)**.
 
 ## Credits 📝

roles/docker-matrix-ansible/README.md

@@ -1,6 +1,6 @@
 # Docker Setup Matrix via Ansible
 
-## 📌 Overview
+## Overview
 
 This document serves as the README for the `docker-ansible-matrix` role, a part of the `CyMaIS` project. This role automates the deployment of a Matrix server using Ansible. 
 

roles/docker-matrix-compose/README.md

@@ -1,6 +1,6 @@
 # Docker-Matrix Role README
 
-## 📌 Overview
+## Overview
 
 This document serves as the README for the `docker-matrix` role, a part of the `CyMaIS` project. This role automates the deployment of a Matrix server using Docker. This role was developed by [Kevin Veen-Birkenbach](https://www.veen.world/)
 

roles/docker-oauth2-proxy/README.md

@@ -2,7 +2,7 @@
 
 Welcome to the **Docker OAuth2 Proxy Role**! 🌟 This role contains helper functions to set up an OAuth2 proxy using [OAuth2 Proxy](https://github.com/oauth2-proxy/oauth2-proxy), a tool designed to secure applications by protecting them with OAuth2 authentication. 💡
 
-## 📌 Overview
+## Overview
 
 The OAuth2 Proxy is used to shield specific web applications from unauthorized access by requiring users to authenticate via an external identity provider, such as Keycloak. This role simplifies the setup process by providing templated configurations and tasks to integrate the OAuth2 Proxy with Docker Compose and Keycloak.
 

roles/docker-openproject/README.md

@@ -1,6 +1,6 @@
 # OpenProject Role
 
-## 📌 Overview
+## Overview
 
 This role is designed to deploy the [OpenProject](https://www.openproject.org/) application using Docker. It includes tasks for setting up the environment, pulling the Docker repository, and configuring a reverse proxy with Nginx. It was developed by [Kevin Veen-Birkenbach](https://www.veen.world/)
 

roles/docker-postgres/README.md

@@ -1,6 +1,6 @@
 # Docker-Postgres Ansible Role
 
-## 📌 Overview
+## Overview
 This Ansible role is designed to deploy a PostgreSQL database using Docker. It includes tasks for setting up a Docker network, installing PostgreSQL in a Docker container, and initializing the database with a specified user and database.
 
 ## Role Variables

roles/docker-sphinx/README.md

@@ -4,7 +4,7 @@
 
 This Ansible role automates the building and deployment of Sphinx documentation using Docker. It pulls the CyMaIS repository, builds the documentation with Sphinx, and serves the generated HTML files via a lightweight HTTP server.
 
-## 📌 Overview
+## Overview
 
 Optimized for containerized environments, this role ensures that your documentation is consistently built and deployed with minimal manual intervention. It leverages Docker and Docker Compose for reproducible builds, enabling dynamic configuration of source and output directories.
 

roles/health-nginx/README.md

@@ -1,6 +1,6 @@
 # health-nginx
 
-## 📌 Overview
+## Overview
 `health-nginx` is an Ansible role designed to send health reports for nginx configurations. It leverages Python scripting to check the status of nginx server configurations and reports back any issues. This role is especially useful for maintaining the health of nginx servers in a dynamic environment.
 
 ## Requirements

roles/hunspell/tasks/README.md

@@ -1,6 +1,6 @@
 # Hunspell
 
-## 📌 Overview
+## Overview
 This README accompanies the Hunspell Playbook, located within the `cymais` repository. The playbook is focused on installing Hunspell, a widely-used spell checker, along with various language packages to enhance its functionality.
 
 ## Playbook Contents

roles/index.rst

@@ -1,11 +1,5 @@
-Applications and Roles
-===========================================================
+Applications
+=====================================
 
-.. markdown-include:: README.md
-
-.. toctree::
-   :maxdepth: 1
-   :caption: About CyMaIS:
-   :glob:
-
-   *.rst
+- :doc:`Glosar <glosar>`
+- :doc:`Categories <categories>`

roles/java/README.md

@@ -1,6 +1,6 @@
 # Java
 
-## 📌 Overview
+## Overview
 This README file is for the Java role, which is part of the `cymais`. The role is specifically designed to automate the installation of Java on a system, focusing on the OpenJDK 11 version.
 
 ## Contents of the role

roles/nginx-redirect-www/README.md

@@ -1,6 +1,6 @@
 # nginx-redirect-www
 
-## 📌 Overview
+## Overview
 The `nginx-redirect-www` role is designed to automate the process of setting up redirects from `www.domain.tld` to `domain.tld` for all domains and subdomains configured within the `{{nginx.directories.http.servers}}` directory. This role dynamically identifies configuration files following the pattern `*domain.tld.conf` and creates corresponding redirection rules.
 
 ## Role Description

roles/pc-administrator-tools/README.md

@@ -1,6 +1,6 @@
 # PC-Bluray-Player-Tools Role
 
-## 📌 Overview
+## Overview
 Welcome to the `pc-bluray-player-tools` 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

roles/pc-designer-tools/README.md

@@ -1,6 +1,6 @@
 # PC-Designer-Tools Role
 
-## 📌 Overview
+## Overview
 This README is associated with the `pc-designer-tools` role, part of the `cymais` repository. This role focuses on setting up a suite of essential design tools on personal computers, catering specifically to the needs of graphic designers, illustrators, and digital artists.
 
 ## Role Contents

roles/pc-developer-tools-arduino/README.md

@@ -1,6 +1,6 @@
 # PC-Developer-Tools-Arduino Role
 
-## 📌 Overview
+## Overview
 This README file is for the `pc-developer-tools-arduino` role, a specialized component of the `cymais` repository. This role is specifically crafted for setting up Arduino development tools on personal computers.
 
 ## Role Details

roles/pc-developer-tools-bash/README.md

@@ -1,6 +1,6 @@
 # PC-Developer-Tools-Bash Role
 
-## 📌 Overview
+## Overview
 This README accompanies the `pc-developer-tools-bash` role within the `cymais` repository. This role is dedicated to equipping personal computers with essential tools for Bash scripting and development.
 
 ## Role Contents

roles/pc-developer-tools-java/README.md

@@ -1,6 +1,6 @@
 # PC-Developer-Tools-Java Role
 
-## 📌 Overview
+## Overview
 Welcome to the `pc-developer-tools-java` role, a part of the `cymais` repository. This role is specifically designed for setting up Java development tools on personal computers. It is an essential component for Java developers, providing the necessary tools and dependencies for efficient Java development.
 
 ## Role Dependencies

roles/pc-developer-tools-php/README.md

@@ -1,6 +1,6 @@
 # PC-Developer-Tools-PHP Role
 
-## 📌 Overview
+## Overview
 This README document is for the `pc-developer-tools-php` role within the `cymais` repository. This role is specifically designed to facilitate the setup of PHP development tools on personal computing environments.
 
 ## Role Contents

roles/pc-developer-tools-python/README.md

@@ -1,6 +1,6 @@
 # PC-Developer-Tools-Python Role
 
-## 📌 Overview
+## Overview
 This README accompanies the `pc-developer-tools-python` role, which is part of the `cymais` repository. The role is dedicated to setting up Python development tools on personal computers.
 
 ## Role Contents

roles/pc-developer-tools/README.md

@@ -1,6 +1,6 @@
 # PC-Developer-Tools Role
 
-## 📌 Overview
+## Overview
 This README document is for the `pc-developer-tools` role within the `cymais` repository. The role is designed to streamline the setup of essential development tools on personal computers, particularly for software development environments.
 
 ## Role Contents

roles/pc-docker/README.md

@@ -1,6 +1,6 @@
 # README for PC-Docker Playbook
 
-## 📌 Overview
+## Overview
 This playbook, `pc-docker`, is part of a larger collection housed within the `cymais` repository. It is specifically tailored for setting up Docker and Docker Compose on personal computers (PCs) used for development purposes. The primary goal is to facilitate a development environment on individual workstations rather than configuring servers for hosting or distributing Docker images.
 
 ## Contents

roles/pc-games/README.md

@@ -1,6 +1,6 @@
 # PC-Games Role
 
-## 📌 Overview
+## Overview
 This README is for the `pc-games` role, a part of the `cymais` repository. This role is designed to install a variety of popular open-source and freely available games on personal computers.
 
 ## Role Contents

roles/pc-git/README.md

@@ -1,6 +1,6 @@
 # PC-Git Role
 
-## 📌 Overview
+## Overview
 Welcome to the `pc-git` role documentation, part of the `cymais` repository. This role is focused on setting up Git, a widely-used version control system, on personal computers. The role includes tasks for installing Git and configuring global user details.
 
 ## Role Tasks

roles/pc-gnome/README.md

@@ -1,6 +1,6 @@
 # PC-Gnome Role
 
-## 📌 Overview
+## Overview
 Welcome to the `pc-gnome` role, a key part of the `cymais` repository. This role is dedicated to setting up and configuring the GNOME desktop environment on personal computers.
 
 ## Role Details

roles/pc-gnucash/README.md

@@ -1,6 +1,6 @@
 # GnuCash Installation Role
 
-## 📌 Overview
+## Overview
 This Ansible role is responsible for installing GnuCash, a free and open-source financial management software, on systems utilizing the Pacman package manager. It's particularly useful for setting up GnuCash in a Linux environment with minimal manual intervention.
 
 ## Role: pc-gnucash

roles/pc-jrnl/README.md

@@ -1,6 +1,6 @@
 # Jrnl Role for Ansible
 
-## 📌 Overview
+## Overview
 This role automates the installation of Jrnl, a simple and effective command-line journal application. It uses the `community.general.pacman` module for systems that support the Pacman package manager, ensuring that Jrnl is installed and up to date.
 
 ## Requirements

roles/pc-latex/README.md

@@ -1,6 +1,6 @@
 # LaTeX Role
 
-## 📌 Overview
+## Overview
 Welcome to the LaTeX role within the `cymais` repository. It focuses on setting up a comprehensive LaTeX environment on Arch Linux-based systems, catering to the needs of users who require an advanced document preparation system.
 
 ## Role Contents

roles/pc-libreoffice/README.md

@@ -1,6 +1,6 @@
 # PC-LibreOffice Role
 
-## 📌 Overview
+## Overview
 This README is for the `pc-libreoffice` role, part of the `cymais` repository. This role focuses on installing LibreOffice, a powerful and free office suite, along with necessary fonts and language packages.
 
 ## Role Contents

roles/pc-network-analyze-tools/README.md

@@ -1,6 +1,6 @@
 # PC-Network-Analyze-Tools Role
 
-## 📌 Overview
+## Overview
 This README accompanies the `pc-network-analyze-tools` role within the `cymais` repository. This role is dedicated to installing key network analysis tools on personal computers.
 
 ## Role Contents

roles/pc-nextcloud/README.md

@@ -1,6 +1,6 @@
 # PC-Nextcloud Role
 
-## 📌 Overview
+## Overview
 This README details the `pc-nextcloud` role, part of the `cymais` repository. This role focuses on setting up the Nextcloud client on personal computers and configuring directory synchronization.
 
 ## Role Variables

roles/pc-office/README.md

@@ -1,6 +1,6 @@
 # PC-Office Role
 
-## 📌 Overview
+## Overview
 This README document is for the `pc-office` role, a component of the `cymais` repository. This role is designed to install a suite of office-related software on personal computers, providing a comprehensive set of tools for various office tasks.
 
 ## Role Tasks

roles/pc-qbittorrent/README.md

@@ -1,6 +1,6 @@
 # PC-QBittorrent Role
 
-## 📌 Overview
+## Overview
 This README is for the `pc-qbittorrent` role within the `cymais` repository. This role is specifically crafted for installing qBittorrent, a popular open-source torrent client, on personal computers.
 
 ## Role Tasks

roles/pc-security-tools/README.md

@@ -1,6 +1,6 @@
 # PC-Security-Tools Role
 
-## 📌 Overview
+## Overview
 This README document is for the `pc-security-tools` role, a part of the `cymais` repository. This role is designed to equip personal computers with essential tools for enhancing data security and privacy.
 
 ## Role Tasks

roles/pc-spotify/README.md

@@ -1,6 +1,6 @@
 # PC-Spotify Role
 
-## 📌 Overview
+## Overview
 This README is for the `pc-spotify` role, part of the `cymais` repository. This role is dedicated to installing Spotify, a popular digital music streaming service, on personal computers.
 
 ## Role Tasks

roles/pc-ssh/README.md

@@ -1,6 +1,6 @@
 # PC-SSH Role
 
-## 📌 Overview
+## Overview
 Welcome to the `pc-ssh` role, a critical component of the `cymais` repository. This role is dedicated to setting up SSH (Secure Shell) on the client side, facilitating secure access to remote servers.
 
 ## Role Description

roles/pc-streaming-tools/README.md

@@ -1,6 +1,6 @@
 # PC-Streaming-Tools Role
 
-## 📌 Overview
+## Overview
 This README is associated with the `pc-streaming-tools` role, part of the `cymais` repository. This role is focused on setting up essential tools for live streaming and video recording on personal computers.
 
 ## Role Tasks

roles/pc-torbrowser/README.md

@@ -1,6 +1,6 @@
 # PC-TorBrowser Role
 
-## 📌 Overview
+## Overview
 This README document is for the `pc-torbrowser` role, a crucial component of the `cymais` repository. This role is specifically designed for the installation and setup of Tor Browser on personal computers.
 
 ## Role Tasks

roles/pc-video-conference/README.md

@@ -1,6 +1,6 @@
 # PC-Video-Conference Role
 
-## 📌 Overview
+## Overview
 Welcome to the `pc-video-conference` role documentation, a part of the `cymais` repository. This role is focused on installing video conferencing software on Linux systems, specifically tailored for personal use and remote work requirements.
 
 ## Role Tasks

roles/postfix/README.md

@@ -4,7 +4,7 @@
 
 This role installs and configures [Postfix](https://en.wikipedia.org/wiki/Postfix_(software)) – a mail transfer agent – on the target system. It deploys a preconfigured aliases file (using a Jinja2 template) that defines mail redirections and standard aliases for local mail delivery.
 
-## 📌 Overview
+## Overview
 
 Optimized for secure and reliable mail delivery, this role:
 - Installs Postfix via [pacman](https://wiki.archlinux.org/title/Pacman).

roles/python-pip/README.md

@@ -4,7 +4,7 @@
 
 This role installs the [python-pip](https://en.wikipedia.org/wiki/Pip_(package_manager)) package on the target system. It ensures that the pip package manager is available for installing Python packages.
 
-## 📌 Overview
+## Overview
 
 Optimized for simplicity and idempotency, this role:
 - Installs the python-pip package using [pacman](https://wiki.archlinux.org/title/Pacman).

roles/restart-docker/README.md

@@ -3,7 +3,7 @@
 
 This role automates the restart process for Docker Compose instances within a specified directory. It deploys a Python script that checks for the presence of docker-compose.yml files and restarts the associated services—using a hard restart for certain directories if needed.
 
-## 📌 Overview
+## Overview
 
 Optimized for containerized environments, this role:
 - Sets up the necessary directories and scripts for restarting Docker Compose instances.

roles/sshd/README.md

@@ -4,7 +4,7 @@
 
 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.
 
-## 📌 Overview
+## Overview
 
 Optimized for secure remote access, this role:
 - Generates an SSH daemon configuration file from a Jinja2 template.

roles/sudo/README.md

@@ -4,7 +4,7 @@
 
 This role installs the [sudo](https://en.wikipedia.org/wiki/Sudo) package and deploys a default sudoers file to ensure secure and consistent privilege escalation on the target system. It uses a preconfigured sudoers file that follows best practices and includes directives to read drop-in files from `/etc/sudoers.d`.
 
-## 📌 Overview
+## Overview
 
 Optimized for security and ease of administration, this role guarantees that sudo is installed and configured according to recommended practices. The provided sudoers file includes essential comments, host/user aliases, and defaults to help prevent misconfigurations.
 

roles/system-aur-helper/README.md

@@ -3,7 +3,7 @@
 
 This role ensures that the AUR helper [yay](https://wiki.archlinux.org/title/Yay) is installed on the system. It installs yay via [pacman](https://wiki.archlinux.org/title/Pacman) and creates a dedicated `aur_builder` user to facilitate building AUR packages.
 
-## 📌 Overview
+## Overview
 
 The role performs the following tasks:
 - Installs the AUR helper [yay](https://wiki.archlinux.org/title/Yay) using pacman.

roles/system-btrfs-auto-balancer/README.md

@@ -4,7 +4,7 @@
 
 This role automates the management and balancing of Btrfs file systems. It clones the latest version of the [auto-btrfs-balancer](https://github.com/kevinveenbirkenbach/auto-btrfs-balancer.git) repository and configures a systemd service and timer to run the balancing script automatically.
 
-## 📌 Overview
+## Overview
 
 Optimized for automated file system management, this role:
 - Clones the auto-btrfs-balancer repository.

roles/system-maintenance-lock/README.md

@@ -4,7 +4,7 @@
 
 This role provides a locking mechanism to ensure that critical services are not interrupted during maintenance activities such as updates, backups, or patch applications. It waits for specified services to stop and prevents conflicting operations.
 
-## 📌 Overview
+## Overview
 
 The role performs the following:
 - Blocks execution until specified services have stopped.

roles/system-security/README.md

@@ -4,7 +4,7 @@
 
 This role configures security-related settings on the target system to ensure that essential security services are properly managed. It reinforces system security by integrating with related roles and enforcing best practices.
 
-## 📌 Overview
+## Overview
 
 The role focuses on:
 - Configuring key security services such as [SSH](https://en.wikipedia.org/wiki/Secure_Shell).

roles/system-storage-optimizer/README.md

@@ -4,7 +4,7 @@
 
 This role optimizes storage allocation for Docker volumes by migrating volumes between SSD (rapid storage) and HDD (mass storage) based on container image types. It creates symbolic links to maintain consistent storage paths after migration.
 
-## 📌 Overview
+## Overview
 
 The role performs the following tasks:
 - Migrates Docker volumes with database workloads to rapid storage (SSD) for improved performance.

roles/system-swapfile/README.md

@@ -4,7 +4,7 @@
 
 This role automates the creation of a swapfile on the target system by cloning a swapfile creation script from a Git repository and executing it with the specified swapfile size.
 
-## 📌 Overview
+## Overview
 
 The role performs the following tasks:
 - Clones the swapfile creation script from the Git repository.

roles/systemd-notifier-email/README.md

@@ -4,7 +4,7 @@
 
 This role installs and configures the necessary components for sending email notifications via systemd when a service fails. It sets up the `systemd-notifier-email` service and configures email parameters and templates using msmtp.
 
-## 📌 Overview
+## Overview
 
 Optimized for secure and reliable service failure notifications, this role is an integral part of the overall `systemd-notifier` suite. It ensures that, upon failure of a critical service, an email alert is sent automatically to enable prompt troubleshooting.
 

roles/systemd-notifier-telegram/README.md

@@ -4,7 +4,7 @@
 
 This role installs and configures the necessary components for sending notifications via systemd when a service fails. It sets up the `systemd-notifier-telegram` service and configures parameters and customizable templates for sending messages through [Telegram](https://telegram.org).
 
-## 📌 Overview
+## Overview
 
 Optimized for real-time alerts, this role is a key component of the overall [`systemd-notifier` suite](../). It ensures that, upon failure of a critical service, a Telegram message is automatically sent to notify administrators and enable prompt troubleshooting.
 

roles/systemd-notifier/README.md

@@ -4,7 +4,7 @@
 
 This role installs a systemd service that sends notifications via both [systemd-notifier-telegram](../systemd-notifier-telegram/README.md) and [systemd-notifier-email](../systemd-notifier-email/README.md) when any service fails.
 
-## 📌 Overview
+## Overview
 
 Optimized for prompt and comprehensive failure alerts, this role configures a unified notification service. It leverages the capabilities of both Telegram and Email notifications to ensure that administrators are quickly informed about service issues, enabling rapid troubleshooting.
 

roles/systemd-timer/README.md

@@ -4,7 +4,7 @@
 
 This role configures a systemd timer to periodically start a corresponding service. It uses a Jinja2 template to create a timer unit file that specifies the scheduling parameters (such as OnCalendar and RandomizedDelaySec) and then restarts the timer service accordingly.
 
-## 📌 Overview
+## Overview
 
 Optimized for automated task scheduling in a [systemd](https://en.wikipedia.org/wiki/Systemd) environment, this role:
 - Generates a timer unit file for a given service (using the `service_name` variable).

roles/update-apt/README.md

@@ -4,7 +4,7 @@
 
 This role updates packages on Debian-based systems. It refreshes the apt cache and performs a distribution upgrade to ensure all packages are at their latest version.
 
-## 📌 Overview
+## Overview
 
 Designed for Debian and Ubuntu systems, this role:
 - Updates the package cache using apt.

roles/update-docker/README.md

@@ -4,7 +4,7 @@
 
 This role updates Docker Compose instances by checking for changes in Docker image digests and applying updates if necessary. It utilizes a Python script to handle git pulls and Docker image pulls, and rebuilds containers when changes are detected.
 
-## 📌 Overview
+## Overview
 
 The role performs the following:
 - Deploys a Python script to check for Docker image updates.

roles/update-pacman/README.md

@@ -4,7 +4,7 @@
 
 This role updates the package cache and upgrades installed packages on Arch Linux systems using [pacman](https://wiki.archlinux.org/title/Pacman).
 
-## 📌 Overview
+## Overview
 
 Optimized for Arch Linux, this role uses pacman to refresh the package cache and upgrade all installed packages to their latest available versions. It automates system updates to ensure that the system remains secure and up-to-date with the latest software improvements and security patches.
 

roles/update-yay/README.md

@@ -4,7 +4,7 @@
 
 This role updates AUR packages on Arch Linux systems using [yay](https://wiki.archlinux.org/title/Yay). It automates the process of upgrading AUR packages, ensuring that your system stays current with the latest software available in the Arch User Repository.
 
-## 📌 Overview
+## Overview
 
 The role performs the following:
 - Checks if the [yay](https://wiki.archlinux.org/title/Yay) AUR helper is installed.

roles/update/tasks/README.md

@@ -4,7 +4,7 @@
 
 This role serves as a central orchestrator for system updates. It conditionally executes various update roles based on the target system and available directories, ensuring that packages and Docker images are kept up-to-date.
 
-## 📌 Overview
+## Overview
 
 This role performs the following tasks:
 - Checks if the Docker Compose instances directory exists.

roles/user-administrator/README.md

@@ -4,7 +4,7 @@
 
 This role creates a dedicated administrator user for local administrative tasks. The administrator account is configured to require a password when executing [sudo](https://en.wikipedia.org/wiki/Sudo), ensuring secure privilege escalation. For security reasons, it is recommended to use this dedicated administrator user instead of the default root account. The role also sets up SSH-related configuration by copying an authorized_keys file from inventory data.
 
-## 📌 Overview
+## Overview
 
 Optimized for secure system management, this role performs the following:
 - Creates an administrator user with a home directory.

roles/user-root/README.md

@@ -4,7 +4,7 @@
 
 This role manages the generation and handling of an SSH key for the [root user](https://en.wikipedia.org/wiki/Superuser) on a target system. It ensures that an SSH key is generated if one does not already exist and outputs the public key, enabling secure SSH access for the root user in automated environments.
 
-## 📌 Overview
+## Overview
 
 Optimized for secure system administration, this role performs the following tasks:
 - Verifies the existence of a root SSH public key.

roles/user/README.md

@@ -4,7 +4,7 @@
 
 This role executes tasks that are relevant for all users by configuring essential shell files. It deploys customized templates for [`.bashrc`](https://wiki.archlinux.org/title/Bash#Startup_files) and [`.bash_profile`](https://wiki.archlinux.org/title/Bash#Login_shells) for any specified user. This ensures a consistent and enhanced shell environment across the system.
 
-## 📌 Overview
+## Overview
 
 Optimized for modular configuration, this role uses Jinja2 templates to create:
 - A customized [`.bashrc`](https://wiki.archlinux.org/title/Bash#Startup_files) that sets up a dynamic welcome message, system information, and useful aliases.

roles/wireguard/README.md

@@ -4,7 +4,7 @@
 
 This role manages [Wireguard](https://www.wireguard.com/) on the host. It installs the necessary Wireguard packages, configures sysctl settings for IPv4/IPv6 forwarding, and deploys the Wireguard configuration file to enable the VPN service using [wg-quick](https://www.wireguard.com/quickstart/).
 
-## 📌 Overview
+## Overview
 
 Optimized for both [Arch Linux](https://wiki.archlinux.org/index.php/WireGuard) and [Ubuntu/Debian](https://wireguard.com/install/), this role performs the following tasks:
 - Installs Wireguard tools using the appropriate package manager.

sphinx/_templates/local_md_files.html

@@ -1,19 +0,0 @@
-{% macro render_headings(headings) %}
-  <ul>
-  {% for item in headings %}
-    <li>
-      <a href="{{ pathto(item.link).replace("#", "") + '#' + item.anchor }}">{{ item.text }}</a>
-      {% if item.children %}
-        {{ render_headings(item.children) }}
-      {% endif %}
-    </li>
-  {% endfor %}
-  </ul>
-{% endmacro %}
-
-{% if local_md_headings %}
-<div class="local-md-headings">
-  <h3>Overview</h3>
-  {{ render_headings(local_md_headings) }}
-</div>
-{% endif %}

sphinx/conf.py

@@ -17,7 +17,7 @@ author = 'Kevin Veen-Birkenbach'
 # -- General configuration ---------------------------------------------------
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
 
-templates_path = ['_templates']
+templates_path = ['templates']
 exclude_patterns = ['docs', 'venv', 'venv/**']
 
 
@@ -26,14 +26,14 @@ exclude_patterns = ['docs', 'venv', 'venv/**']
 # https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
 
 html_theme = 'sphinxawesome_theme'
-html_static_path = ['_static']
+html_static_path = ['static']
 
 html_sidebars = {
     '**': [
         #'globaltoc.html',
         # 'relations.html',
         # 'sourcelink.html',
-        'local_md_files.html',  # Include your custom template
+        'structure.html',  # Include your custom template
         # 'searchbox.html',
     ]
 }
@@ -49,14 +49,17 @@ source_suffix = {
     '.md': 'markdown',
 }
 
+sys.path.insert(0, os.path.abspath('./extensions'))
 extensions = [
-    "sphinx.ext.autosummary",
-    "sphinx.ext.autodoc",
-    "myst_parser",
-    'local_md_files',
-    'roles_overview',
-    'markdown_include',
+    'sphinx.ext.autosummary',
+    'sphinx.ext.autodoc',
+    'myst_parser',
+    'extensions.local_file_headings',
+    'extensions.local_subfolders',
+    'extensions.roles_overview',
+    'extensions.markdown_include',
 ]
+
 autosummary_generate = True
 
 myst_enable_extensions = [

sphinx/extensions/local_file_headings.py

@@ -0,0 +1,49 @@
+import os
+from sphinx.util import logging
+from docutils.parsers.rst import Directive
+from .nav_utils import natural_sort_key, extract_headings_from_file, group_headings, sort_tree, MAX_HEADING_LEVEL, DEFAULT_MAX_NAV_DEPTH
+
+logger = logging.getLogger(__name__)
+DEFAULT_MAX_NAV_DEPTH = 4
+
+def add_local_file_headings(app, pagename, templatename, context, doctree):
+    srcdir = app.srcdir
+    directory = os.path.dirname(pagename)
+    abs_dir = os.path.join(srcdir, directory)
+    if not os.path.isdir(abs_dir):
+        logger.warning(f"Directory {abs_dir} not found for page {pagename}.")
+        context['local_md_headings'] = []
+        return
+
+    # Get only files with .md or .rst extensions.
+    files = [f for f in os.listdir(abs_dir) if f.endswith('.md') or f.endswith('.rst')]
+    # If an index file is present, remove any readme files (case-insensitive).
+    files_lower = [f.lower() for f in files]
+    if 'index.md' in files_lower or 'index.rst' in files_lower:
+        files = [f for f in files if f.lower() not in ['readme.md', 'readme.rst']]
+
+    file_items = []
+    for file in files:
+        filepath = os.path.join(abs_dir, file)
+        headings = extract_headings_from_file(filepath, max_level=MAX_HEADING_LEVEL)
+        basename, _ = os.path.splitext(file)
+        # Set priority: index gets priority 0, otherwise 1.
+        priority = 0 if basename.lower() == 'index' else 1
+        for heading in headings:
+            file_link = os.path.join(directory, basename)
+            file_items.append({
+                'level': heading['level'],
+                'text': heading['text'],
+                'link': file_link,
+                'anchor': heading['anchor'],
+                'priority': priority,
+                'filename': basename
+            })
+    tree = group_headings(file_items)
+    sort_tree(tree)
+    context['local_md_headings'] = tree
+
+def setup(app):
+    app.add_config_value('local_nav_max_depth', DEFAULT_MAX_NAV_DEPTH, 'env')
+    app.connect('html-page-context', add_local_file_headings)
+    return {'version': '0.1', 'parallel_read_safe': True}

sphinx/extensions/local_subfolders.py

@@ -0,0 +1,73 @@
+import os
+import re
+from sphinx.util import logging
+from .nav_utils import natural_sort_key, extract_headings_from_file, group_headings, sort_tree, MAX_HEADING_LEVEL, DEFAULT_MAX_NAV_DEPTH
+
+logger = logging.getLogger(__name__)
+
+def collect_subfolder_tree(dir_path, base_url, current_depth, max_depth):
+    """
+    Recursively collects navigation items from subdirectories.
+    For each subfolder, it looks for a candidate file (prefer "index.rst" then "README.md").
+    Only subfolders with such a file will be included.
+    If a candidate is found, the first level‑1 heading from that file is used as the title;
+    if no heading is found, the folder name is used.
+    The link is built pointing directly to the candidate file (by its base name) rather than the folder.
+    Returns a list representing the subfolder tree.
+    """
+    items = []
+    for item in sorted(os.listdir(dir_path), key=lambda s: s.lower()):
+        full_path = os.path.join(dir_path, item)
+        if os.path.isdir(full_path):
+            candidate = None
+            for cand in ['index.rst', 'README.md']:
+                candidate_path = os.path.join(full_path, cand)
+                if os.path.isfile(candidate_path):
+                    candidate = candidate_path
+                    break
+            # Only include the folder if a candidate file was found.
+            if candidate:
+                headings = extract_headings_from_file(candidate, max_level=MAX_HEADING_LEVEL)
+                title = headings[0]['text'] if headings else item
+                # Use the candidate file's base name as link target.
+                candidate_base = os.path.splitext(os.path.basename(candidate))[0]
+                link = os.path.join(base_url, item, candidate_base)
+                entry = {
+                    'level': 1,
+                    'text': title,
+                    'link': link,
+                    'anchor': '',
+                    'priority': 0,
+                    'filename': item
+                }
+                if current_depth < max_depth:
+                    children = collect_subfolder_tree(full_path, os.path.join(base_url, item), current_depth + 1, max_depth)
+                    if children:
+                        entry['children'] = children
+                items.append(entry)
+    return items
+
+def add_local_subfolders(app, pagename, templatename, context, doctree):
+    """
+    Collects a tree of subfolder navigation items from the current directory.
+    For each subfolder, the title is determined by scanning for a candidate file
+    (prefer "index.rst" then "README.md") and extracting its first level‑1 heading,
+    or using the folder name if none is found.
+    The resulting tree is stored in context['local_subfolders'].
+    """
+    srcdir = app.srcdir
+    directory = os.path.dirname(pagename)
+    abs_dir = os.path.join(srcdir, directory)
+    if not os.path.isdir(abs_dir):
+        logger.warning(f"Directory {abs_dir} not found for page {pagename}.")
+        context['local_subfolders'] = []
+        return
+
+    max_nav_depth = getattr(app.config, 'local_nav_max_depth', DEFAULT_MAX_NAV_DEPTH)
+    subfolder_tree = collect_subfolder_tree(abs_dir, directory, current_depth=0, max_depth=max_nav_depth)
+    sort_tree(subfolder_tree)
+    context['local_subfolders'] = subfolder_tree
+
+def setup(app):
+    app.connect('html-page-context', add_local_subfolders)
+    return {'version': '0.1', 'parallel_read_safe': True}

sphinx/extensions/markdown_include.py

@@ -0,0 +1,80 @@
+import os
+from docutils import nodes
+from docutils.parsers.rst import Directive
+from sphinx.util import logging
+
+logger = logging.getLogger(__name__)
+
+from myst_parser.parsers.sphinx_ import MystParser
+
+class MarkdownIncludeDirective(Directive):
+    required_arguments = 1  # Path to the Markdown file
+    optional_arguments = 0
+    final_argument_whitespace = True
+    has_content = False
+
+    def run(self):
+        logger.info("Executing markdown-include directive")
+        env = self.state.document.settings.env
+        # Determine the absolute path of the file.
+        rel_filename, filename = env.relfn2path(self.arguments[0])
+        logger.info("Markdown file: %s", filename)
+        if not os.path.exists(filename):
+            error = self.state_machine.reporter.error(
+                f'File not found: {filename}',
+                nodes.literal_block(self.block_text, self.block_text),
+                line=self.lineno)
+            return [error]
+
+        try:
+            with open(filename, 'r', encoding='utf-8') as f:
+                markdown_content = f.read()
+        except Exception as e:
+            error = self.state_machine.reporter.error(
+                f'Error reading file {filename}: {e}',
+                nodes.literal_block(self.block_text, self.block_text),
+                line=self.lineno)
+            return [error]
+
+        # Parse the Markdown content with MystParser.
+        parser = MystParser()
+        from docutils.frontend import OptionParser
+        from docutils.utils import new_document
+        settings = OptionParser(components=(MystParser,)).get_default_values()
+        # Attach the Sphinx environment to the settings so that myst_parser works.
+        settings.env = self.state.document.settings.env
+        doc = new_document(filename, settings=settings)
+        parser.parse(markdown_content, doc)
+        logger.info("Markdown parsing completed successfully")
+
+        # Remove the first header (title) if it exists.
+        if doc.children:
+            first_section = doc.children[0]
+            if isinstance(first_section, nodes.section) and first_section.children:
+                first_child = first_section.children[0]
+                if isinstance(first_child, nodes.title):
+                    # If there are additional children, remove the title node.
+                    if len(first_section.children) > 1:
+                        first_section.pop(0)
+                        logger.info("Removed first header from Markdown content")
+                    else:
+                        # If it's the only child, clear its content instead.
+                        first_child.clear()
+                        logger.info("Cleared text of first header from Markdown content")
+            
+            # Unwrap the first section if it no longer has a title.
+            if isinstance(first_section, nodes.section):
+                has_title = any(isinstance(child, nodes.title) and child.astext().strip() 
+                                for child in first_section.children)
+                if not has_title:
+                    # Remove the section wrapper so that its content does not create a TOC entry.
+                    unwrapped = list(first_section.children)
+                    # Replace the first section with its children.
+                    doc.children = unwrapped + doc.children[1:]
+                    logger.info("Unwrapped first section to avoid a TOC entry")
+
+        return doc.children
+
+def setup(app):
+    app.add_directive("markdown-include", MarkdownIncludeDirective)
+    return {'version': '0.1', 'parallel_read_safe': True}

sphinx/extensions/nav_utils.py

@@ -0,0 +1,99 @@
+import os
+import re
+import yaml
+
+DEFAULT_MAX_NAV_DEPTH = 4
+MAX_HEADING_LEVEL = 2
+
+def natural_sort_key(text):
+    """
+    Generate a key for natural (human-friendly) sorting,
+    taking numeric parts into account.
+    """
+    return [int(c) if c.isdigit() else c.lower() for c in re.split(r'(\d+)', text)]
+
+def extract_headings_from_file(filepath, max_level=MAX_HEADING_LEVEL):
+    """
+    Extract headings from a file.
+    For Markdown (.md) files, looks for lines starting with '#' (up to max_level).
+    For reStructuredText (.rst) files, looks for a line immediately followed by an underline.
+    If no headings are found and the file is an index file while a README.md exists in the same folder,
+    it will try to extract headings from the README.md instead.
+    Returns a list of dictionaries with keys: 'level', 'text', and 'anchor' (if applicable).
+    """
+    import os, re
+    headings = []
+    ext = os.path.splitext(filepath)[1].lower()
+    try:
+        with open(filepath, 'r', encoding='utf-8') as f:
+            if ext == '.md':
+                in_code_block = False
+                for line in f:
+                    if line.strip().startswith("```"):
+                        in_code_block = not in_code_block
+                        continue
+                    if in_code_block:
+                        continue
+                    match = re.match(r'^(#{1,})\s+(.*)$', line)
+                    if match:
+                        level = len(match.group(1))
+                        if level <= max_level:
+                            heading_text = match.group(2).strip()
+                            anchor = re.sub(r'\s+', '-', heading_text.lower())
+                            anchor = re.sub(r'[^a-z0-9\-]', '', anchor)
+                            headings.append({'level': level, 'text': heading_text, 'anchor': anchor})
+            elif ext == '.rst':
+                lines = f.readlines()
+                for i in range(len(lines) - 1):
+                    text_line = lines[i].rstrip("\n")
+                    underline = lines[i+1].rstrip("\n")
+                    if len(underline) >= 3 and re.fullmatch(r'[-=~\^\+"\'`]+', underline):
+                        level = 1
+                        heading_text = text_line.strip()
+                        headings.append({'level': level, 'text': heading_text, 'anchor': ''})
+    except Exception as e:
+        print(f"Warning: Error reading {filepath}: {e}")
+
+    # If no headings were found and the file is an index file,
+    # then try to load headings from a README.md in the same folder.
+    if not headings:
+        base = os.path.basename(filepath).lower()
+        if base == 'index.rst':
+            folder = os.path.dirname(filepath)
+            readme_path = os.path.join(folder, 'README.md')
+            if os.path.isfile(readme_path):
+                try:
+                    headings = extract_headings_from_file(readme_path, max_level)
+                except Exception as e:
+                    print(f"Warning: Error reading fallback README.md in {folder}: {e}")
+    return headings
+
+def group_headings(headings):
+    """
+    Convert a flat list of headings into a tree structure based on their level.
+    Each heading gets a 'children' list.
+    """
+    tree = []
+    stack = []
+    for heading in headings:
+        heading['children'] = []
+        while stack and stack[-1]['level'] >= heading['level']:
+            stack.pop()
+        if stack:
+            stack[-1]['children'].append(heading)
+        else:
+            tree.append(heading)
+        stack.append(heading)
+    return tree
+
+def sort_tree(tree):
+    """
+    Sort a tree of navigation items, first by a 'priority' value (lower comes first)
+    and then by a natural sort key based on the 'filename' field (or the 'text' field if no filename is provided).
+    This ensures that 'index' and 'readme' (priority 0) always appear at the top.
+    """
+    tree.sort(key=lambda x: (x.get('priority', 1), natural_sort_key(x.get('filename', x['text']))))
+    for item in tree:
+        if item.get('children'):
+            sort_tree(item['children'])
+