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/web-app-nextcloud/docs/Administration.md

@@ -0,0 +1,20 @@
+# Administration 
+
+Instructions for manual administrative operations like container login, config file edits, and post-update recovery actions.
+
+## Modify Config 🔧
+
+### Enter the Container
+```bash
+docker-compose exec -it application /bin/sh
+```
+
+### Modify the Configuration
+Inside the container, install a text editor and edit the config:
+```bash
+apk add --no-cache nano && nano config/config.php
+```
+
+## Logs
+
+The logs you will find here on the host: **/var/lib/docker/volumes/nextcloud_data/_data/data/nextcloud.log**

roles/web-app-nextcloud/docs/Applications.md

@@ -0,0 +1,32 @@
+# Nextcloud Applications
+
+Details on specific apps like Cospend, including related SQL queries and debugging tips.
+
+## receive Plugin Information
+To receive the relevant configuration options for a plugin type:
+```bash
+docker compose exec -u www-data application php occ config:list oidc_login
+```
+
+## App Relevant Tables 🗃️
+
+- `oc_appconfig`
+- `oc_migrations`
+
+## LDAP
+
+## Cospend 
+
+### Relevant SQL Commands for Cospend
+Debugguging Migrations: 
+
+https://github.com/julien-nc/cospend-nc/issues/325
+
+```sql
+-- Show all Cospend Tables
+SHOW TABLES where Tables_in_nextcloud LIKE "%cospend%";
+-- Show Cospend Configuration
+SELECT * FROM `oc_appconfig` WHERE appid LIKE "%cospend%";
+-- Show Cospend Database Migrations 
+SELECT * FROM `oc_migrations` WHERE app LIKE "%cospend%";
+```

roles/web-app-nextcloud/docs/Database.md

@@ -0,0 +1,15 @@
+# Database Management (local)
+
+To manage the database if you installed it locally use the following comments. If you have created the database via the central database option, look for the related documentation.
+
+
+## Database Access
+To access the database, execute:
+```bash
+docker-compose exec -it database mysql -u nextcloud -D nextcloud -p
+```
+
+### Recreate Database with New Volume
+```bash
+docker-compose run --detach --name database --env MYSQL_USER="nextcloud" --env MYSQL_PASSWORD=PASSWORD --env MYSQL_ROOT_PASSWORD=PASSWORD --env MYSQL_DATABASE="nextcloud" -v nextcloud_database:/var/lib/mysql
+```

roles/web-app-nextcloud/docs/IAM.md

@@ -0,0 +1,72 @@
+# Identity and Access Management
+IAM(Identity and Access Management) is setup via Keycloak and LDAP.
+
+## OpenID Connect (OIDC) Support 🔐
+
+OIDC is supported in this role—for example, via **Keycloak**. OIDC-specific tasks are included when enabled, allowing integration of external authentication providers seamlessly.
+
+### Verify OIDC Configuration
+
+```bash
+docker compose exec -u www-data application /var/www/html/occ config:app:get sociallogin custom_providers
+```
+
+## LDAP 
+
+More information: https://docs.nextcloud.com/server/latest/admin_manual/configuration_user/user_auth_ldap.html
+
+## Get LDAP Configuration
+
+```bash
+docker compose exec -u www-data application php occ ldap:show-config
+```
+
+## Get all relevant entries except password
+
+```sql
+SELECT * FROM `oc_appconfig` WHERE appid LIKE "%ldap%" and configkey != "s01ldap_agent_password";
+```
+
+## Update User with LDAP values
+
+```bash
+docker compose exec -it -u www-data application php occ ldap:check-user --update {{username}}
+```
+
+## Update LDAP Sync
+
+```bash
+docker compose exec -u www-data application php occ user:sync-account-data
+```
+
+### Update Each User
+If you want to update **every LDAP user**, run:
+
+```bash
+for user in $(docker compose exec -u www-data application php occ user:list --output=json | jq -r 'keys[]'); do
+    docker compose exec -u www-data application php occ ldap:check-user --update "$user"
+done
+```
+
+### Unlink All
+```bash
+for user in $(docker compose exec -u www-data application php occ ldap:show-remnants | tail -n +3 | awk -F '|' '{print $2}' | tr -d ' ' | grep -v '^$'); do
+    echo "Unlinking user from LDAP: $user"
+    echo "y" | docker compose exec -T -u www-data application php occ ldap:reset-user "$user"
+done
+```
+
+### Reset LDAP Links for Orphaned Users
+Run this **corrected script**:
+
+```bash
+for user in $(docker compose exec -u www-data application php occ ldap:show-remnants | tail -n +3 | awk -F '|' '{print $2}' | tr -d ' ' | grep -v '^$'); do
+    echo "Resetting LDAP link for user: $user"
+    echo "y" | docker compose exec -T -u www-data application php occ ldap:reset-user "$user"
+done
+```
+
+
+## Federation
+
+If users are just created via Keycloak and not via LDAP, they have a different username. Due to this reaso concider to use LDAP to guaranty that the username is valid. 

roles/web-app-nextcloud/docs/LDAP.md

