Restructured mds

docs/guides/administrator/Configuration.md

@@ -0,0 +1,38 @@
+# Configuration
+
+## 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'
+```
+
+## 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.

docs/guides/administrator/Deploy.md

@@ -0,0 +1,100 @@
+# 🚀 Deployment Guide
+
+This section explains how to deploy and manage the **Cyber Master Infrastructure Solution (CyMaIS)** using Ansible. CyMaIS uses a collection of Ansible tasks, which are controlled via different **"modes"** — such as **updates**, **backups**, **resets**, and **cleanup** operations.
+
+---
+
+## ✅ Prerequisites
+
+Before deploying, ensure the following are in place:
+
+- **🧭 Inventory File:** A valid Ansible inventory file that defines your target systems (servers, personal computers, etc.). Adjust example paths to your environment.
+- **📦 CyMaIS Installed:** Install via [Kevin's Package-Manager](https://github.com/kevinveenbirkenbach/package-manager).
+- **🔐 (Optional) Vault Password File:** If you don't want to enter your vault password interactively, create a password file.
+
+---
+
+## 📘 Show CyMaIS Help
+
+To get a full overview of available options and usage instructions, run:
+
+```bash
+cymais --help
+```
+
+---
+
+## 💡 Example Deploy Command
+
+To deploy CyMaIS on a personal computer (e.g., a laptop), you can run:
+
+```bash
+cymais playbook \
+  --limit hp-spectre-x360 \
+  --host-type personal-computer \
+  --update \
+  --password-file ~/Repositories/git.veen.world/kevinveenbirkenbach/computer-inventory/.pass/general.txt \
+  ~/Repositories/git.veen.world/kevinveenbirkenbach/computer-inventory/pcs.yml
+```
+
+### 🧠 What does this command do?
+
+| Parameter | Description |
+|----------|-------------|
+| `playbook` | Executes the playbook subcommand of CyMaIS. |
+| `--limit hp-spectre-x360` | Limits execution to a specific host (`hp-spectre-x360`). |
+| `--host-type personal-computer` | Defines the host type. Default is `server`; here it is set to `personal-computer`. |
+| `--update` | Enables update mode to apply software or configuration updates. |
+| `--password-file` | Specifies the vault password file path for decrypting sensitive values. |
+| `pcs.yml` | The path to the inventory file containing host definitions. |
+
+---
+
+## 🔐 Using a Vault Password File
+
+To avoid typing your vault password interactively, you can provide a file:
+
+```bash
+--password-file /path/to/your/vault_pass.txt
+```
+
+> ⚠️ **Security Tip:** Ensure the password file is properly protected (e.g., `chmod 600 vault_pass.txt`).
+
+---
+
+## 🔍 Full Command-Line Reference
+
+Here’s a breakdown of all available parameters from `cymais playbook --help`:
+
+| Argument | Description |
+|----------|-------------|
+| `inventory` *(positional)* | Path to the Ansible inventory file. |
+| `--limit <HOST>` | Run the playbook only on the specified host. |
+| `--host-type {server, personal-computer}` | Define the target system type (default is `server`). |
+| `--reset` | Enables reset mode (restores or resets specific configurations). |
+| `--test` | Enables test mode (dry-run style). No actual changes are applied. |
+| `--update` | Enables update mode to upgrade packages or configs. |
+| `--backup` | Triggers backup routines for data or configurations. |
+| `--cleanup` | Cleans up temporary files, old data, etc. |
+| `--debug` | Enables debug logging in the playbook. |
+| `--password-file <PATH>` | Uses a vault password file instead of interactive prompt. |
+| `-v, -vv, -vvv` | Increases output verbosity. More `v`s = more detail. |
+
+---
+
+## 🔧 Combine Multiple Modes
+
+You can mix and match modes like this:
+
+```bash
+cymais playbook --update --backup --cleanup pcs.yml
+```
+
+This will update the system, create a backup, and clean up unnecessary files in one run.
+
+---
+
+## 📝 Footnote
+
+> 📄 *This documentation page was generated with the help of AI.*  
+> 🤖 [View the original conversation (ChatGPT)](https://chatgpt.com/share/67ecfe25-3fb8-800f-923d-8cd3fc4efd2f)

docs/guides/administrator/Readme.md

@@ -0,0 +1,22 @@
+# Administrator Guide
+
+This guide is for **system administrators** who are deploying and managing CyMaIS infrastructure.
+
+## Setting Up CyMaIS 🏗️
+Follow these guides to install and configure CyMaIS:
+- [Setup Guide](SETUP_GUIDE.md)
+- [Configuration Guide](CONFIGURATION.md)
+- [Deployment Guide](DEPLOY.md)
+
+## Key Responsibilities 🔧
+- **User Management** - Configure LDAP, Keycloak, and user permissions.
+- **Security & Backups** - Set up `backup-remote-to-local`, `backup-data-to-usb`, and `system-security` roles.
+- **Application Hosting** - Deploy services like `Nextcloud`, `Matrix`, `Gitea`, and more.
+- **Networking & VPN** - Configure `WireGuard`, `OpenVPN`, and `Nginx Reverse Proxy`.
+
+## Managing & Updating CyMaIS 🔄
+- Regularly update services using `update-docker`, `update-pacman`, or `update-apt`.
+- Monitor system health with `health-btrfs`, `health-nginx`, and `health-docker-container`.
+- Automate system maintenance with `system-maintenance-lock`, `cleanup-backups-service`, and `restart-docker`.
+
+For more details, refer to the specific guides above.

docs/guides/administrator/Security_Guidelines.md

@@ -0,0 +1,29 @@
+# Security Guidelines
+
+CyMaIS is designed with security in mind. However, while following our guidelines can greatly improve your system’s security, no IT system can be 100% secure. Please report any vulnerabilities as soon as possible.
+
+Additional to the user securitry guidelines administrators have additional responsibilities to secure the entire system:
+
+- **Deploy on an Encrypted Server**  
+  It is recommended to install CyMaIS on an encrypted server to prevent hosting providers from accessing end-user data. For a practical guide on setting up an encrypted server, refer to the [Hetzner Arch LUKS repository](https://github.com/kevinveenbirkenbach/hetzner-arch-luks) 🔐. (Learn more about [disk encryption](https://en.wikipedia.org/wiki/Disk_encryption) on Wikipedia.)
+
+- **Centralized User Management & SSO**  
+  For robust authentication and central user management, set up CyMaIS using Keycloak and LDAP.
+  This configuration enables centralized [Single Sign-On (SSO)](https://en.wikipedia.org/wiki/Single_sign-on) (SSO), simplifying user management and boosting security.
+
+- **Enforce 2FA and Use a Password Manager**  
+  Administrators should also enforce [2FA](https://en.wikipedia.org/wiki/Multi-factor_authentication) and use a password manager with auto-generated passwords. We again recommend [KeePass](https://keepass.info/). The KeePass database can be stored securely in your Nextcloud instance and synchronized between devices.
+
+- **Avoid Root Logins & Plaintext Passwords**  
+  CyMaIS forbids logging in via the root user or using simple passwords. Instead, an SSH key must be generated and transferred during system initialization. When executing commands as root, always use `sudo` (or, if necessary, `sudo su`—but only if you understand the risks). (More information on [SSH](https://en.wikipedia.org/wiki/Secure_Shell) and [sudo](https://en.wikipedia.org/wiki/Sudo) is available on Wikipedia.)
+
+- **Manage Inventories Securely**  
+  Your inventories for running CyMaIS should be managed in a separate repository and secured with tools such as [Ansible Vault](https://en.wikipedia.org/wiki/Encryption) 🔒. Sensitive credentials must never be stored in plaintext; use a password file to secure these details.
+
+- **Reporting Vulnerabilities**  
+  If you discover a security vulnerability in CyMaIS, please report it immediately. We encourage proactive vulnerability reporting so that issues can be addressed as quickly as possible. Contact our security team at [security@cymais.cloud](mailto:security@cymais.cloud) 
+  **DO NOT OPEN AN ISSUE.**
+
+---
+
+By following these guidelines, both end users and administrators can achieve a high degree of security. Stay vigilant, keep your systems updated, and report any suspicious activity. Remember: while we strive for maximum security, no system is completely infallible.

docs/guides/administrator/Setup_Guide.md

@@ -0,0 +1,26 @@
+# Setup Guide
+
+To setup CyMaIS follow this steps: 
+
+## Prerequisites
+
+Before you setup CyMaIS you need to install [Kevin's Package Manager](https://github.com/kevinveenbirkenbach/package-manager).
+Follow the installation instruction descriped [here](https://github.com/kevinveenbirkenbach/package-manager)
+
+## Setup CyMaIS
+
+To setup CyMaIS execute: 
+
+```bash
+pkgmgr install cymais
+```
+
+This command will setup CyMaIS on your system with the alias **cymais**.
+
+## Get Help 
+
+After you setuped CyMaIS you can recieve more help by executing: 
+
+```bash
+cymais --help
+```

docs/guides/customer/Readme.md

@@ -0,0 +1,17 @@
+# Customer Guide
+
+Are you looking for a **reliable IT infrastructure** for your business or organization? **CyMaIS** is here to help!
+
+## Who Can Benefit? 🎯
+✅ **Small & Medium Businesses** - IT infrastructure with everything included what you need. E.g. data clouds, mailservers, vpn's, homepages, documentation tools, etc.
+✅ **Enterprises** - Scale the solutions for Small & Medium Businesses up for an unlimeted amount of users
+✅ **NGOs & Organizations** - Secure, cost-effective infrastructure solutions on Open Source Base
+✅ **Journalists & Content Creators** - Host your content on your own servers, share it via the Fediverse and avoid cencorship
+
+## Why Choose CyMaIS? 🚀
+- **Fast Deployment** - Get your IT setup running in minutes
+- **Security First** - Encrypted backups, 2FA, and secure logins
+- **Scalable & Customizable** - Adapts to your specific needs
+- **Cost-Effective** - Open-source, no licensing fees
+
+For enterprise solutions, check [Enterprise Solutions](10_ENTERPRISE_SOLUTIONS.md) or contact [Kevin Veen-Birkenbach](mailto:kevin@veen.world).

docs/guides/developer/index.rst

@@ -0,0 +1,53 @@
+Developer Guide
+===============
+
+Welcome to the **CyMaIS Developer Guide**! This guide provides essential information for developers who want to contribute to the CyMaIS open-source project.
+
+Explore CyMaIS Solutions
+------------------------
+CyMaIS offers various solutions for IT infrastructure automation. Learn more about the available applications:
+
+- :doc:`../../../roles/application_glosar`
+- :doc:`../../../roles/application_categories`
+
+For Developers
+--------------
+
+Understanding Ansible Roles
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+CyMaIS is powered by **Ansible** roles to automate deployments. Developers can explore the technical details of our roles here:
+
+- :doc:`../../../roles/ansible_role_glosar`
+
+Contributing to CyMaIS
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Want to contribute to the project or explore the source code? Check out our **GitHub repository**:
+
+- `CyMaIS GitHub Repository <https://github.com/kevinveenbirkenbach/cymais/tree/master/roles>`_
+
+Contribution Guidelines
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+1. **Fork the Repository** – Start by forking the CyMaIS repository.
+2. **Create a New Branch** – Make changes in a dedicated branch.
+3. **Follow Coding Standards** – Ensure your code is well-documented and follows best practices.
+4. **Submit a Pull Request** – Once your changes are tested, submit a PR for review.
+
+For detailed guidelines, refer to:
+
+- :doc:`../../../CONTRIBUTING`
+- :doc:`../../../CODE_OF_CONDUCT`
+
+Community & Support
+-------------------
+If you have questions or need help, visit the **CyMaIS Information Hub**:
+
+- `hub.cymais.cloud <https://hub.cymais.cloud>`_
+
+This is the best place to ask questions, get support, and collaborate with other contributors.
+
+Stay connected, collaborate, and help improve CyMaIS together!
+
+Happy coding! 🚀

