refactor(web-app-espocrm): improve config patching and container vars

- Replace `ESPOCRM_NAME` with `ESPOCRM_CONTAINER` for clarity and consistency.
- Drop unused `ESPOCRM_CONFIG_FILE_PUBLIC`, rely only on `config-internal.php`.
- Make DB credential patching idempotent using `grep` + `sed` checks.
- Replace direct sed edits for maintenance/cron/cache with EspoCRM ConfigWriter.
- Add fallback execution as root if www-data user cannot write config.
- Clear EspoCRM cache only when config changes and in update mode.
- Remove obsolete OIDC scopes inline task (now handled via env/vars).
- Fix docker-compose template to use `ESPOCRM_CONTAINER`.

This refactor makes the EspoCRM role more robust, idempotent, and aligned
with EspoCRM’s official ConfigWriter mechanism.

See conversation: https://chatgpt.com/share/68a87820-12f8-800f-90d6-01ba97a1b279

group_vars/all/07_services.yml

@@ -2,19 +2,20 @@
 # Services
 
 ## Meta
-SYS_SERVICE_SUFFIX:                   ".{{ SOFTWARE_NAME | lower }}.service"
+SYS_SERVICE_SUFFIX:                     ".{{ SOFTWARE_NAME | lower }}.service"
 
 ## Names
-SYS_SERVICE_CLEANUP_BACKUPS_FAILED:   "{{ 'sys-ctl-cln-faild-bkps'    | get_service_name(SOFTWARE_NAME) }}"
-SYS_SERVICE_OPTIMIZE_DRIVE:           "{{ 'svc-opt-ssd-hdd'           | get_service_name(SOFTWARE_NAME) }}"
-SYS_SERVICE_BACKUP_RMT_2_LOC:         "{{ 'svc-bkp-rmt-2-loc'         | get_service_name(SOFTWARE_NAME) }}"
-SYS_SERVICE_BACKUP_DOCKER_2_LOC:      "{{ 'sys-ctl-bkp-docker-2-loc'  | get_service_name(SOFTWARE_NAME) }}"
-SYS_SERVICE_REPAIR_DOCKER_SOFT:       "{{ 'sys-ctl-rpr-docker-soft'   | get_service_name(SOFTWARE_NAME) }}"
-SYS_SERVICE_REPAIR_DOCKER_HARD:       "{{ 'sys-ctl-rpr-docker-hard'   | get_service_name(SOFTWARE_NAME) }}"
-SYS_SERVICE_UPDATE_DOCKER:            "{{ 'update-docker'             | get_service_name(SOFTWARE_NAME) }}"
+SYS_SERVICE_CLEANUP_BACKUPS_FAILED:     "{{ 'sys-ctl-cln-faild-bkps'    | get_service_name(SOFTWARE_NAME) }}"
+SYS_SERVICE_CLEANUP_ANONYMOUS_VOLUMES:  "{{ 'sys-ctl-cln-anon-volumes'  | get_service_name(SOFTWARE_NAME) }}"
+SYS_SERVICE_OPTIMIZE_DRIVE:             "{{ 'svc-opt-ssd-hdd'           | get_service_name(SOFTWARE_NAME) }}"
+SYS_SERVICE_BACKUP_RMT_2_LOC:           "{{ 'svc-bkp-rmt-2-loc'         | get_service_name(SOFTWARE_NAME) }}"
+SYS_SERVICE_BACKUP_DOCKER_2_LOC:        "{{ 'sys-ctl-bkp-docker-2-loc'  | get_service_name(SOFTWARE_NAME) }}"
+SYS_SERVICE_REPAIR_DOCKER_SOFT:         "{{ 'sys-ctl-rpr-docker-soft'   | get_service_name(SOFTWARE_NAME) }}"
+SYS_SERVICE_REPAIR_DOCKER_HARD:         "{{ 'sys-ctl-rpr-docker-hard'   | get_service_name(SOFTWARE_NAME) }}"
+SYS_SERVICE_UPDATE_DOCKER:              "{{ 'update-docker'             | get_service_name(SOFTWARE_NAME) }}"
 
 ## On Failure
