@ai-support-agent/cli 0.3.0-beta.1 → 0.3.1-beta.0

package/ansible/callback_plugins/json.py

@@ -0,0 +1,146 @@
+"""Bundled `ANSIBLE_STDOUT_CALLBACK=json` stdout callback.
+
+WHY THIS FILE EXISTS: ansible-core does not ship a `json` stdout callback
+plugin (confirmed absent from `ansible-core`'s bundled `callback_plugins/`
+directory across the 2.x line at the time this file was written — see
+`ansible-doc -t callback -l`, which does not list one). Before this file was
+added, `src/server-setup/server-setup-runner.ts` set
+`ANSIBLE_STDOUT_CALLBACK=json` and got no matching plugin, silently falling
+back to the human-readable `default` callback; `parseStepResults()` would
+then fail to `JSON.parse` that output and report *every* requested step as
+"skipped" regardless of what actually happened on the target host.
+
+Ansible auto-discovers callback plugins from a `callback_plugins/`
+directory next to the running playbook (this file lives at
+`ansible/callback_plugins/json.py`, next to `ansible/playbook.yml`), so no
+collection install or extra configuration is required to pick this up.
+
+OUTPUT CONTRACT: emits exactly one line of JSON at the end of the run,
+shaped as
+    {"plays": [{"task": {"name": <task name>},
+                 "hosts": {<hostname>: {"changed":, "failed":, "skipped":,
+                                          "msg":, ...other module fields}}}]}
+matching the `AnsibleJsonOutput` shape parsed by
+`parseStepResults()` in `src/server-setup/server-setup-runner.ts`. Task
+names in the bundled roles are prefixed `"<stepType> : <description>"`, and
+`parseStepResults()` groups task outcomes back to a step by taking the text
+before the first `:` in the task name.
+"""
+from __future__ import annotations
+
+import json
+
+from ansible.plugins.callback import CallbackBase
+
+DOCUMENTATION = r"""
+    callback: json
+    type: stdout
+    short_description: Bundled JSON stdout callback for server-setup-exec
+    description:
+      - Emits a single JSON document at the end of the run grouping
+        per-task, per-host results, consumed by the agent CLI's
+        server_setup_exec command (src/server-setup/server-setup-runner.ts).
+      - Bundled here because ansible-core does not ship a `json` stdout
+        callback plugin out of the box.
+"""
+
+
+class CallbackModule(CallbackBase):
+    """Accumulate per-task/per-host results and dump them as one JSON blob."""
+
+    CALLBACK_VERSION = 2.0
+    CALLBACK_TYPE = 'stdout'
+    CALLBACK_NAME = 'json'
+
+    def __init__(self):
+        super().__init__()
+        self.results = {"plays": []}
+        self._current_play = None
+        self._current_task = None
+
+    def _new_task_entry(self, task_name):
+        entry = {"task": {"name": task_name}, "hosts": {}}
+        if self._current_play is not None:
+            self._current_play["tasks"].append(entry)
+        return entry
+
+    def v2_playbook_on_play_start(self, play):
+        self._current_play = {"play": {"name": play.get_name()}, "tasks": []}
+        self.results["plays"].append(self._current_play)
+
+    def v2_playbook_on_task_start(self, task, is_conditional):
+        self._current_task = self._new_task_entry(task.get_name())
+
+    def v2_playbook_on_handler_task_start(self, task):
+        self._current_task = self._new_task_entry(task.get_name())
+
+    @staticmethod
+    def _is_no_log(result, raw_result):
+        """True if this result must be censored because of `no_log: true`.
+
+        IMPORTANT: `result._result` (the raw dict callbacks receive via
+        `v2_runner_on_*`) is NOT pre-censored by Ansible core. Core's
+        censorship logic lives in `TaskResult.clean_copy()`
+        (ansible/executor/task_result.py), but the strategy plugin
+        (ansible/plugins/strategy/__init__.py) passes the *original*,
+        uncensored `TaskResult` to `send_callback()` — `clean_copy()` is used
+        for other internal purposes (e.g. the `ansible_failed_result`
+        rescue/always fact), not for what reaches stdout callback plugins.
+        A callback plugin that assumes core already censored `_result` (as
+        this one previously did) will leak whatever `no_log: true` was
+        meant to hide — e.g. `db_root_password` from
+        ansible/roles/database/tasks/main.yml's `mysql_user`/
+        `postgresql_user` tasks — straight into this plugin's JSON output.
+        So this plugin must replicate (a minimal version of) that censorship
+        itself, checking both the task's own `no_log` flag and the
+        `_ansible_no_log` flag a module can set on its own result.
+        """
+        task = getattr(result, "_task", None)
+        task_no_log = bool(getattr(task, "no_log", False)) if task is not None else False
+        result_no_log = bool(raw_result.get("_ansible_no_log", False)) if isinstance(raw_result, dict) else False
+        return task_no_log or result_no_log
+
+    def _record(self, result, *, failed, skipped):
+        host = result._host.get_name()
+        raw_result = dict(result._result)
+        if self._is_no_log(result, raw_result):
+            # Minimal, non-secret summary only — no module fields (which may
+            # include the no_log'd value or closely related data) are
+            # forwarded.
+            payload = {"censored": True, "changed": raw_result.get("changed", False)}
+        else:
+            payload = raw_result
+        payload["failed"] = failed
+        payload["skipped"] = skipped
+        payload.setdefault("changed", False)
+        if self._current_task is None:
+            # Defensive: a result arrived with no preceding task-start event.
+            self._current_task = self._new_task_entry(getattr(result, "task_name", "") or "")
+        self._current_task["hosts"][host] = payload
+
+    def v2_runner_on_ok(self, result):
+        self._record(result, failed=False, skipped=False)
+
+    def v2_runner_on_failed(self, result, ignore_errors=False):
+        self._record(result, failed=True, skipped=False)
+
+    def v2_runner_on_skipped(self, result):
+        self._record(result, failed=False, skipped=True)
+
+    def v2_runner_on_unreachable(self, result):
+        host = result._host.get_name()
+        raw_result = dict(result._result)
+        if self._is_no_log(result, raw_result):
+            payload = {"censored": True, "changed": raw_result.get("changed", False)}
+        else:
+            payload = raw_result
+        payload["unreachable"] = True
+        payload["failed"] = True
+        payload["skipped"] = False
+        payload.setdefault("changed", False)
+        if self._current_task is None:
+            self._current_task = self._new_task_entry(getattr(result, "task_name", "") or "")
+        self._current_task["hosts"][host] = payload
+
+    def v2_playbook_on_stats(self, stats):
+        self._display.display(json.dumps(self.results))

