Huge role refactoring/cleanup. Other commits will propably follow. Because some bugs will exist. Still important for longrun and also for auto docs/help/slideshow generation

roles/README.md

@@ -1,13 +1,120 @@
-# Applications and Roles
-CyMaIS offers a variety of applications to simplify your daily tasks.
+# Roles
+
+This directory contains all of the Ansible roles used throughout the CyMaIS project. Roles are organized by function and prefixed accordingly.
+
+For a complete list of role categories and detailed definitions, see:
 
-## For Users  
-Discover the solutions CyMaIS provides for you:  
 - [Application Glossary](application_glosar.rst)  
-- [Application Categories](application_categories.rst)  
+- [Application Categories](application_categories.rst)
 
-## For Developers
-Explore the technical details of our roles:  
-- [Ansible Role Glossary](ansible_role_glosar.rst)  
+---
 
-Want to dive deeper into the source code or our ansible roles? Check out our [GitHub repository](https://github.com/kevinveenbirkenbach/cymais/tree/master/roles).  
+## Core & System
+
+- **core-***  
+  Fundamental system configuration (SSH, journald, sudo, etc.)
+
+- **generic-***  
+  Generic helpers and language/tool installers (e.g. `generic-git`, `generic-locales`, `generic-timer`)
+
+- **desktop-***  
+  Desktop environment and application roles (e.g. `desktop-gnome`, `desktop-browser`, `desktop-libreoffice`)
+
+---
+
+## Webserver & HTTP
+
+- **webserver-core**  
+  Installs and configures the base Nginx server.
+
+- **webserver-tls-***  
+  Manages TLS certificates and renewal (formerly “https”).
+
+- **webserver-proxy-***  
+  Proxy and vhost orchestration roles (domain setup, OAuth2 proxy, etc.)
+
+- **webserver-injector-***  
+  HTML response modifiers: CSS, JS, Matomo tracking, iframe notifier.
+
+- **webserver-composer**  
+  Aggregates multiple sub-filters into one include for your vhost.
+
+- **web-service-***  
+  Static‐content servers (assets, HTML, legal pages, file hosting).
+
+- **web-app-***  
+  Application-specific Docker/Compose roles (e.g. GitLab, Nextcloud, Mastodon).
+
+---
+
+## Network
+
+- **network-***  
+  Network infrastructure (DNS records, WireGuard, Let’s Encrypt entrypoints).
+
+- **service-***  
+  Docker‐deployed services that aren’t “apps” (RDBMS, LDAP, Redis, OpenLDAP).
+
+---
+
+## Monitoring & Alerting
+
+- **monitor-bot-***  
+  “Bot”-style health checks with alerts via Telegram, email, etc.
+
+- **monitor-core-***  
+  Low-level system monitors (journalctl, Docker containers, disk space).
+
+- **alert-***  
+  Failure or status notification handlers (core, email, Telegram).
+
+---
+
+## Maintenance & Healing
+
+- **maintenance-***  
+  Periodic maintenance tasks (Btrfs balancing, swapfile management).
+
+- **maintenance-docker-***  
+  Automated recovery and restarts for Docker Compose workloads.
+
+- **cleanup-***  
+  Housekeeping tasks (old backups, certs, log rotation).
+
+---
+
+## Backup & Restore
+
+- **backup-***  
+  Local and remote backup strategies for files, Docker volumes, databases.
+
+---
+
+## Updates & Package Management
+
+- **update-***  
+  Keeps OS and language packages up to date (`update-apt`, `update-docker`, `update-pip`, etc.)
+
+- **pkgmgr-***  
+  Language or platform package managers (npm, pip, AUR helper).
+
+---
+
+## Users & Access
+
+- **user-***  
+  Creates user accounts and SSH keys.
+
+- **user-administrator**, **user-root**  
+  Specialized account configurations for privileged users.
+
+---
+
+> **Tip:** To find a role quickly, search for its prefix:  
+> `core-`, `generic-`, `desktop-`, `webserver-`, `web-service-`, `web-app-`,  
+> `network-`, `service-`, `monitor-`, `alert-`, `maintenance-`, `cleanup-`,  
+> `backup-`, `update-`, `pkgmgr-`, `user-`.
+
+---
+
+_For more details on which applications each role supports, see the [Application Categories](application_categories.rst) and the full [Application Glossary](application_glosar.rst)._