From 4fbf8f505cd5ead95d1d6b68015b8c8c9584dcbc Mon Sep 17 00:00:00 2001
From: Kevin Veen-Birkenbach <kevin@veen.world>
Date: Tue, 17 Jun 2025 12:29:33 +0200
Subject: [PATCH] Solved moodle database character issue:
 https://github.com/bitnami/containers/issues/81439#issuecomment-2977590924

---
 roles/docker-compose/tasks/create-files.yml |  2 +-
 roles/docker-mariadb/defaults/README.md     | 44 +++++++++++++++++++++
 roles/docker-mariadb/defaults/main.yml      |  3 ++
 roles/docker-mariadb/tasks/main.yml         | 12 +++---
 roles/docker-mariadb/vars/README.md         | 34 ++++++++++++++++
 roles/docker-moodle/Administration.md       | 28 +++++++++++++
 roles/docker-moodle/TODO.md                 |  3 +-
 7 files changed, 118 insertions(+), 8 deletions(-)
 create mode 100644 roles/docker-mariadb/defaults/README.md
 create mode 100644 roles/docker-mariadb/defaults/main.yml
 create mode 100644 roles/docker-mariadb/vars/README.md
 create mode 100644 roles/docker-moodle/Administration.md

diff --git a/roles/docker-compose/tasks/create-files.yml b/roles/docker-compose/tasks/create-files.yml
index 2b794cde..58acc5a3 100644
--- a/roles/docker-compose/tasks/create-files.yml
+++ b/roles/docker-compose/tasks/create-files.yml
@@ -1,6 +1,6 @@
 - name:           "Create (optional) '{{ docker_compose.files.dockerfile }}'"
   template:
-    src:          "{{ playbook_dir }}/roles/{{ role_name }}/templates/Dockerfile"
+    src:          "{{ playbook_dir }}/roles/{{ role_name }}/templates/Dockerfile.j2"
     dest:         "{{ docker_compose.files.dockerfile }}"
   notify:         docker compose project build and setup
   ignore_errors:  false
diff --git a/roles/docker-mariadb/defaults/README.md b/roles/docker-mariadb/defaults/README.md
new file mode 100644
index 00000000..728f29f9
--- /dev/null
+++ b/roles/docker-mariadb/defaults/README.md
@@ -0,0 +1,44 @@
+# defaults/
+
+This directory contains default variable definition files for the `docker-mariadb` Ansible role. It centralizes all configurable values related to MariaDB deployment and can be adjusted without modifying task logic.
+
+---
+
+## files and their purpose
+
+### `main.yml`
+
+Defines default values for how the MariaDB database should be created.
+
+* **`database_encoding`** (string):
+
+  * **Default:** `"utf8mb4"`
+  * **Reasoning:**
+
+    * **Full Unicode support**: `utf8mb4` is the only MySQL/MariaDB character set that fully implements 4‑byte UTF‑8, allowing storage of emojis, supplementary symbols, and all global scripts without data loss.
+    * **Future‑proof:** Modern applications and standards have converged on UTF‑8; using `utf8mb4` avoids migration challenges later.
+    * **Performance trade‑off:** While slightly more storage might be used compared to `latin1`, the universality of `utf8mb4` outweighs the cost for most deployments.
+
+* **`database_collation`** (string):
+
+  * **Default:** `"utf8mb4_unicode_ci"`
+  * **Reasoning:**
+
+    * **Accurate sorting & comparison:** This collation uses full Unicode algorithm rules, ensuring linguistically correct comparisons across many languages.
+    * **Case‑insensitive (`ci`):** Most web apps expect case‑insensitive matching for usernames, emails, and search queries, improving usability.
+    * **Neutral choice:** Unlike language‑specific collations, `unicode_ci` works robustly in multilingual contexts without bias.
+
+> **Tip:** If you have a legacy application requiring a different charset or collation (e.g., for backward compatibility with existing data), simply override `database_encoding` and `database_collation` in your playbook-level variables.
+
+## Overriding default variables
+
+To customize any of these values without editing role defaults:
+
+1. Create or update a playbook-level vars file (e.g. `group_vars/all/docker-mariadb.yml`).
+2. Set the desired values, for example:
+
+   ```yaml
+   database_encoding: "latin1"
+   database_collation: "latin1_swedish_ci"
+   ```
+3. Run your playbook—Ansible’s variable precedence ensures your overrides take effect.
\ No newline at end of file
diff --git a/roles/docker-mariadb/defaults/main.yml b/roles/docker-mariadb/defaults/main.yml
new file mode 100644
index 00000000..fa676261
--- /dev/null
+++ b/roles/docker-mariadb/defaults/main.yml
@@ -0,0 +1,3 @@
+# Check out the README.md file for more information, why this encodings and collations are used
+database_encoding:  "utf8mb4"
+database_collation: "utf8mb4_unicode_ci"
\ No newline at end of file
diff --git a/roles/docker-mariadb/tasks/main.yml b/roles/docker-mariadb/tasks/main.yml
index 27aafa70..182c2ec0 100644
--- a/roles/docker-mariadb/tasks/main.yml
+++ b/roles/docker-mariadb/tasks/main.yml
@@ -53,12 +53,14 @@
 
 - name: "Create database: {{ database_name }}"
   mysql_db:
