Solved bugs, restructured and added new functionality for clients/personal computers

07_SETUP_GUIDE.md

@@ -12,7 +12,7 @@ Follow the installation instruction descriped [here](https://github.com/kevinvee
 To setup CyMaIS execute: 
 
 ```bash
-pkgmgr setup cymais
+pkgmgr install cymais
 ```
 
 This command will setup CyMaIS on your system with the alias **cymais**.

09_DEPLOY.md

@@ -1,22 +1,100 @@
-# Deploy
+# 🚀 Deployment Guide
 
-This guide explains how to deploy and manage the Cyber Master Infrastructure Solution (CyMaIS) using Ansible. CyMaIS is based on a collection of ansible tasks. The tasks use different “modes” to control behavior such as updates, backups, resets, and cleanup tasks. 
+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
-- **Inventory File:** Have an inventory file that lists your servers and PCs. (Paths in examples are general; adjust them to your environment.)
-- **Cymais Installed:** CyMaIS is installed via [Kevin's Package-Manager](https://github.com/kevinveenbirkenbach/package-manager).
-- **Vault Password File (Optional):** Prepare a file with your vault password if you prefer not to enter it interactively.
+---
 
-## Deploying on Servers
-To get detailled information how to use CyMaIS to deploy software to your server execute:
-```sh
+## ✅ 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
 ```
 
-## Using a Password File
+---
+
+## 💡 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:
 
-To avoid entering your vault password interactively every time, use the `--password-file` option:
 ```bash
 --password-file /path/to/your/vault_pass.txt
 ```
-Ensure the vault password file is stored securely.
+
+> ⚠️ **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)

roles/client-browser/README.md

@@ -6,7 +6,7 @@ This Ansible role serves as a wrapper to install and configure multiple browsers
 
 ## Overview
 
-The **pc-browsers** role orchestrates the deployment of two specialized roles: **pc-browser-chromium** and **pc-browser-firefox**. By executing both roles, it provides a unified solution for browser management, making it easier to maintain a secure and consistent browsing environment across your systems.
+The **client-browser** role orchestrates the deployment of two specialized roles: **client-browser-chromium** and **client-browser-firefox**. By executing both roles, it provides a unified solution for browser management, making it easier to maintain a secure and consistent browsing environment across your systems.
 
 ## Purpose
 

roles/client-browser/meta/main.yml

@@ -34,5 +34,5 @@ galaxy_info:
   issue_tracker_url: https://s.veen.world/cymaisissues
   documentation: https://s.veen.world/cymais
 dependencies:
-  - pc-browser-chromium
-  - pc-browser-firefox
+  - client-browser-chromium
+  - client-browser-firefox

roles/client-git/README.md

@@ -1,4 +1,4 @@
-# Git for Personal Computers
+# Git
 
 ## Description
 

roles/client-nextcloud/README.md

@@ -0,0 +1,28 @@
+# Nextcloud Client ☁️
+
+## Description
+
+This Ansible role installs and configures the Nextcloud desktop client on Arch Linux systems. It also manages symbolic links from commonly used user directories (like `Documents`, `Pictures`, etc.) to the respective folders inside a cloud-synced Nextcloud directory. This ensures user data is seamlessly integrated into the synchronized cloud folder.
+
+## Overview
+
+Targeting user environments on Arch Linux (e.g., Manjaro), this role sets up the official `nextcloud-client` and dynamically links key directories from the user's home folder to Nextcloud. This makes it easy to use the Nextcloud client without needing to manually configure folders.
+
+## Purpose
+
+The purpose of this role is to automate the configuration of cloud-integrated user directories by ensuring that common folders like `Downloads`, `Music`, and `Workspaces` are transparently redirected into a centralized cloud structure. This makes it easier to maintain backup-friendly, cloud-ready setups for homelab and professional workflows.
+
+## Features
+
+- **Installs the Nextcloud Desktop Client:** Uses `pacman` via the `community.general.pacman` module.
+- **Symbolic Linking of User Folders:** Maps home folders (e.g., `Documents`, `Videos`, `Workspaces`) into their Nextcloud equivalents.
+- **Dynamic Cloud Directory Resolution:** Builds the target cloud directory path from user and cloud variables.
+- **Dump Folder Mapping:** Links `InstantUpload` from the cloud to a `~/Dump` folder for quick camera/file access.
+
+## Credits 📝
+
+Developed and maintained by **Kevin Veen-Birkenbach**.  
+Learn more at [www.veen.world](https://www.veen.world)
+
+Part of the [CyMaIS Project](https://github.com/kevinveenbirkenbach/cymais)  
+License: [CyMaIS NonCommercial License (CNCL)](https://s.veen.world/cncl)

roles/client-nextcloud/meta/main.yml

@@ -0,0 +1,27 @@
+---
+galaxy_info:
+  author: "Kevin Veen-Birkenbach"
+  description: "Installs and links Nextcloud desktop client folders for cloud-integrated user environments."
+  license: "CyMaIS NonCommercial License (CNCL)"
+  license_url: "https://s.veen.world/cncl"
+  company: | 
+    Kevin Veen-Birkenbach
+    Consulting & Coaching Solutions
+    https://www.veen.world
+  min_ansible_version: "2.9"
+  platforms:
+    - name: Archlinux
+      versions:
+        - rolling
+  galaxy_tags:
+    - nextcloud
+    - cloud
+    - archlinux
+    - user
+    - desktop
+    - automation
+  repository: https://s.veen.world/cymais
+  issue_tracker_url: https://s.veen.world/cymaisissues
+  documentation: https://s.veen.world/cymais
+
+dependencies: []

roles/client-nextcloud/tasks/main.yml

@@ -10,6 +10,8 @@
     owner: "{{users.client.username}}"
     group: "{{users.client.username}}"
     state: link
+    force: yes
+  ignore_errors: true # Just temporary @todo remove
   loop:
     - Templates
     - Documents

roles/client-ssh/README.md

@@ -0,0 +1,33 @@
+# SSH Agent 🔐
+
+## Description
+
+This Ansible role ensures a functional and persistent SSH Agent setup on Arch Linux (Manjaro) systems running GNOME with Wayland. It manages SSH configuration by cloning a remote Git repository into the user's `~/.ssh` directory and sets up a systemd user service to start the SSH agent automatically at login.
+
+To understand the broader context of SSH, read more on [Wikipedia – SSH](https://en.wikipedia.org/wiki/Secure_Shell) or visit the official [OpenSSH project](https://www.openssh.com/).
+
+This role was designed and validated in the context of [this discussion](https://chatgpt.com/share/67ed0e25-7240-800f-9ab2-9fffc569bc20) on configuring SSH agents for KeePassXC compatibility under Wayland sessions.
+
+## Overview
+
+This role is intended for Manjaro/Arch systems where `gnome-keyring` no longer reliably manages `ssh-agent` due to changes in behavior under Wayland. It works by deploying a `systemd --user` service, making SSH Agent integration predictable and independent of graphical environment quirks.
+
+## Purpose
+
+The purpose of this role is to automate the provisioning of SSH agent capabilities and synchronize the `.ssh` directory from a Git repository. This enables users to access private repositories or authenticate with remote servers immediately after login.
+
+## Features
+
+- **Clones a remote SSH config repository** into `~/.ssh` using the `client-git` role.
+- **Deploys and enables a systemd user service** for `ssh-agent`.
+- **Ensures environment compatibility** by injecting the `SSH_AUTH_SOCK` variable into either `.bash_profile` or `.profile`.
+- **Fails gracefully** with an optional debug message if the Git repository is unreachable.
+- **KeePassXC ready**: Ensures compatibility with password managers that support SSH agent integration.
+
+## Credits 📝
+
+Developed and maintained by **Kevin Veen-Birkenbach**.  
+Learn more at [www.veen.world](https://www.veen.world)
+
+Part of the [CyMaIS Project](https://github.com/kevinveenbirkenbach/cymais)  
+License: [CyMaIS NonCommercial License (CNCL)](https://s.veen.world/cncl)

roles/client-ssh/meta/main.yml

@@ -0,0 +1,29 @@
+---
+galaxy_info:
+  author: "Kevin Veen-Birkenbach"
+  description: "Persistent SSH agent setup for GNOME Wayland sessions with SSH configuration pulled from Git."
+  license: "CyMaIS NonCommercial License (CNCL)"
+  license_url: "https://s.veen.world/cncl"
+  company: | 
+    Kevin Veen-Birkenbach
+    Consulting & Coaching Solutions
+    https://www.veen.world
+  min_ansible_version: "2.9"
+  platforms:
+    - name: Archlinux
+      versions:
+        - rolling
+  galaxy_tags:
+    - ssh
+    - agent
+    - systemd
+    - gnome
+    - wayland
+    - archlinux
+    - keepassxc
+  repository: https://s.veen.world/cymais
+  issue_tracker_url: https://s.veen.world/cymaisissues
+  documentation: https://s.veen.world/cymais
+
+dependencies:
+  - client-git

roles/client-ssh/tasks/main.yml

@@ -0,0 +1,55 @@
+- name: pull ssh repository from {{ssh_configuration_repository}}
+  git:
+    repo: "{{ssh_configuration_repository}}"
+    dest: "$HOME/.ssh"
+    update: yes
+  register: git_result
+  ignore_errors: true
+  become: false
+
+- name: Warn if repo is not reachable
+  debug:
+    msg: "Warning: Repository is not reachable."
+  when: git_result.failed and enable_debug | bool
+
+- name: Ensure systemd user directory exists
+  file:
+    path: "$HOME/.config/systemd/user"
+    state: directory
+    mode: "0700"
+  become: false
+
+- name: Deploy ssh-agent systemd unit file
+  template:
+    src: ssh-agent.service.j2
+    dest: "$HOME/.config/systemd/user/ssh-agent.service"
+    mode: "0644"
+  become: false
+
+- name: Enable and start ssh-agent service
+  systemd:
+    name: ssh-agent.service
+    scope: user
+    enabled: true
+    state: started
+    daemon_reload: true
+  become: false
+
+- name: Set SSH_AUTH_SOCK in bash_profile or profile
+  block:
+    - name: Choose profile file
+      set_fact:
+        profile_file: "$HOME/.bash_profile"
+      when: ansible_facts.env.HOME is defined and lookup('file', ansible_env.HOME + '/.bash_profile', errors='ignore') is defined
+
+    - name: Fallback to .profile if .bash_profile not found
+      set_fact:
+        profile_file: "$HOME/.profile"
+      when: profile_file is not defined
+
+    - name: Ensure SSH_AUTH_SOCK is set in profile
+      lineinfile:
+        path: "{{ profile_file }}"
+        line: 'export SSH_AUTH_SOCK="$XDG_RUNTIME_DIR/ssh-agent.socket"'
+        insertafter: EOF
+        state: present

roles/client-ssh/templates/ssh-agent.service.j2

@@ -0,0 +1,11 @@
+[Unit]
+Description=User SSH Agent
+Before=default.target
+
+[Service]
+Type=simple
+Environment=SSH_AUTH_SOCK=%t/ssh-agent.socket
+ExecStart=/usr/bin/ssh-agent -D -a $SSH_AUTH_SOCK
+
+[Install]
+WantedBy=default.target

roles/pc-administrator-tools/meta/main.yml

@@ -1,3 +1,3 @@
 dependencies:
-- pc-git
+- client-git
 - make

roles/pc-gnome-caffeine/tasks/main.yml

@@ -4,6 +4,7 @@
     use: yay
     name:
       - caffeine-ng
+  become: false
 
 - name: Create autostart directory if it doesn't exist
   file:

roles/pc-nextcloud/README.md

@@ -1,41 +0,0 @@
-# PC-Nextcloud Role
-
-## 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
-The `vars/main.yml` file defines key variables used in this role:
-- `user_home_directory`: The home directory of the user, typically `/home/{{users.client.username}}/`.
-- `cloud_directory`: The directory path for Nextcloud cloud storage, structured as `{{user_home_directory}}Clouds/{{cloud_fqdn}}/{{users.client.username}}/`.
-
-## Role Tasks
-The `main.yml` file in the `pc-nextcloud` role comprises the following tasks:
-
-1. **Install Nextcloud-Client**:
-   - Installs the Nextcloud desktop client using the `community.general.pacman` module.
-
-2. **Link Homefolders to Cloud**:
-   - Creates symbolic links from various user directories (like Templates, Documents, Videos, etc.) to corresponding folders in the Nextcloud cloud directory. This ensures synchronization of these folders with the user's Nextcloud account.
-
-3. **Link Dump Folder**:
-   - Specifically links a `Dump` folder in the user's home directory to the `InstantUpload` folder in the Nextcloud cloud directory for easy file dumping and syncing.
-
-## Purpose and Usage
-The `pc-nextcloud` role is designed for users who want to integrate Nextcloud, a cloud storage service, into their daily workflow. This role automates the installation of the Nextcloud client and the setup of directory synchronization, making files and documents easily accessible and syncable across devices.
-
-## Prerequisites
-- **Ansible**: Required for running this role.
-- **Arch Linux-based System**: Since the role uses the `pacman` package manager, it's tailored for Arch Linux or similar distributions.
-
-## Running the Role
-To use this role:
-1. Clone the `cymais` repository.
-2. Navigate to the `roles/pc-nextcloud` directory.
-3. Ensure that the `users.client.username` and `cloud_fqdn` variables are correctly set to match your Nextcloud account details.
-4. Execute the role using Ansible, ensuring appropriate permissions are available for installations and configurations.
-
-## Customization
-You can customize this role by modifying the variables in `vars/main.yml` and adjusting the directories in the linking tasks to suit your specific Nextcloud setup and preferences.
-
-## Support and Contributions
-For support, suggestions, or contributions, such as adding additional features or improving the setup, open an issue or submit a pull request in the `cymais` repository. Contributions that enhance the integration and usability of Nextcloud on personal computers are highly welcome.

roles/pc-office/meta/main.yml

@@ -1,3 +1,3 @@
 dependencies:
 - pc-libreoffice
-- pc-browsers
+- client-browser

roles/pc-ssh/README.md

@@ -1,38 +0,0 @@
-# PC-SSH Role
-
-## 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
-The `pc-ssh` role includes tasks to pull and update SSH configuration from a specified repository and handle potential errors:
-
-1. **Pull SSH Repository**: 
-   - Clones or updates the SSH configuration from a given repository (`{{ssh_configuration_repository}}`) into the `$HOME/.ssh` directory. This task ensures that your SSH configuration is synchronized with the specified repository.
-
-2. **Warn if Repo is Not Reachable**:
-   - Displays a warning message if the SSH configuration repository is not reachable, indicating potential issues with the repository's availability or the network connection.
-
-## Dependencies
-This role depends on:
-- **pc-git**: Ensures that Git is installed, which is necessary for cloning and updating the SSH configuration repository.
-
-## Purpose and Usage
-The `pc-ssh` role is designed for users who require SSH access to remote servers, such as developers, system administrators, or IT professionals. By automating the SSH configuration process, this role streamlines the setup and ensures a consistent and secure SSH environment.
-
-## Prerequisites
-- **Ansible**: Must be installed to run this role.
-- **Git**: Required for cloning and updating the SSH configuration repository.
-- **Arch Linux-based System**: While not explicitly stated, the role's compatibility with specific systems depends on the dependencies and the overall playbook configuration.
-
-## Running the Role
-To use this role:
-1. Clone the `cymais` repository.
-2. Navigate to the `roles/pc-ssh` directory.
-3. Define the `ssh_configuration_repository` variable with the URL of your SSH configuration repository.
-4. Run the role using Ansible, ensuring you have the necessary permissions for executing the tasks.
-
-## Customization
-You can customize this role by modifying the SSH configuration repository URL or by adding additional SSH-related tasks as needed.
-
-## Support and Contributions
-For support, feedback, or contributions, such as enhancing the SSH setup or adding more features, please open an issue or submit a pull request in the `cymais` repository. Contributions that improve SSH configuration and usage are highly encouraged.

roles/pc-ssh/meta/main.yml

@@ -1,2 +0,0 @@
-dependencies:
-- pc-git

roles/pc-ssh/tasks/main.yml

@@ -1,13 +0,0 @@
-- name: pull ssh repository from {{ssh_configuration_repository}}
-  git:
-    repo: "{{ssh_configuration_repository}}"
-    dest: "$HOME/.ssh"
-    update: yes
-  register: git_result
-  ignore_errors: true
-  become: false
-
-- name: Warn if repo is not reachable
-  debug:
-    msg: "Warning: Repository is not reachable."
-  when: git_result.failed

tasks/personal-computer.yml

@@ -48,14 +48,14 @@
     name: pc-latex
 
 - name: GNOME setup
-  when: ("gnome
+  when: ("gnome" in group_names)
   include_role:
     name: pc-gnome
 
 - name: setup ssh client
-  when: ("ssh" in group_names)
+  when: ("ssh-client" in group_names)
   include_role:
-    name: pc-ssh
+    name: client-ssh
 
 - name: setup gaming hosts
   when: ("gaming" in group_names)
@@ -72,13 +72,13 @@
   include_role:
     name: pc-torbrowser
 
-- name: setup nextcloud
+- name: setup nextcloud-client
   when: ("nextcloud_client" in group_names)
   include_role:
-    name: pc-nextcloud
+    name: client-nextcloud
 
 - name: setup docker
-  when: ("dockerin group_names)
+  when: ("docker" in group_names)
   include_role:
     name: pc-docker