From 3f4018bcdff2dc0e4c66418e35488ef711fe8c04 Mon Sep 17 00:00:00 2001
From: FrankApiyo <franklineapiyo@gmail.com>
Date: Fri, 24 Jul 2026 17:00:04 +0300
Subject: [PATCH 1/4] test: enable molecule idempotence gate against
 version-aware django role

---
 molecule/default/converge.yml          | 2 +-
 molecule/default/molecule.yml          | 1 +
 molecule/default/requirements.yml      | 2 +-
 molecule/default/tests/test_default.py | 8 ++++++++
 4 files changed, 11 insertions(+), 2 deletions(-)

diff --git a/molecule/default/converge.yml b/molecule/default/converge.yml
index 033fc86..f46cfb4 100644
--- a/molecule/default/converge.yml
+++ b/molecule/default/converge.yml
@@ -19,7 +19,7 @@
       changed_when: false
       failed_when: systemctl_status.rc > 1
   roles:
-    - role: onaio.onadata
+    - role: ../../..
       onadata_python_source_version: "3.12"
       onadata_run_init_commands: false
       onadata_enable_celery: true
diff --git a/molecule/default/molecule.yml b/molecule/default/molecule.yml
index f6ad8f4..ec723b0 100644
--- a/molecule/default/molecule.yml
+++ b/molecule/default/molecule.yml
@@ -27,6 +27,7 @@ scenario:
     - create
     - prepare
     - converge
+    - idempotence
     - side_effect
     - verify
     - destroy
diff --git a/molecule/default/requirements.yml b/molecule/default/requirements.yml
index 8ced2c4..be5a175 100644
--- a/molecule/default/requirements.yml
+++ b/molecule/default/requirements.yml
@@ -2,7 +2,7 @@
 - src: https://github.com/onaio/ansible-django.git
   name: onaio.django
   scm: git
-  version: 6d5572fa1ee9e1cb6c0e425e181a618cf6ca095f
+  version: feat/version-aware-deploys
 
 - src: https://github.com/onaio/ansible-ssl-certificate.git
   name: onaio.ssl-certificate
diff --git a/molecule/default/tests/test_default.py b/molecule/default/tests/test_default.py
index 3a445d6..1a1b2d4 100644
--- a/molecule/default/tests/test_default.py
+++ b/molecule/default/tests/test_default.py
@@ -28,3 +28,11 @@ def test_django_service(host):
     assert celerybeat_onadata.is_running
     assert celerybeat_onadata.is_enabled
 
+
+def test_versioned_release_marker(host):
+    app = host.file("/home/onadata/app")
+    assert app.is_symlink
+
+    marker = host.file("/home/onadata/app/.deployed_version")
+    assert marker.exists
+    assert len(marker.content_string.strip()) == 40

From 717758d95db92773bd0604bb63e52951f0b5ff84 Mon Sep 17 00:00:00 2001
From: FrankApiyo <franklineapiyo@gmail.com>
Date: Fri, 24 Jul 2026 17:21:12 +0300
Subject: [PATCH 2/4] refactor: make custom template, docs and sasl2 tasks
 idempotent

---
 tasks/install.yml | 70 +++++++++++++++++++++++++++++++++++++++--------
 1 file changed, 58 insertions(+), 12 deletions(-)

diff --git a/tasks/install.yml b/tasks/install.yml
index 504ee49..d50ad23 100644
--- a/tasks/install.yml
+++ b/tasks/install.yml
@@ -1,11 +1,46 @@
 ---
+- name: Resolve the custom template version to a commit SHA
+  become: true
+  become_user: "{{ onadata_system_user }}"
+  command: "git ls-remote {{ onadata_custom_template_git_url }} {{ onadata_custom_template_version }}"
+  register: onadata_template_ls_remote
+  changed_when: false
+  check_mode: false
+  when: onadata_enable_custom_templates
+
+- name: Read the installed custom template marker
+  slurp:
+    src: "{{ onadata_codebase_path }}/.custom_template_version"
+  register: onadata_template_marker
+  failed_when: false
+  when: onadata_enable_custom_templates
+
+- name: Set custom template facts
+  set_fact:
+    onadata_template_desired_sha: "{{ (onadata_template_ls_remote.stdout_lines | last).split() | first }}"
+    onadata_template_installed_sha: >-
+      {{ (onadata_template_marker.content | b64decode | trim)
+         if onadata_template_marker.content is defined else '' }}
+  when: onadata_enable_custom_templates
+
 - name: Install the custom template # noqa 301
   become: true
   become_user: "{{ onadata_system_user }}"
   shell: "(git remote add template {{ onadata_custom_template_git_url }} || true) && git fetch template {{ onadata_custom_template_version }} && git reset HEAD onadata/libs/custom_template && rm -rf onadata/libs/custom_template && git read-tree --prefix=onadata/libs/custom_template -u template/{{ onadata_custom_template_version }}" # noqa 204
   args:
     executable: /bin/bash