-SYS_SERVICE_ON_FAILURE_COMPOSE:       "{{ ('sys-ctl-alm-compose@') | get_service_name(SOFTWARE_NAME, False) }}%n.service"
+SYS_SERVICE_ON_FAILURE_COMPOSE:         "{{ ('sys-ctl-alm-compose@') | get_service_name(SOFTWARE_NAME, False) }}%n.service"
 
 ## Groups
 SYS_SERVICE_GROUP_BACKUPS: >

roles/sys-ctl-cln-anon-volumes/tasks/main.yml

@@ -0,0 +1,18 @@
+- block:
+  - name: "pkgmgr install"
+    include_role:
+      name: pkgmgr-install
+    vars:
+      package_name: dockreap
+  
+  - include_role:
+      name: sys-service
+    vars:
+      system_service_tpl_on_failure:      "{{ SYS_SERVICE_ON_FAILURE_COMPOSE }}"
+      system_service_tpl_exec_start:      dockreap --no-confirmation
+      system_service_tpl_exec_start_pre:  /usr/bin/python {{ PATH_SYSTEM_LOCK_SCRIPT }} {{ SYS_SERVICE_GROUP_MANIPULATION | join(' ')  }} --ignore {{ SYS_SERVICE_CLEANUP_ANONYMOUS_VOLUMES }} --timeout "{{ SYS_TIMEOUT_CLEANUP_SERVICES }}"
+      system_service_copy_files:          false
+
+  - include_tasks: utils/run_once.yml
+  when:
+    - run_once_sys_ctl_cln_anon_volumes is not defined

roles/sys-ctl-cln-anon-volumes/vars/main.yml

@@ -0,0 +1 @@
+system_service_id: sys-ctl-cln-anon-volumes

roles/sys-ctl-rpr-docker-hard/tasks/01_core.yml

@@ -6,5 +6,6 @@
 - include_role:
     name: sys-service
   vars:
-    system_service_on_calendar: "{{SYS_SCHEDULE_REPAIR_DOCKER_HARD}}"
-    system_service_timer_enabled:  true
+    system_service_on_calendar:     "{{ SYS_SCHEDULE_REPAIR_DOCKER_HARD }}"
+    system_service_timer_enabled:   true
+    system_service_tpl_on_failure:  "{{ SYS_SERVICE_CLEANUP_ANONYMOUS_VOLUMES }}"

roles/sys-service/tasks/05_service.yml

@@ -39,10 +39,12 @@
 
 - name: refresh systemctl service when SYS_SERVICE_ALL_ENABLE
   block:
-  - command: /bin/true
+  - name: reload system daemon
+    command: /bin/true
     notify: reload system daemon
-  - command: /bin/true
+  - name: refresh systemctl service
+    command: /bin/true
     notify: refresh systemctl service
     when: not system_service_uses_at
-  when: SYS_SERVICE_ALL_ENABLED | bool
+  when: SYS_SERVICE_ALL_ENABLED | bool or system_force_flush | bool
 

roles/sys-service/vars/main.yml

@@ -6,15 +6,16 @@ system_service_role_dir:       "{{ [ playbook_dir, 'roles', system_service_role_
 system_service_script_dir:     "{{ [ PATH_SYSTEMCTL_SCRIPTS, system_service_id ] | path_join }}"
 
 ## Settings
+system_force_flush:            false # When set to true it activates the flushing of services :)
 system_service_copy_files:     true  # When set to false file copying will be skipped
 system_service_timer_enabled:  false # When set to true timer will be loaded
 system_service_state:          "{{ SYS_SERVICE_DEFAULT_STATE }}"
 
 # Dynamic Loaded ( Just available when dependencies are loaded )
-system_service_script_base:    "{{ system_service_script_src | basename | regex_replace('\\.j2$', '') }}"
-system_service_script_type:    "{{ system_service_script_base | filetype }}"
-system_service_script_inter:   "/bin/{{ 'bash' if system_service_script_type == 'sh' else 'python3'}}"
-system_service_script_exec:    "{{ system_service_script_inter }} {{ system_service_id | get_service_script_path( system_service_script_type ) }}"
+system_service_script_base:   "{{ system_service_script_src | basename | regex_replace('\\.j2$', '') }}"
+system_service_script_type:   "{{ system_service_script_base | filetype }}"
+system_service_script_inter:  "/bin/{{ 'bash' if system_service_script_type == 'sh' else 'python3'}}"
+system_service_script_exec:   "{{ system_service_script_inter }} {{ system_service_id | get_service_script_path( system_service_script_type ) }}"
 
 # Service template
 system_service_tpl_on_failure:        "{{ SYS_SERVICE_ON_FAILURE_COMPOSE }}"