package/ansible/callback_plugins/tests/test_json_callback.py

@@ -0,0 +1,171 @@
+"""Unit tests for the bundled `json` stdout callback plugin (json.py).
+
+Focus: `no_log: true` must actually be respected by this plugin's own JSON
+output. `result._result` (what `v2_runner_on_*` receives from Ansible's
+strategy plugin) is NOT pre-censored by Ansible core — core's censorship
+(`TaskResult.clean_copy()`) is used for other internal purposes, not for
+what reaches callback plugins — so this plugin must apply its own
+censorship, and these tests exist to prove it actually does.
+
+Run with (requires ansible-core installed — see docker/Dockerfile's pinned
+`ansible-core>=2.16,<2.18`, or `pip install 'ansible-core>=2.16,<2.18'` into
+a local virtualenv):
+
+    python3 ansible/callback_plugins/tests/test_json_callback.py -v
+
+Run as a plain script (NOT via `python3 -m unittest <dotted.path>` from the
+repo root, and NOT from inside `ansible/callback_plugins/` itself): this
+repo's top-level `ansible/` directory would shadow the real `ansible`
+package on `sys.path`, and the plugin under test is itself named `json.py`,
+which would shadow the stdlib `json` module if its own directory ended up
+on `sys.path`. Running this file directly puts only *this* `tests/`
+directory on `sys.path[0]`, avoiding both collisions; `json.py` itself is
+loaded by absolute file path via `importlib`, independent of `sys.path`.
+
+Loads json.py directly by file path (rather than relying on package/
+collection discovery) since this plugin is only ever auto-discovered by
+ansible-core at `ansible-playbook` runtime via the `callback_plugins/`
+directory convention, not importable as a regular Python package.
+"""
+from __future__ import annotations
+
+import importlib.util
+import json
+import os
+import unittest
+
+
+def _load_callback_module_class():
+    plugin_path = os.path.join(os.path.dirname(__file__), "..", "json.py")
+    spec = importlib.util.spec_from_file_location("server_setup_json_stdout_callback", plugin_path)
+    assert spec is not None and spec.loader is not None
+    module = importlib.util.module_from_spec(spec)
+    spec.loader.exec_module(module)
+    return module.CallbackModule
+
+
+class _FakeNamed:
+    """Minimal stand-in for anything exposing ansible-core's `get_name()`."""
+
+    def __init__(self, name):
+        self._name = name
+
+    def get_name(self):
+        return self._name
+
+
+class _FakeTask:
+    def __init__(self, name, no_log=False):
+        self._name = name
+        self.no_log = no_log
+
+    def get_name(self):
+        return self._name
+
+
+class _FakeResult:
+    """Minimal stand-in for the `TaskResult` ansible-core hands to `v2_runner_on_*`."""
+
+    def __init__(self, host_name, result_dict, task=None, task_name=""):
+        self._host = _FakeNamed(host_name)
+        self._result = result_dict
+        self._task = task
+        self.task_name = task_name
+
+
+class JsonCallbackNoLogTest(unittest.TestCase):
+    def setUp(self):
+        callback_cls = _load_callback_module_class()
+        self.cb = callback_cls()
+        self.cb.v2_playbook_on_play_start(_FakeNamed("AI Support Agent server setup"))
+
+    def _host_payload(self, task_index=0, host="203.0.113.10"):
+        return self.cb.results["plays"][0]["tasks"][task_index]["hosts"][host]
+
+    def test_task_marked_no_log_is_censored_in_ok_result(self):
+        task = _FakeTask("database : Set MySQL root password", no_log=True)
+        self.cb.v2_playbook_on_task_start(task, is_conditional=False)
+
+        result = _FakeResult(
+            "203.0.113.10",
+            {"changed": True, "password": "hunter2", "msg": "ALTER USER root ... IDENTIFIED BY 'hunter2'"},
+            task=task,
+        )
+        self.cb.v2_runner_on_ok(result)
+
+        payload = self._host_payload()
+        self.assertEqual(payload, {"censored": True, "changed": True, "failed": False, "skipped": False})
+
+        # (The task *name* legitimately contains the word "password" — that's
+        # just a human-readable description, not the secret value itself.)
+        dumped = json.dumps(self.cb.results)
+        self.assertNotIn("hunter2", dumped)
+        self.assertNotIn("IDENTIFIED BY", dumped)
+
+    def test_module_set_ansible_no_log_flag_is_censored_even_if_task_no_log_is_false(self):
+        # A module can mark its own result no_log (`_ansible_no_log`) even
+        # when the *task* itself wasn't declared `no_log: true` — this must
+        # be censored too.
+        task = _FakeTask("database : Set MySQL root password", no_log=False)
+        self.cb.v2_playbook_on_task_start(task, is_conditional=False)
+
+        result = _FakeResult(
+            "203.0.113.10",
+            {"changed": True, "_ansible_no_log": True, "password": "hunter2"},
+            task=task,
+        )
+        self.cb.v2_runner_on_ok(result)
+
+        payload = self._host_payload()
+        self.assertEqual(payload, {"censored": True, "changed": True, "failed": False, "skipped": False})
+        self.assertNotIn("hunter2", json.dumps(self.cb.results))
+
+    def test_no_log_result_is_censored_on_failure_too(self):
+        task = _FakeTask("database : Set MySQL root password", no_log=True)
+        self.cb.v2_playbook_on_task_start(task, is_conditional=False)
+
+        result = _FakeResult(
+            "203.0.113.10",
+            {"changed": False, "password": "hunter2", "msg": "Access denied for user 'root'@'localhost' (using password: YES)"},
+            task=task,
+        )
+        self.cb.v2_runner_on_failed(result, ignore_errors=False)
+
+        payload = self._host_payload()
+        self.assertEqual(payload, {"censored": True, "changed": False, "failed": True, "skipped": False})
+        self.assertNotIn("hunter2", json.dumps(self.cb.results))
+
+    def test_no_log_result_is_censored_on_unreachable_too(self):
+        task = _FakeTask("database : Set MySQL root password", no_log=True)
+        self.cb.v2_playbook_on_task_start(task, is_conditional=False)
+
+        result = _FakeResult(
+            "203.0.113.10",
+            {"changed": False, "password": "hunter2"},
+            task=task,
+        )
+        self.cb.v2_runner_on_unreachable(result)
+
+        payload = self._host_payload()
+        self.assertEqual(
+            payload,
+            {"censored": True, "changed": False, "failed": True, "skipped": False, "unreachable": True},
+        )
+        self.assertNotIn("hunter2", json.dumps(self.cb.results))
+
+    def test_task_without_no_log_is_not_censored(self):
+        # Control case: a normal (non-secret) task's result must pass through
+        # unmodified, proving the censorship above is targeted rather than
+        # blanket-applied.
+        task = _FakeTask("os_init : Update apt cache", no_log=False)
+        self.cb.v2_playbook_on_task_start(task, is_conditional=False)
+
+        result = _FakeResult("203.0.113.10", {"changed": True, "msg": "cache updated"}, task=task)
+        self.cb.v2_runner_on_ok(result)
+
+        payload = self._host_payload()
+        self.assertEqual(payload, {"changed": True, "msg": "cache updated", "failed": False, "skipped": False})
+
+
+if __name__ == "__main__":
+    unittest.main()

