readme: app_image в списке ролей + контракт для приложения

README.md

@@ -24,3 +24,37 @@ Git в этой директории — опциональный бэкап и
 ## Роли
 
 - `eget` — установка утилиты [eget](https://github.com/zyedidia/eget).
+- `app_image` — локальная сборка docker-образа приложения и доставка его
+  на сервер через `docker save`/`load` (без registry; тулчейн сборки на
+  сервере не нужен). Подробности и переменные — в `roles/app_image/README.md`.
+
+### Контракт для приложения (app_image)
+
+Чтобы приложение можно было деплоить этой ролью, в его рабочей директории
+должна быть **команда сборки образа** (по умолчанию `task image`). Роль —
+инициатор: она вызывает команду и передаёт ей случайный `BUILD_ID` через
+окружение. Команда обязана собрать **полный** образ и затегать его
+`<app_image_name>:$BUILD_ID`.
+
+Пример реализации на Taskfile (тег из `$BUILD_ID`, по умолчанию `dev` для
+локальной работы):
+
+```yaml
+image:
+  desc: 'Полный docker-образ. Тег из $BUILD_ID (по умолчанию dev).'
+  deps: [build]
+  cmds:
+    - docker build -t {{.BINARY}}:${BUILD_ID:-dev} .
+```
+
+Вызов роли в плейбуке:
+
+```yaml
+- name: 'Build and deliver application image'
+  ansible.builtin.import_role:
+    name: app_image
+  vars:
+    app_image_name: 'myapp'
+    app_image_src_dir: '{{ (playbook_dir, "..", "myapp") | path_join }}'
+# роль выставляет факт app_image_tag для рендера compose
+```