flatten the "playbooks" directory for better structure

Because of how Ansible local relative search paths work, the global
"files" and "templates" directories need to be next to the playbooks.
However its not intuitive to look into the playbooks directory to find
the files and templates for a host.
Therefore flatten the playbooks directory to get rid of this confusing
structure.

Also see:
https://docs.ansible.com/ansible/latest/playbook_guide/playbook_pathing.html#resolving-local-relative-paths

roles/docker_compose/README.md

@@ -0,0 +1,34 @@
+# Role `docker_compose`
+
+A role for deploying a Docker-Compose-based application.
+It deploys the given Compose file as well as configuration files to the specified hosts and makes sure all services are up-to-date and running.
+The Compose file gets deployed to `/ansible_docker_compose/compose.yaml` and the configuration files get deployed into the `/ansible_docker_compose/configs/` directory.
+A use case for the deployment of the additional configuration files is Composes top-level element `configs` in conjunction with the `configs` option for services.
+
+## Supported Distributions
+
+The following distributions are supported:
+
+- Debian 11
+
+## Required Arguments
+
+For the required arguments look at the [`argument_specs.yaml`](./meta/argument_specs.yaml).
+
+## `hosts`
+
+The `hosts` for this role need to be the machines, for which you want to make sure the given Compose file is deployed and all services of it are up-to-date and running.
+
+## Links & Resources
+
+- <https://docs.docker.com/compose/>
+- <https://docs.docker.com/compose/compose-v2/>
+- <https://docs.docker.com/compose/production/>
+- <https://docs.docker.com/compose/startup-order/>
+- <https://docs.docker.com/compose/compose-file/>
+- <https://docs.docker.com/compose/compose-file/03-compose-file/>
+- <https://docs.docker.com/compose/compose-file/08-configs/>
+- <https://docs.docker.com/compose/compose-file/05-services/#configs>
+- <https://docs.docker.com/engine/reference/commandline/compose_up/>
+- <https://docs.docker.com/engine/reference/commandline/compose_ps/>
+- <https://docs.docker.com/engine/reference/commandline/compose_down/>

roles/docker_compose/defaults/main.yaml

@@ -0,0 +1 @@
+docker_compose__configuration_files: [ ]

roles/docker_compose/handlers/main.yaml

@@ -0,0 +1,6 @@
+- name: docker compose down
+  ansible.builtin.command:
+    cmd: /usr/bin/docker compose down
+    chdir: /ansible_docker_compose
+  become: true
+  changed_when: true  # This is always changed.

roles/docker_compose/meta/argument_specs.yaml

@@ -0,0 +1,26 @@
+argument_specs:
+  main:
+    options:
+      docker_compose__compose_file_content:
+        description: >-
+          The content of the Compose file at
+          `/ansible_docker_compose/compose.yaml`.
+        type: str
+        required: true
+      docker_compose__configuration_files:
+        description: >-
+          A list of configuration files to be deployed in the
+          `/ansible_docker_compose/configs/` directory.
+        type: list
+        elements: dict
+        required: false
+        default: [ ]
+        options:
+          name:
+            description: The name of the configuration file.
+            type: str
+            required: true
+          content:
+            description: The content of the configuration file.
+            type: str
+            required: true

roles/docker_compose/meta/main.yaml

@@ -0,0 +1,10 @@
+---
+dependencies:
+  - role: distribution_check
+    vars:
+      distribution_check__distribution_support_spec:
+        - name: Debian
+          major_versions:
+            - 11
+            - 12
+  - role: docker

roles/docker_compose/tasks/main.yaml