package/ansible/playbook.yml

@@ -0,0 +1,52 @@
+---
+# Server setup playbook bundled with the agent CLI (agent/ansible/playbook.yml).
+#
+# Invoked by src/server-setup/server-setup-runner.ts as:
+#   ansible-playbook -i <inventory.yml> playbook.yml --tags <stepType,...> -e @<extra-vars.json>
+#
+# The inventory is JSON content written with a .yml extension (JSON is valid
+# YAML, so ansible-core's bundled `yaml` inventory plugin — matched by file
+# extension — parses it unambiguously); see server-setup-runner.ts's
+# buildInventory() for why.
+#
+# Each role below corresponds 1:1 to a ServerSetupStepType (os_init / docker /
+# web_server / database / dns_tls). `--tags` selects which roles run; task
+# names inside each role are prefixed "<stepType> : ..." so the runner can
+# group the `ansible-playbook --stdout-callback=json` output (produced by
+# the bundled `callback_plugins/json.py` — ansible-core does not ship a
+# `json` stdout callback of its own) back into one result per requested step.
+#
+# See admin-docs docs/features/server-setup.md for the full design,
+# especially "秘密鍵の受け渡し設計" (this playbook never touches the SSH key
+# file directly — it is only referenced via the inventory's
+# ansible_ssh_private_key_file).
+#
+# Supported OS: MVP scope is Ubuntu 22.04/24.04 LTS only (see precheck task
+# below, tagged `always` so it runs regardless of which --tags are passed).
+- name: AI Support Agent server setup
+  hosts: all
+  become: true
+  gather_facts: true
+
+  tasks:
+    - name: "precheck : Verify supported OS"
+      ansible.builtin.fail:
+        msg: >-
+          Unsupported OS: {{ ansible_distribution }} {{ ansible_distribution_version }}.
+          Only Ubuntu 22.04/24.04 LTS are supported by server setup execution.
+      when: >-
+        ansible_distribution != 'Ubuntu' or
+        ansible_distribution_version not in ['22.04', '24.04']
+      tags: always
+
+  roles:
+    - role: os_init
+      tags: os_init
+    - role: docker
+      tags: docker
+    - role: web_server
+      tags: web_server
+    - role: database
+      tags: database
+    - role: dns_tls
+      tags: dns_tls

