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
+```