docs/guides/investors/Readme.md

@@ -0,0 +1,15 @@
+# Investor Guide
+
+🚀 **CyMaIS is seeking investors** to expand its reach and continue development. With an increasing demand for automated IT solutions, **CyMaIS has the potential to revolutionize IT infrastructure management.**
+
+## Market Potential 📈
+- **$500B+ Global IT Infrastructure Market**
+- Growing **open-source adoption** across enterprises
+- Increasing need for **automation & cybersecurity**
+
+## Why Invest in CyMaIS? 🔥
+- **Unique Automation Approach** - Pre-configured roles for quick IT setup
+- **Security & Compliance Focus** - Built-in security best practices
+- **Scalability** - Modular framework adaptable to various industries
+
+Interested in investing? Contact **[Kevin Veen-Birkenbach](mailto:kevin@veen.world)** to discuss partnership opportunities.

docs/guides/user/Enterprise_Solutions.md

@@ -0,0 +1,17 @@
+# Enterprise Solutions
+
+**CyMaIS** provides powerful **enterprise-grade IT infrastructure solutions**, enabling businesses to scale securely and efficiently.
+
+## How CyMaIS Helps Enterprises 🔧
+- **Automated Deployment** - Set up secure servers & workstations effortlessly
+- **Advanced Security** - Integrated 2FA, LDAP, encrypted storage
+- **High Availability** - Scalable infrastructure for growing enterprises
+- **Compliance & Audit Logs** - Maintain regulatory standards
+
+## Use Cases 💼
+- ✅ **Cloud-Based Infrastructure** (Docker, Kubernetes, CI/CD pipelines)
+- ✅ **Enterprise Networking & VPN** (WireGuard, OpenVPN, Firewall rules)
+- ✅ **Database & Business Apps** (PostgreSQL, Nextcloud, ERP systems)
+- ✅ **Custom Security Solutions** (Keycloak, LDAP, 2FA enforcement)
+
+Interested? Contact [Kevin Veen-Birkenbach](mailto:kevin@veen.world) to discuss tailored enterprise solutions.