-    chdir: "{{ onadata_checkout_path }}"
+    chdir: "{{ onadata_codebase_path }}"
+  when:
+    - onadata_enable_custom_templates
+    - onadata_template_desired_sha != onadata_template_installed_sha
+
+- name: Record the installed custom template version
+  become: true
+  copy:
+    content: "{{ onadata_template_desired_sha }}\n"
+    dest: "{{ onadata_codebase_path }}/.custom_template_version"
+    owner: "{{ onadata_system_user }}"
+    mode: "0644"
   when: onadata_enable_custom_templates
 
 - name: Install tableau library
@@ -25,27 +60,38 @@
   when:
     - not onadata_unmanaged_git_key
 
-- name: Install docs.pip
+- name: Install docs requirements
   become: true
   become_user: "{{ onadata_system_user }}"
-  shell: "source {{ onadata_venv_path }}/bin/activate && python -m pip install --no-cache-dir -r requirements/docs.pip"
-  args:
-    executable: /bin/bash
-    chdir: "{{ onadata_codebase_path }}"
+  pip:
+    requirements: "{{ onadata_codebase_path }}/requirements/docs.pip"
+    virtualenv: "{{ onadata_venv_path }}"
+    extra_args: "--no-cache-dir"
 
 - name: Generate Docs
   become: true
   become_user: "{{ onadata_system_user }}"
-  shell: "source {{ onadata_venv_path }}/bin/activate && make html"
+  command: make html
   args:
-    executable: /bin/bash
     chdir: "{{ onadata_codebase_path }}/docs"
+    creates: "{{ onadata_codebase_path }}/docs/_build/html/index.html"
+  environment:
+    PATH: "{{ onadata_venv_path }}/bin:{{ ansible_env.PATH }}"
 
-- name: Fix libsassl erorr
+- name: Ensure /usr/lib64 exists
   become: true
-  shell: "ln -sfn /usr/lib/x86_64-linux-gnu/sasl2/ /usr/lib64/sasl2"
-  args:
-    executable: /bin/bash
+  ansible.builtin.file:
+    path: /usr/lib64
+    state: directory
+    mode: "0755"
+
+- name: Link sasl2 modules into /usr/lib64
+  become: true
+  ansible.builtin.file:
+    src: /usr/lib/x86_64-linux-gnu/sasl2
+    dest: /usr/lib64/sasl2
+    state: link
+    force: true
 
 - name: Add /var/log/celery path
   become: true

From 3f1099dca3506a03406b8b3c516ee7abf2f69fb2 Mon Sep 17 00:00:00 2001
From: FrankApiyo <franklineapiyo@gmail.com>
Date: Mon, 27 Jul 2026 10:16:49 +0300
Subject: [PATCH 3/4] fix: match sasl2 link target written by previous shell
 task

---
 tasks/install.yml | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/tasks/install.yml b/tasks/install.yml
index d50ad23..424ba72 100644
--- a/tasks/install.yml
+++ b/tasks/install.yml
@@ -88,7 +88,9 @@
 - name: Link sasl2 modules into /usr/lib64
   become: true
   ansible.builtin.file:
-    src: /usr/lib/x86_64-linux-gnu/sasl2
+    # Trailing slash matches the target string the old `ln -sfn` shell task
+    # wrote on existing hosts, so the link is not rewritten on first run.
+    src: /usr/lib/x86_64-linux-gnu/sasl2/
     dest: /usr/lib64/sasl2
     state: link
     force: true

From d5cec467d28aeac8ac9baa9efedc96826b55561c Mon Sep 17 00:00:00 2001
From: FrankApiyo <franklineapiyo@gmail.com>
Date: Mon, 27 Jul 2026 10:20:49 +0300
Subject: [PATCH 4/4] fix: delete git key for real in check mode

---
 tasks/install.yml | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/tasks/install.yml b/tasks/install.yml
index 424ba72..4358bfb 100644
--- a/tasks/install.yml
+++ b/tasks/install.yml
@@ -57,6 +57,9 @@
     path: "{{ onadata_system_user_home }}/.ssh/{{ onadata_git_key_filename }}"
   become: true
   become_user: "{{ onadata_system_user }}"
+  # Real removal in --check too: the django role copies the key for real in
+  # check mode (its version check needs it), so cleanup must match.
+  check_mode: false
   when:
     - not onadata_unmanaged_git_key