package/ansible/roles/database/tasks/main.yml

@@ -0,0 +1,121 @@
+---
+# database role: installs and starts MySQL or PostgreSQL, selected by the
+# `db_type` variable ('mysql' | 'postgresql'), and sets the root/postgres
+# admin password using the ansible.mysql / community.postgresql collections
+# (bundled into the agent CLI's Docker image via `ansible-galaxy collection
+# install`, see docker/Dockerfile).
+#
+# `ansible.mysql.mysql_user` (not `community.mysql.mysql_user`, which as of
+# community.mysql 5.x is deprecated in favor of this collection and slated
+# for removal in community.mysql 6.0.0) is used for MySQL.
+#
+# IMPORTANT: do not build the password-setting SQL as a raw string with the
+# password Jinja-interpolated directly into it (e.g.
+# `mysql -u root -e "ALTER USER 'root'@'localhost' IDENTIFIED BY '{{ db_root_password }}'"`
+# via `ansible.builtin.command`). A password containing a single quote would
+# break out of the SQL string literal there, letting arbitrary SQL run as
+# root/postgres. The mysql_user / postgresql_user modules below instead pass
+# the password as a bound module parameter, never as literal SQL text, so no
+# password value can escape its parameter position regardless of its
+# content.
+#
+# Any task that touches a password value MUST be marked `no_log: true` so
+# the value never reaches Ansible's own stdout/stderr or the JSON callback
+# output consumed by src/server-setup/server-setup-runner.ts.
+#
+# `db_type` is validated as an enum ('mysql' | 'postgresql') by
+# `ALLOWED_STEP_PARAMS`/`STEP_PARAM_ENUM_VALUES` in
+# src/server-setup/server-setup-runner.ts before this playbook ever runs, so
+# the `assert` below should never fire in practice. It exists as a second,
+# independent safety net: every task in this file is gated by a plain
+# `when: db_type == '...'` string comparison, so a value that doesn't match
+# ANY known engine (a typo, wrong case, ...) would otherwise match none of
+# them, causing every task to silently skip while `ansible-playbook` still
+# exits 0 — i.e. `runServerSetup` would report success despite installing
+# nothing.
+
+- name: "database : Validate db_type is supported"
+  ansible.builtin.assert:
+    that:
+      - db_type in ['mysql', 'postgresql']
+    fail_msg: >-
+      db_type must be one of 'mysql' or 'postgresql': got {{ db_type | to_json }}
+  when: db_type is defined
+
+- name: "database : Install MySQL server"
+  ansible.builtin.apt:
+    name:
+      - mysql-server
+    state: present
+    update_cache: true
+  when: (db_type | default('')) == 'mysql'
+
+- name: "database : Enable and start MySQL"
+  ansible.builtin.service:
+    name: mysql
+    state: started
+    enabled: true
+  when: (db_type | default('')) == 'mysql'
+
+- name: "database : Install PyMySQL (required by ansible.mysql.mysql_user)"
+  ansible.builtin.apt:
+    name: python3-pymysql
+    state: present
+    update_cache: true
+  when: (db_type | default('')) == 'mysql' and db_root_password is defined
+
+# `check_implicit_admin: true` + the explicit `login_user`/`login_password`
+# fallback make this task idempotent across re-runs. On a fresh MySQL
+# install, root@localhost authenticates via the `auth_socket` plugin (no
+# password) over the unix socket — the "implicit admin" connection
+# `check_implicit_admin` tries first. Setting `password` here switches
+# root@localhost to password auth, so a *second* run can no longer connect
+# as the implicit admin; `check_implicit_admin` then falls back to
+# connecting as `login_user`/`login_password` (the same, now-current,
+# `db_root_password`), which succeeds and is a no-op since the password
+# already matches. Without this, a second run would fail outright once the
+# implicit-admin connection stops working. This mirrors the "Handle multiple
+# non-idempotent password changed states" example in the upstream
+# community.mysql.mysql_user documentation (ansible.mysql.mysql_user shares
+# the same module interface).
+- name: "database : Set MySQL root password"
+  ansible.mysql.mysql_user:
+    name: root
+    host: localhost
+    password: "{{ db_root_password }}"
+    login_unix_socket: /var/run/mysqld/mysqld.sock
+    check_implicit_admin: true
+    login_user: root
+    login_password: "{{ db_root_password }}"
+  when: (db_type | default('')) == 'mysql' and db_root_password is defined
+  no_log: true
+
+- name: "database : Install PostgreSQL server"
+  ansible.builtin.apt:
+    name:
+      - postgresql
+    state: present
+    update_cache: true
+  when: (db_type | default('')) == 'postgresql'
+
+- name: "database : Enable and start PostgreSQL"
+  ansible.builtin.service:
+    name: postgresql
+    state: started
+    enabled: true
+  when: (db_type | default('')) == 'postgresql'
+
+- name: "database : Install psycopg2 (required by community.postgresql.postgresql_user)"
+  ansible.builtin.apt:
+    name: python3-psycopg2
+    state: present
+    update_cache: true
+  when: (db_type | default('')) == 'postgresql' and db_root_password is defined
+
+- name: "database : Set PostgreSQL postgres user password"
+  become_user: postgres
+  community.postgresql.postgresql_user:
+    name: postgres
+    password: "{{ db_root_password }}"
+  when: (db_type | default('')) == 'postgresql' and db_root_password is defined
+  no_log: true