docs/guides/user/Readme.md

@@ -0,0 +1,66 @@
+# User Guide
+
+Welcome to **CyMaIS**! This guide is designed for **end-users** who want to use cloud services, email, and collaboration tools securely and efficiently. Whether you're an **enterprise user** or an **individual**, CyMaIS provides a wide range of services tailored to your needs.
+
+## What Can CyMaIS Do for You? 💡
+CyMaIS enables you to securely and efficiently use a variety of **cloud-based applications**, including:
+
+### 📂 Cloud Storage & File Sharing
+- **Nextcloud** – Securely store, sync, and share files across devices.
+- **OnlyOffice** – Work on documents, spreadsheets, and presentations directly within Nextcloud.
+- **LibreOffice** – A powerful office suite alternative to Microsoft Office.
+
+### 💬 Secure Communication & Collaboration
+- **Matrix (Element)** – Encrypted messaging for teams and individuals.
+- **XMPP** – Secure instant messaging with various supported clients.
+- **Mailu** – A private, self-hosted email solution.
+- **Etherpad** – Real-time collaborative document editing.
+- **BigBlueButton** – Web conferencing with screen sharing and presentations.
+- **Jitsi** – Secure video conferencing without account requirements.
+
+### 🎵 Social Media & Content Sharing
+- **Mastodon** – Decentralized microblogging platform (alternative to Twitter/X).
+- **Pixelfed** – Decentralized image sharing (alternative to Instagram).
+- **Friendica** – Social network supporting federation with Mastodon and others.
+- **Peertube** – Decentralized video streaming platform (alternative to YouTube).
+- **Funkwhale** – Self-hosted music streaming for individuals and communities.
+
+### 🎮 Entertainment & Media
+- **Jellyfin** – Open-source media server for movies, TV, and music.
+- **Kodi** – Media center application with extensive plugin support.
+- **qBittorrent** – Open-source torrent client with secure remote access.
+
+### 🔒 Privacy & Security
+- **WireGuard** – Secure and fast VPN solution.
+- **Tor Browser** – Browse the web anonymously and bypass censorship.
+- **Bitwarden** – Open-source password manager for secure credential storage.
+- **2FA Authentication** – Securely log in to your services with Two-Factor Authentication.
+
+### 🔧 Developer & Productivity Tools
+- **Gitea** – Self-hosted Git repository management (alternative to GitHub/GitLab).
+- **Jenkins** – Automate software development pipelines.
+- **Discourse** – Community discussion forums for support and engagement.
+- **MediaWiki** – Create and manage knowledge bases and wikis.
+
+## 🏢 Enterprise Users
+### How to Get Started 🏁
+If your organization provides CyMaIS services, follow these steps:
+- Your **administrator** will provide login credentials.
+- Access **cloud services** via a web browser or mobile apps.
+- For support, contact your **system administrator**.
+
+## 🏠 Private Users
+### How to Get Started 🏁
+If you're an **individual user**, you can sign up for CyMaIS services:
+- **Register an account** at [cymais.cloud](https://cymais.cloud).
+- Choose the applications and services you need.
+- Follow the setup guide and start using CyMaIS services immediately.
+
+## 📚 Learn More
+Discover more about CyMaIS applications:
+- :doc:`roles/application_glosar`
+- :doc:`roles/application_categories`
+
+For further information, visit our **[Information Hub](https://hub.cymais.cloud)** for tutorials, FAQs, and community support.
+
+You can also register for updates and support from our community.

docs/guides/user/Security_Guidelines.md

@@ -0,0 +1,23 @@
+# Security Guidelines
+
+CyMaIS is designed with security in mind. However, while following our guidelines can greatly improve your system’s security, no IT system can be 100% secure. Please report any vulnerabilities as soon as possible.
+
+For optimal personal security, we **strongly recommend** the following:
+
+- **Use a Password Manager**  
+  Use a reliable password manager such as [KeePass](https://keepass.info/) 🔐. (Learn more about [password managers](https://en.wikipedia.org/wiki/Password_manager) on Wikipedia.) KeePass is available for both smartphones and PCs, and it can automatically generate strong, random passwords.
+
+- **Enable Two-Factor Authentication (2FA)**  
+  Always enable 2FA whenever possible. Many password managers (like KeePass) can generate [TOTP](https://en.wikipedia.org/wiki/Time-based_One-Time_Password) tokens, adding an extra layer of security even if your password is compromised.  
+  Synchronize your password database across devices using the [Nextcloud Client](https://nextcloud.com/) 📱💻.
+
+- **Use Encrypted Systems**  
+  We recommend running CyMaIS only on systems with full disk encryption. For example, Linux distributions such as [Manjaro](https://manjaro.org/) (based on ArchLinux) with desktop environments like [GNOME](https://en.wikipedia.org/wiki/GNOME) provide excellent security. (Learn more about [disk encryption](https://en.wikipedia.org/wiki/Disk_encryption) on Wikipedia.)
+
+- **Beware of Phishing and Social Engineering**  
+  Always verify email senders, avoid clicking on unknown links, and never share your passwords or 2FA codes with anyone. (Learn more about [Phishing](https://en.wikipedia.org/wiki/Phishing) and [Social Engineering](https://en.wikipedia.org/wiki/Social_engineering_(security)) on Wikipedia.)
+
+Following these guidelines will significantly enhance your personal security—but remember, no system is completely immune to risk.
+
+A tutorial how to setup secure password management you will find [here](https://blog.veen.world/blog/2025/04/04/%f0%9f%9b%a1%ef%b8%8f-keepassxc-cymais-cloud-the-ultimate-guide-to-cross-device-password-security/)
+---

docs/overview/Features.md

@@ -0,0 +1,26 @@
+# 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:
+
+## Effortless Setup and Management 🚀
+Setting up and managing IT systems has never been easier. CyMaIS automates complex tasks, whether on Linux servers or personal computers, reducing manual effort and saving valuable time.
+
+## Comprehensive IT Solutions 🛠️
+CyMaIS covers everything from essential system setups to advanced configurations, including VPN, Docker, Ansible-based deployments, security optimizations, and monitoring tools. This makes IT management seamless and efficient.
+
+## Tailored for Your Needs 🎯
+Every business is unique, and so is CyMaIS! With a modular architecture, it adapts to specific requirements, whether for startups, growing businesses, NGOs, or large enterprises.
+
+## Proactive Monitoring & Maintenance 🔍
+With automated updates, system health checks, and security audits, CyMaIS ensures your infrastructure is always up-to-date and running smoothly. Roles such as `health-docker-container`, `health-btrfs`, and `health-nginx` help monitor system integrity.
+
+## Uncompromised Security 🔒
+Security is a top priority! CyMaIS includes robust security features like full-disk encryption recommendations, 2FA enforcement, encrypted server deployments (`docker-keycloak`, `docker-ldap`), and secure backup solutions (`backup-remote-to-local`, `backup-data-to-usb`).
+
+## User-Friendly with Expert Support 👩‍💻
+No need to be a Linux or Docker expert! CyMaIS simplifies deployment with intuitive role-based automation. Documentation and community support make IT administration accessible to all experience levels.
+
+## Open Source Trust & Transparency 🔓
+As an open-source project, CyMaIS guarantees transparency, security, and community-driven development, ensuring continuous improvements and adherence to industry best practices.
+
+For further information, check out the [application glosar](roles/application_glosar), [applications ordered by category](roles/application_categories) and the [detailled ansible role descriptions](roles/ansible_role_glosar).

docs/overview/Vision.md

@@ -0,0 +1,11 @@
+# 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.
+
+This tool, grounded firmly in Open Source principles, will not only champion transparency and innovation but also ensure adaptability and accessibility for every business, regardless of its size or industry. We aim to make the complex process of IT setup not just simpler but also faster.
+
+We envision a future where businesses are no longer constrained by the complexities of IT infrastructure setup. Instead, they will be empowered with a tool that seamlessly integrates into their operational fabric, offering a robust, secure, and scalable digital backbone. This tool will not only cater to the immediate IT needs of a company but also be agile enough to evolve with their growing demands and the ever-changing technological landscape.
+
+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.