roles/sys-svc-cln-anon-volumes/tasks/main.yml

@@ -1,24 +0,0 @@
-- name: Check if docker is installed
-  ansible.builtin.stat:
-    path: /usr/bin/docker
-  register: docker_bin
-
-- block:
-  - name: "pkgmgr install"
-    include_role:
-      name: pkgmgr-install
-    vars:
-      package_name: dockreap
-  
-  - name: run dockreap with --no-confirmation
-    command:
-      cmd: "dockreap --no-confirmation"
-    async: "{{ ASYNC_TIME if ASYNC_ENABLED | bool else omit }}"
-    poll:  "{{ ASYNC_POLL if ASYNC_ENABLED | bool else omit }}"
-
-  - name: mark dockreap as run
-    set_fact:
-      run_once_sys_svc_cln_anon_volumes: true
-  when:
-    - run_once_sys_svc_cln_anon_volumes is not defined
-    - docker_bin.stat.exists

roles/sys-svc-docker/tasks/03_cleanup.yml

@@ -1,6 +1,11 @@
-- name: Load role to delete anonymous volumes
-  include_role:
-    name: sys-svc-cln-anon-volumes
+- block:
+    - name: Load role to delete anonymous volumes
+      include_role:
+        name: sys-ctl-cln-anon-volumes
+      vars: 
+        system_force_flush: true
+    - include_tasks: utils/run_once.yml
+  when: run_once_sys_ctl_cln_anon_volumes is not defined
 
 - name: Prune Docker resources
   become: true

roles/web-app-espocrm/config/main.yml

@@ -38,4 +38,4 @@ docker:
       version:  "latest"
       name:     "espocrm"
   volumes:
-    data: ESPOCRM_data
+    data: espocrm_data

roles/web-app-espocrm/tasks/01_patch_config.yml

@@ -1,25 +1,37 @@
-- name: Update DB host
+- name: Update DB host (idempotent)
   command: >