@@ -0,0 +1,121 @@
+- name: make sure the `/ansible_docker_compose` directory exists
+  ansible.builtin.file:
+    path: /ansible_docker_compose
+    state: directory
+    mode: "0755"
+    owner: root
+    group: root
+  become: true
+
+- name: deploy the Compose file
+  ansible.builtin.copy:
+    content: "{{ docker_compose__compose_file_content }}"
+    dest: /ansible_docker_compose/compose.yaml
+    mode: "0644"
+    owner: root
+    group: root
+  become: true
+  notify: docker compose down
+
+- name: make sure the `/ansible_docker_compose/configs` directory exists
+  ansible.builtin.file:
+    path: /ansible_docker_compose/configs
+    state: directory
+    mode: "0755"
+    owner: root
+    group: root
+  become: true
+
+- name: set `docker_compose__config_files_to_exist` fact initially to an empty list
+  ansible.builtin.set_fact:
+    docker_compose__config_files_to_exist: [ ]
+
+- name: add names from `docker_compose__configuration_files` to `docker_compose__config_files_to_exist` fact
+  ansible.builtin.set_fact:
+    docker_compose__config_files_to_exist: "{{ docker_compose__config_files_to_exist + [ item.name ] }}"  # noqa: jinja[spacing]
+  loop: "{{ docker_compose__configuration_files }}"
+
+- name: find configuration files to remove
+  ansible.builtin.find:
+    paths: /ansible_docker_compose/configs/
+    recurse: false
+    excludes: "{{ docker_compose__config_files_to_exist }}"
+  register: docker_compose__config_files_to_remove
+
+- name: remove all configuration files, which should be removed
+  ansible.builtin.file:
+    path: "{{ item.path }}"
+    state: absent
+  become: true
+  loop: "{{ docker_compose__config_files_to_remove.files }}"
+  # notify: docker compose down
+
+- name: make sure all given configuration files are deployed
+  ansible.builtin.copy:
+    content: "{{ item.content }}"
+    dest: "/ansible_docker_compose/configs/{{ item.name }}"
+    mode: "0644"
+    owner: root
+    group: root
+  become: true
+  loop: "{{ docker_compose__configuration_files }}"
+  # notify: docker compose down
+
+- name: Flush handlers to make "docker compose down" handler run now
+  ansible.builtin.meta: flush_handlers
+
+- name: docker compose ps --format json before docker compose up
+  ansible.builtin.command:
+    cmd: /usr/bin/docker compose ps --format json
+    chdir: /ansible_docker_compose
+  become: true
+  changed_when: false
+  register: docker_compose__ps_json_before_up
+
+- name: docker compose up --detach --pull always --build
+  ansible.builtin.command:
+    cmd: /usr/bin/docker compose up --detach --pull always --build --remove-orphans
+    chdir: /ansible_docker_compose
+  become: true
+  changed_when: false
+  # The changed for this task is tried to be determined by the "potentially
+  # report changed" task together with the "docker compose ps --format json
+  # [...]" tasks.
+
+- name: docker compose ps --format json after docker compose up
+  ansible.builtin.command:
+    cmd: /usr/bin/docker compose ps --format json
+    chdir: /ansible_docker_compose
+  become: true
+  changed_when: false
+  register: docker_compose__ps_json_after_up
+
+# Doesn't work anymore. Dunno why.
+# TODO: Fix
+# - name: potentially report changed
+#   ansible.builtin.debug:
+#     msg: "If this reports changed, then the docker compose containers changed."
+#   changed_when: (docker_compose__ps_json_before_up.stdout | from_json | community.general.json_query('[].ID') | sort)
+#                 != (docker_compose__ps_json_after_up.stdout | from_json | community.general.json_query('[].ID') | sort)
+
+- name: Make sure anacron is installed
+  become: true
+  ansible.builtin.package:
+    name: anacron
+    state: present
+
+- name: Install automatic update cron job
+  become: true
+  ansible.builtin.cron:
+    name: 'docker compose auto update'
+    minute: "0"
+    hour: "5"
+    job: "cd /ansible_docker_compose; docker compose pull && docker compose up -d"
+
+- name: Install automatic cleanup cron job
+  become: true
+  ansible.builtin.cron:
+    name: 'docker compose auto update'
+    minute: "23"
+    hour: "4"
+    job: "docker system prune -a -f"