@@ -0,0 +1,41 @@
+## Add LDAP Users Manually for Immediate Sharing
+
+In a default Nextcloud + LDAP setup, user accounts are only created in the internal Nextcloud database **after their first login**. This means that even if a user exists in LDAP, they **cannot receive shared files or folders** until they have logged in at least once—or are manually synchronized.
+
+To make LDAP users available for sharing **without requiring initial login**, follow these steps:
+
+### 1. Search for the User in LDAP
+
+Check if the user exists in the configured LDAP directory:
+
+```bash
+docker exec -u www-data nextcloud-application php occ ldap:search <username>
+```
+
+If the user is found, proceed to the next step.
+
+### 2. Create the User in Nextcloud from LDAP
+
+Manually trigger a sync to register the user in the Nextcloud database:
+
+```bash
+docker exec -u www-data nextcloud-application php occ ldap:check-user --update <username>
+```
+
+**Example:**
+
+```bash
+docker exec -u www-data nextcloud-application php occ ldap:check-user --update viktoriakaffanke
+```
+
+Once executed, the user becomes fully available in the system—for sharing, group membership, and permissions—even without logging in.
+
+### 3. Synchronize All Known Users (Optional)
+
+To synchronize account data (display name, mail address, group memberships, etc.) for **all users** currently known to Nextcloud:
+
+```bash
+docker exec -u www-data nextcloud-application php occ user:sync-account-data
+```
+
+This step is especially useful after modifying LDAP attributes or group memberships, ensuring up-to-date data in the Nextcloud UI and permission system.

roles/web-app-nextcloud/docs/OCC.md

@@ -0,0 +1,28 @@
+
+# OCC (Nextcloud Command Line) 🔧
+
+Reference for frequently used OCC commands, including user and app management.
+
+## General Use
+
+To use OCC, run:
+```bash
+docker-compose exec -it -u www-data application /var/www/html/occ
+```
+
+## App Administration
+```bash
+docker compose exec -u www-data application php occ config:list {{app_name}}
+```
+
+## Initialize Duplicates
+```bash
+docker-compose exec -it -u www-data application /var/www/html/occ duplicates:find-all --output
+```
+
+## Unlock Files
+```bash
+docker-compose exec -it -u www-data application /var/www/html/occ maintenance:mode --on
+docker-compose exec -it nextcloud_database_1 mysql -u nextcloud -pPASSWORD1234132 -D nextcloud -e "delete from oc_file_locks where 1"
+docker-compose exec -it -u www-data application /var/www/html/occ maintenance:mode --off
+```

roles/web-app-nextcloud/docs/README.md

@@ -0,0 +1,14 @@
+# Nextcloud Docs for CyMaIS
+
+This folder contains the Nextcloud Docs for CyMaIS.
+
+## Index
+
+Operational guidance can be found in the following supporting documentation files:
+- [Applications.md](Applications.md)
+- [Architecture.md](Architecture.md)
+- [Administration.md](Administration.md)
+- [Update.md](Update.md)
+- [OCC.md](OCC.md)
+- [Database.md](Database.md)
+- [IAM.md](IAM.md)

roles/web-app-nextcloud/docs/Update.md

@@ -0,0 +1,53 @@
+# Update 🔄
+
+To update the Nextcloud container, execute the following commands on the server:
+```bash
+docker exec -it -u www-data nextcloud-application /var/www/html/occ maintenance:mode --on &&
+export COMPOSE_HTTP_TIMEOUT=600 &&
+export DOCKER_CLIENT_TIMEOUT=600 &&
+docker-compose down
+```
+
+Afterwards, update the ***applications.nextcloud.version*** variable to the next version and run this repository with this Ansible role.
+
+> **Note:**  
+> It is only possible to update from one to the next major version at a time.  
+> Wait for the update to finish.
+
+Verify the update by checking the logs:
+```bash
+docker-compose logs application
+```
+and
+```bash
+docker-compose exec -it application top
+```
+
+If Nextcloud remains in maintenance mode after the update, try the following:
+```bash
+docker exec -it -u www-data nextcloud-application/var/www/html/occ maintenance:mode --on
+docker exec -it -u www-data nextcloud-application /var/www/html/occ upgrade
+docker exec -it -u www-data nextcloud-application /var/www/html/occ maintenance:mode --off
+```
+
+If the update process fails, execute:
+```bash
+docker exec -it -u www-data nextcloud-application /var/www/html/occ maintenance:repair --include-expensive
+```
+and disable any non-functioning apps.
+
+---
+
+## Recover Latest Backup 💾
+
+```bash
+cd {{path_docker_compose_instances}}nextcloud &&
+docker-compose down &&
+docker-compose exec -i database mysql -u nextcloud -pPASSWORT nextcloud < "/Backups/$(sha256sum /etc/machine-id | head -c 64)/backup-docker-to-local/latest/nextcloud_database/sql/backup.sql" &&
+cd {{path_administrator_scripts}}backup-docker-to-local &&
+bash ./recover-web-app-from-local.sh "nextcloud_data" "$(sha256sum /etc/machine-id | head -c 64)"
+```
+
+## Other Resources
+
+- [Nextcloud Upgrade via Docker by Goneuland](https://goneuland.de/nextcloud-upgrade-auf-neue-versionen-mittels-docker/)

roles/web-app-nextcloud/docs/Users.md

@@ -0,0 +1,43 @@
+# User Administration 
+
+### List Users
+```bash
+docker compose exec -it -u www-data application php occ user:list
+```
+
+### Get User Info
+```bash
+docker compose exec -u www-data application php occ user:info {{username}}
+```
+
+### Sync Users
+```bash
+docker compose exec -it -u www-data application php occ user:sync
+```
+
+### Create user via CLI
+```bash
+docker compose exec -it -u www-data application php occ user:add {{username}}
+```
+
+### Make user admin via cli
+```bash
+docker compose exec -it -u www-data application php occ group:adduser admin {{username}}
+```
+
+### Delete user via CLI
+```bash
+docker compose exec -it -u www-data application php occ user:delete {{username}}
+```
+
+### Delete all User (if no ldap is used)
+```bash 
+for user in $(docker compose exec -u www-data application php occ user:list --output=json | jq -r 'keys[]'); do
+    docker compose exec -u www-data application php occ user:delete "$user"
+done
+```
+
+### Identify users which exist still in nextcloud but not in LDAP anymore
+```bash 
+occ ldap:show-remnants
+```