package/ansible/roles/dns_tls/tasks/main.yml

@@ -0,0 +1,75 @@
+---
+# dns_tls role: Caddy (reverse proxy with automatic Let's Encrypt TLS),
+# configured from the `domain` variable.
+
+- name: "dns_tls : Install prerequisite packages"
+  ansible.builtin.apt:
+    name:
+      - debian-keyring
+      - debian-archive-keyring
+      - apt-transport-https
+      - curl
+      - gnupg
+    state: present
+    update_cache: true
+
+- name: "dns_tls : Create apt keyrings directory"
+  ansible.builtin.file:
+    path: /etc/apt/keyrings
+    state: directory
+    mode: '0755'
+
+- name: "dns_tls : Add Caddy GPG key"
+  ansible.builtin.get_url:
+    url: https://dl.cloudsmith.io/public/caddy/stable/gpg.key
+    dest: /etc/apt/keyrings/caddy-stable.asc
+    mode: '0644'
+
+- name: "dns_tls : Add Caddy apt repository"
+  ansible.builtin.apt_repository:
+    repo: >-
+      deb [signed-by=/etc/apt/keyrings/caddy-stable.asc]
+      https://dl.cloudsmith.io/public/caddy/stable/deb/debian any-version main
+    state: present
+    filename: caddy-stable
+
+- name: "dns_tls : Install Caddy"
+  ansible.builtin.apt:
+    name: caddy
+    state: present
+    update_cache: true
+
+- name: "dns_tls : Validate domain is a well-formed FQDN"
+  ansible.builtin.assert:
+    that:
+      # Anchored (`match` = re.match, and the pattern ends in `$`) so a value
+      # with an embedded newline, space, or Caddyfile-syntax character
+      # (`{`, `}`, `#`, etc.) cannot slip through and be injected into
+      # Caddyfile.j2's generated reverse_proxy block.
+      - domain is match('^([A-Za-z0-9]([A-Za-z0-9-]{0,61}[A-Za-z0-9])?\.)+[A-Za-z]{2,63}$')
+    fail_msg: >-
+      domain must be a well-formed FQDN (letters/digits/hyphens and dots
+      only): got {{ domain | to_json }}
+  when: domain is defined
+
+- name: "dns_tls : Generate Caddyfile"
+  ansible.builtin.template:
+    src: Caddyfile.j2
+    dest: /etc/caddy/Caddyfile
+    owner: root
+    group: root
+    mode: '0644'
+  when: domain is defined
+  register: dns_tls_caddyfile
+
+- name: "dns_tls : Enable and start Caddy"
+  ansible.builtin.service:
+    name: caddy
+    state: started
+    enabled: true
+
+- name: "dns_tls : Restart Caddy to apply Caddyfile changes"
+  ansible.builtin.service:
+    name: caddy
+    state: restarted
+  when: dns_tls_caddyfile is changed