-    docker exec --user root {{ ESPOCRM_NAME }}
-    sed -i "s/'host' => .*/'host' => '{{ database_host }}',/" {{ ESPOCRM_CONFIG_FILE_PRIVATE }}
+    docker exec --user root {{ ESPOCRM_CONTAINER }} sh -lc
+    "grep -q \"'host' *=> *'{{ database_host }}',\" {{ ESPOCRM_CONFIG_FILE_PRIVATE }} ||
+     { sed -i \"s/'host'\\s*=>\\s*[^,]*,/'host' => '{{ database_host }}',/\" {{ ESPOCRM_CONFIG_FILE_PRIVATE }} && echo CHANGED; }"
+  register: db_host_set
+  changed_when: "'CHANGED' in db_host_set.stdout"
   notify: docker compose restart
 
-- name: Update DB name
+- name: Update DB name (idempotent)
   command: >
-    docker exec --user root {{ ESPOCRM_NAME }}
-    sed -i "s/'dbname' => .*/'dbname' => '{{ database_name }}',/" {{ ESPOCRM_CONFIG_FILE_PRIVATE }}
+    docker exec --user root {{ ESPOCRM_CONTAINER }} sh -lc
+    "grep -q \"'dbname' *=> *'{{ database_name }}',\" {{ ESPOCRM_CONFIG_FILE_PRIVATE }} ||
+     { sed -i \"s/'dbname'\\s*=>\\s*[^,]*,/'dbname' => '{{ database_name }}',/\" {{ ESPOCRM_CONFIG_FILE_PRIVATE }} && echo CHANGED; }"
+  register: db_name_set
+  changed_when: "'CHANGED' in db_name_set.stdout"
   notify: docker compose restart
 
-- name: Update DB user
+- name: Update DB user (idempotent)
   command: >
-    docker exec --user root {{ ESPOCRM_NAME }}
-    sed -i "s/'user' => .*/'user' => '{{ database_username }}',/" {{ ESPOCRM_CONFIG_FILE_PRIVATE }}
+    docker exec --user root {{ ESPOCRM_CONTAINER }} sh -lc
+    "grep -q \"'user' *=> *'{{ database_username }}',\" {{ ESPOCRM_CONFIG_FILE_PRIVATE }} ||
+     { sed -i \"s/'user'\\s*=>\\s*[^,]*,/'user' => '{{ database_username }}',/\" {{ ESPOCRM_CONFIG_FILE_PRIVATE }} && echo CHANGED; }"
+  register: db_user_set
+  changed_when: "'CHANGED' in db_user_set.stdout"
   notify: docker compose restart
 
-- name: Update DB password
+- name: Update DB password (idempotent)
   command: >
-    docker exec --user root {{ ESPOCRM_NAME }}
-    sed -i "s/'password' => .*/'password' => '{{ database_password }}',/" {{ ESPOCRM_CONFIG_FILE_PRIVATE }}
+    docker exec --user root {{ ESPOCRM_CONTAINER }} sh -lc
+    "grep -q \"'password' *=> *'{{ database_password }}',\" {{ ESPOCRM_CONFIG_FILE_PRIVATE }} ||
+     { sed -i \"s/'password'\\s*=>\\s*[^,]*,/'password' => '{{ database_password }}',/\" {{ ESPOCRM_CONFIG_FILE_PRIVATE }} && echo CHANGED; }"
+  register: db_pass_set
+  changed_when: "'CHANGED' in db_pass_set.stdout"
   notify: docker compose restart
   no_log: "{{ MASK_CREDENTIALS_IN_LOGS | bool }}"
 
@@ -43,26 +55,56 @@
   register: siteurl_set
   changed_when: "'CHANGED' in siteurl_set.stdout"
 
-- name: Disable EspoCRM maintenance mode
-  ansible.builtin.shell: |
-    docker exec -u root {{ ESPOCRM_NAME }} \
-      sed -i "s/'maintenanceMode' => true/'maintenanceMode' => false/" {{ ESPOCRM_CONFIG_FILE_PUBLIC }}
-  register: disable_maintenance
-  changed_when: disable_maintenance.rc == 0
-  failed_when: disable_maintenance.rc != 0
+- name: Ensure maintenance off, cron on, cache on (idempotent via ConfigWriter)
+  block:
+    - name: Apply config via ConfigWriter as app user
+      command: >
+        docker exec --user {{ ESPOCRM_USER }} {{ ESPOCRM_CONTAINER }}
+        php -r '
+          require "/var/www/html/bootstrap.php";
+          $app = new \Espo\Core\Application();
+          $c = $app->getContainer();
+          $cfg = $c->get("config");
+          $w = $c->get("injectableFactory")->create("\Espo\Core\Utils\Config\ConfigWriter");
+          $pairs = [
+            "maintenanceMode" => false,
+            "cronDisabled"    => false,
+            "useCache"        => true
+          ];
+          $changed = false;
+          foreach ($pairs as $k => $v) {
+            if ($cfg->get($k) !== $v) { $w->set($k, $v); $changed = true; }
+          }
+          if ($changed) { $w->save(); echo "CHANGED"; }
+        '
+      register: cfg_set
+      changed_when: "'CHANGED' in cfg_set.stdout"
 
-- name: Enable EspoCRM cache
-  ansible.builtin.shell: |
-    docker exec -u root {{ ESPOCRM_NAME }} \
-      sed -i "s/'useCache' => false/'useCache' => true/" {{ ESPOCRM_CONFIG_FILE_PUBLIC }}
-  register: enable_cache
-  changed_when: enable_cache.rc == 0
-  failed_when: enable_cache.rc != 0
+  rescue:
+    - name: Apply config via ConfigWriter as root (fallback)
+      command: >
+        docker exec --user root {{ ESPOCRM_CONTAINER }}
+        php -r '
+          require "/var/www/html/bootstrap.php";
+          $app = new \Espo\Core\Application();
+          $c = $app->getContainer();
+          $cfg = $c->get("config");
+          $w = $c->get("injectableFactory")->create("\Espo\Core\Utils\Config\ConfigWriter");
+          $pairs = [
+            "maintenanceMode" => false,
+            "cronDisabled"    => false,
+            "useCache"        => true
+          ];
+          $changed = false;
+          foreach ($pairs as $k => $v) {
+            if ($cfg->get($k) !== $v) { $w->set($k, $v); $changed = true; }
+          }
+          if ($changed) { $w->save(); echo "CHANGED"; }
+        '
+      register: cfg_set
+      changed_when: "'CHANGED' in cfg_set.stdout"
 
-- name: Enable EspoCRM cron
-  ansible.builtin.shell: |
-    docker exec -u root {{ ESPOCRM_NAME }} \
-      sed -i "s/'cronDisabled' => true/'cronDisabled' => false/" {{ ESPOCRM_CONFIG_FILE_PUBLIC }}
-  register: enable_cron
-  changed_when: enable_cron.rc == 0
-  failed_when: enable_cron.rc != 0
+- name: Clear EspoCRM cache (only when config changed and we are updating)
+  command: >
+    docker exec --user {{ ESPOCRM_USER }} {{ ESPOCRM_CONTAINER }} php clear_cache.php
+  when: "'CHANGED' in cfg_set.stdout and MODE_UPDATE | bool"

roles/web-app-espocrm/tasks/main.yml

@@ -6,29 +6,14 @@
     docker_compose_flush_handlers:  true
 
 - name: Check if config.php exists in EspoCRM
-  command: docker exec --user root {{ ESPOCRM_NAME }} test -f {{ ESPOCRM_CONFIG_FILE_PRIVATE }}
+  command: docker exec --user root {{ ESPOCRM_CONTAINER }} test -f {{ ESPOCRM_CONFIG_FILE_PRIVATE }}
   register: config_file_exists
   changed_when: false
   failed_when: false
 
-- name: Patch EspoCRM config.php with updated DB credentials
+- name: Patch EspoCRM config.php
   include_tasks: 01_patch_config.yml
   when: config_file_exists.rc == 0
 
 - name: Flush handlers to make DB available before password reset
   meta: flush_handlers
-
-- name: Set OIDC scopes in EspoCRM config (inside web container)
-  ansible.builtin.shell: |
-    docker compose exec -T web php -r '
-      require "/var/www/html/bootstrap.php";
-      $writer = (new \Espo\Core\Application())
-        ->getContainer()
-        ->get("injectableFactory")
-        ->create("\Espo\Core\Utils\Config\ConfigWriter");
-      $writer->set("oidcScopes", ["openid", "profile", "email"]);
-      $writer->save();
-    '
-  args:
-    chdir: "{{ docker_compose.directories.instance }}"
-  when: ESPOCRM_OIDC_ENABLED | bool

roles/web-app-espocrm/templates/docker-compose.yml.j2

@@ -1,6 +1,6 @@
 {% include 'roles/docker-compose/templates/base.yml.j2' %}
   web:
-    container_name: {{ ESPOCRM_NAME }}
+    container_name: {{ ESPOCRM_CONTAINER }}
     image: "{{ ESPOCRM_IMAGE }}:{{ ESPOCRM_VERSION }}"
 {% include 'roles/docker-container/templates/base.yml.j2' %}
 {% include 'roles/docker-container/templates/healthcheck/curl.yml.j2' %}

roles/web-app-espocrm/vars/main.yml

@@ -13,9 +13,9 @@ vhost_flavour:                "ws_generic"
 # Espocrm
 ESPOCRM_VERSION:              "{{ applications | get_app_conf(application_id, 'docker.services.espocrm.version', True) }}"
 ESPOCRM_IMAGE:                "{{ applications | get_app_conf(application_id, 'docker.services.espocrm.image', True) }}"
-ESPOCRM_NAME:                 "{{ applications | get_app_conf(application_id, 'docker.services.espocrm.name', True) }}"
+ESPOCRM_CONTAINER:            "{{ applications | get_app_conf(application_id, 'docker.services.espocrm.name', True) }}"
 ESPOCRM_VOLUME:               "{{ applications | get_app_conf(application_id, 'docker.volumes.data', True) }}"
 ESPOCRM_CONFIG_FILE_PRIVATE:  "/var/www/html/data/config-internal.php"
-ESPOCRM_CONFIG_FILE_PUBLIC:   "/var/www/html/data/config.php"
 ESPOCRM_URL:                  "{{ domains | get_url(application_id, WEB_PROTOCOL) }}"
-ESPOCRM_OIDC_ENABLED:         "{{ applications | get_app_conf(application_id, 'features.central_database', False) }}"
+ESPOCRM_OIDC_ENABLED:         "{{ applications | get_app_conf(application_id, 'features.oidc', False) }}"
+ESPOCRM_USER:                 "www-data"