-    name: "{{ database_name }}"
-    state: present
-    login_user: root
+    name:           "{{ database_name }}"
+    state:          present
+    login_user:     root
     login_password: "{{ applications.mariadb.credentials.root_password }}"
-    login_host: 127.0.0.1
-    login_port: "{{database_port}}"
+    login_host:     127.0.0.1
+    login_port:     "{{ database_port }}"
+    encoding:       "{{ database_encoding }}"
+    collation:      "{{ database_collation }}"
 
 - name: "Create database user: {{ database_username }}"
   mysql_user:
diff --git a/roles/docker-mariadb/vars/README.md b/roles/docker-mariadb/vars/README.md
new file mode 100644
index 00000000..49b7ded8
--- /dev/null
+++ b/roles/docker-mariadb/vars/README.md
@@ -0,0 +1,34 @@
+# vars/
+
+This directory contains variable definition files for the `docker-mariadb` Ansible role. It centralizes all configurable values related to MariaDB deployment and can be adjusted without modifying task logic.
+
+---
+
+## files and their purpose
+
+### 1. `configuration.yml`
+
+Contains configuration values that determine which Docker image version to use and what hostname the container will be registered under.
+
+* **`version`** (string):
+
+  * Default: `"latest"`
+  * The MariaDB image tag to pull (e.g. `10.6`, `10.11`, or `latest`).
+
+* **`hostname`** (string):
+
+  * Default: `"central-mariadb"`
+  * The container name and DNS alias within the `central_mariadb` network. Used by other services (like Moodle) to connect.
+
+> **Tip:** Pin to a specific minor version (e.g., `10.6.12`) in production to avoid breaking changes on rebuilds.
+
+---
+
+### 2. `main.yml`
+
+Minimal file defining the application identifier for the role.
+
+* **`application_id`** (string):
+
+  * Default: `"mariadb"`
+  * Logical name used in templates, notifications, or paths when multiple roles/services may coexist.
\ No newline at end of file
diff --git a/roles/docker-moodle/Administration.md b/roles/docker-moodle/Administration.md
new file mode 100644
index 00000000..9f7748c9
--- /dev/null
+++ b/roles/docker-moodle/Administration.md
@@ -0,0 +1,28 @@
+# Administration
+
+# Radical Erase of Setup
+To manually erase the full moodle setup inkluding all data execute:
+
+**CLI:**
+
+```bash 
+cd /opt/docker/moodle && \
+docker compose down -v || {
+  echo "docker compose down failed, cleaning up manually"
+  rm -rv /mnt/hdd/data/docker/volumes/moodle_*
+  docker compose down -v
+} && \
+rm -rv /opt/docker/moodle
+``` 
+
+Afterwards login to the database and execute
+
+**MariaDB:**
+```sql
+DROP DATABASE IF EXISTS moodle;
+```
+
+to delete all data in the database related to this role. 
+
+# Virgin Setup
+After the installation you can rerun this role to create a fresh setup of Moodle. 
\ No newline at end of file
diff --git a/roles/docker-moodle/TODO.md b/roles/docker-moodle/TODO.md
index 1b84eb53..e93aa003 100644
--- a/roles/docker-moodle/TODO.md
+++ b/roles/docker-moodle/TODO.md
@@ -1,3 +1,2 @@
 # Todo
-- Check if sendmail needs to be installed. See [Issue](https://github.com/bitnami/containers/issues/63311).
-- Solve [issue](https://github.com/bitnami/containers/issues/72747)
\ No newline at end of file
+- Check if sendmail needs to be installed. See [Issue](https://github.com/bitnami/containers/issues/63311).
\ No newline at end of file