package/ansible/roles/dns_tls/templates/Caddyfile.j2

@@ -0,0 +1,4 @@
+{# Generated by ai-support-agent server setup (dns_tls role). Do not edit by hand. #}
+{{ domain }} {
+    reverse_proxy localhost:8080
+}

package/ansible/roles/docker/tasks/main.yml

@@ -0,0 +1,51 @@
+---
+# docker role: Docker Engine + docker compose plugin, installed from Docker's
+# official apt repository. `ansible.builtin.apt` is naturally idempotent, so
+# re-running this role when Docker is already installed is a no-op.
+
+- name: "docker : Install prerequisite packages"
+  ansible.builtin.apt:
+    name:
+      - ca-certificates
+      - curl
+      - gnupg
+    state: present
+    update_cache: true
+
+- name: "docker : Create apt keyrings directory"
+  ansible.builtin.file:
+    path: /etc/apt/keyrings
+    state: directory
+    mode: '0755'
+
+- name: "docker : Add Docker GPG key"
+  ansible.builtin.get_url:
+    url: https://download.docker.com/linux/ubuntu/gpg
+    dest: /etc/apt/keyrings/docker.asc
+    mode: '0644'
+
+- name: "docker : Add Docker apt repository"
+  ansible.builtin.apt_repository:
+    repo: >-
+      deb [arch={{ 'amd64' if ansible_architecture == 'x86_64' else 'arm64' }}
+      signed-by=/etc/apt/keyrings/docker.asc] https://download.docker.com/linux/ubuntu
+      {{ ansible_distribution_release }} stable
+    state: present
+    filename: docker
+
+- name: "docker : Install Docker Engine and compose plugin"
+  ansible.builtin.apt:
+    name:
+      - docker-ce
+      - docker-ce-cli
+      - containerd.io
+      - docker-buildx-plugin
+      - docker-compose-plugin
+    state: present
+    update_cache: true
+
+- name: "docker : Enable and start the docker service"
+  ansible.builtin.service:
+    name: docker
+    state: started
+    enabled: true

package/ansible/roles/os_init/tasks/main.yml

@@ -0,0 +1,61 @@
+---
+# os_init role: user creation, OS package upgrade, and ufw firewall.
+#
+# IMPORTANT: the "allow OpenSSH" rule is applied BEFORE the default-deny
+# incoming policy and BEFORE `ufw --force enable`. Reversing this order can
+# drop the very SSH session used to run this playbook.
+
+- name: "os_init : Update apt cache"
+  ansible.builtin.apt:
+    update_cache: true
+    cache_valid_time: 3600
+
+- name: "os_init : Upgrade all packages"
+  ansible.builtin.apt:
+    upgrade: dist
+
+- name: "os_init : Create setup user"
+  ansible.builtin.user:
+    name: "{{ os_init_user | default('appuser') }}"
+    shell: /bin/bash
+    create_home: true
+    groups: sudo
+    append: true
+
+- name: "os_init : Install ufw"
+  ansible.builtin.apt:
+    name: ufw
+    state: present
+
+- name: "os_init : Check ufw status"
+  ansible.builtin.command:
+    cmd: ufw status
+  register: os_init_ufw_status
+  changed_when: false
+
+# --- Ordering guard: OpenSSH must be allowed before anything below enables
+# --- the firewall or sets a default-deny incoming policy.
+- name: "os_init : Allow OpenSSH through ufw"
+  ansible.builtin.command:
+    cmd: ufw allow OpenSSH
+  register: os_init_ufw_allow_ssh
+  changed_when: "'Skipping' not in os_init_ufw_allow_ssh.stdout"
+
+- name: "os_init : Set ufw default incoming policy to deny"
+  ansible.builtin.command:
+    cmd: ufw default deny incoming
+  register: os_init_ufw_default_incoming
+  changed_when: "'Default incoming policy changed' in os_init_ufw_default_incoming.stdout"
+
+- name: "os_init : Set ufw default outgoing policy to allow"
+  ansible.builtin.command:
+    cmd: ufw default allow outgoing
+  register: os_init_ufw_default_outgoing
+  changed_when: "'Default outgoing policy changed' in os_init_ufw_default_outgoing.stdout"
+
+- name: "os_init : Enable ufw"
+  ansible.builtin.command:
+    cmd: ufw --force enable
+  when: "'inactive' in os_init_ufw_status.stdout"
+  register: os_init_ufw_enable
+  changed_when: "'Firewall is active' in os_init_ufw_enable.stdout"