move roles, files and templates dirs out of playbook dir into root dir

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 move them out of the "playbooks" directory into the root
directory and add symlinks so everything still works.

Similarly for local roles, they also need to be next to the playbooks.
So for a nicer structure, move the "roles" directory out into the root
directory as well and add a symlink so everything still works.

Also see:
https://docs.ansible.com/ansible/latest/playbook_guide/playbook_pathing.html#resolving-local-relative-paths
https://docs.ansible.com/ansible/latest/playbook_guide/playbooks_reuse_roles.html#storing-and-finding-roles

roles/nginx/README.md

@@ -0,0 +1,59 @@
+# Role `nginx`
+
+Makes sure the `nginx` package is installed from the NGINX repos on the specified hosts.
+Also makes sure a desirable baseline of NGINX configs is deployed on the specified hosts.
+For the NGINX site configurations the config template below can be used.
+
+## Entry Points
+
+The entry points available for external use are:
+
+- `main`
+
+## 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).
+
+## Updates
+
+This role updates NGINX to the latest version covered by the provided version spec., if needed.
+
+## `hosts`
+
+The `hosts` for this role need to be the machines, for which you want to make sure the `nginx` package is installed from the NGINX repos and a desirable baseline of NGINX configs is deployed.
+
+## Config Template
+
+Here's a config template, which can be used for new NGINX site configs, which you can supply to this role using the `nginx__configurations` argument.
+Just replace the placeholder values with real ones and extend and edit it as needed.
+
+```
+# partly generated 2022-01-08, Mozilla Guideline v5.6, nginx 1.17.7, OpenSSL 1.1.1k, intermediate configuration
+# https://ssl-config.mozilla.org/#server=nginx&version=1.17.7&config=intermediate&openssl=1.1.1k&guideline=5.6
+server {
+    listen 443 ssl http2;
+    #listen [::]:443 ssl http2;
+    server_name replace_me;
+
+    ssl_certificate /path/to/signed_cert_plus_intermediates;
+    ssl_certificate_key /path/to/private_key;
+    # verify chain of trust of OCSP response using Root CA and Intermediate certs
+    ssl_trusted_certificate /path/to/root_CA_cert_plus_intermediates;
+
+    # HSTS (ngx_http_headers_module is required) (63072000 seconds)
+    add_header Strict-Transport-Security "max-age=63072000" always;
+
+    # replace with the IP address of your resolver
+    resolver 127.0.0.1;
+}
+```
+
+## Links & Resources
+
+- <https://docs.nginx.com/nginx/admin-guide/installing-nginx/installing-nginx-open-source/#installing-prebuilt-debian-packages>

roles/nginx/defaults/main.yaml

@@ -0,0 +1,5 @@
+nginx__deploy_redirect_conf: true
+nginx__deploy_tls_conf: true
+nginx__configurations: [ ]
+nginx__use_custom_nginx_conf: false
+nginx__custom_nginx_conf: ""

roles/nginx/files/redirect.conf

@@ -0,0 +1,14 @@
+# partly generated 2022-01-08, Mozilla Guideline v5.6, nginx 1.17.7, OpenSSL 1.1.1k, intermediate configuration
+# https://ssl-config.mozilla.org/#server=nginx&version=1.17.7&config=intermediate&openssl=1.1.1k&guideline=5.6
+server {
+    listen 80 default_server;
+    #listen [::]:80 default_server;
+
+    location / {
+        return 301 https://$host$request_uri;
+    }
+
+    location /.well-known/acme-challenge/ {
+        proxy_pass http://127.0.0.1:31820/.well-known/acme-challenge/;
+    }
+}

roles/nginx/files/tls.conf

@@ -0,0 +1,19 @@
+# partly generated 2022-01-08, Mozilla Guideline v5.6, nginx 1.17.7, OpenSSL 1.1.1k, intermediate configuration
+# https://ssl-config.mozilla.org/#server=nginx&version=1.17.7&config=intermediate&openssl=1.1.1k&guideline=5.6
+
+
+ssl_session_timeout 1d;
+ssl_session_cache shared:MozSSL:10m;  # about 40000 sessions
+ssl_session_tickets off;
+
+# curl https://ssl-config.mozilla.org/ffdhe2048.txt > /path/to/dhparam
+ssl_dhparam /etc/nginx-mozilla-dhparam;
+
+# intermediate configuration
+ssl_protocols TLSv1.2 TLSv1.3;
+ssl_ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384;
+ssl_prefer_server_ciphers off;
+
+# OCSP stapling
+ssl_stapling on;
+ssl_stapling_verify on;

roles/nginx/handlers/main.yaml

@@ -0,0 +1,10 @@
+- name: Restart `nginx.service`
+  ansible.builtin.systemd:
+    name: nginx.service
+    state: restarted
+  become: true
+
+- name: apt-get update
+  ansible.builtin.apt:
+    update_cache: true
+  become: true

roles/nginx/meta/argument_specs.yaml

@@ -0,0 +1,64 @@
+argument_specs:
+  main:
+    options:
+      nginx__version_spec:
+        description: >-
+          The version specification to use for installing the `nginx` package. The
+          provided version specification will be used like the following: `nginx={{
+          nginx__version_spec }}*`. This makes it possible to e.g. specify
+          until a minor version (like `1.3.`) and then have patch versions be
+          installed automatically (like `1.3.1` and so on).
+        type: str
+        required: true
+      nginx__deploy_redirect_conf:
+        description: >-
+          Whether or not to deploy a `redirect.conf` to
+          `/etc/nginx/conf.d/redirect.conf`.
+        type: bool
+        required: false
+        default: true
+      nginx__deploy_tls_conf:
+        description: >-
+          Whether or not to deploy a `tls.conf` to `/etc/nginx/conf.d/tls.conf`.
+        type: bool
+        required: false
+        default: true
+      nginx__configurations:
+        description: A list of nginx configurations.
+        type: list
+        elements: dict
+        required: false
+        default: [ ]
+        options:
+          name:
+            description: >-
+              The name of the configuration file, where the configuration should
+              be deployed to. The file will be placed under `/etc/nginx/conf.d/`
+              and `.conf` will be appended to the given name. So in the end the
+              path will be like this: `/etc/nginx/conf.d/\{\{ name \}\}.conf`.
+              Note that the names `tls` and `redirect` aren't allowed.
+            type: str
+            required: true
+          content:
+            description: The content of the configuration.
+            type: str
+            required: true
+      nginx__use_custom_nginx_conf:
+        description: >-
+          Whether or not to use a custom `/etc/nginx/nginx.conf`. If set to
+          true, you must provide a custom `nginx.conf` via
+          `nginx__custom_nginx_conf`.
+        type: bool
+        required: false
+        default: false
+      nginx__custom_nginx_conf:
+        description: >-
+          The value for a `nginx.conf` to be placed at `/etc/nginx/nginx.conf`.
+          You must set `nginx__use_custom_nginx_conf` to true for this value to
+          be used.
+          You should probably make sure that your custom `nginx.conf` still
+          includes `/etc/nginx/conf.d/*.conf` so that the configuration provided
+          using `nginx__configurations` still work.
+        type: str
+        required: false
+        default: ""

roles/nginx/meta/main.yaml

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

roles/nginx/tasks/main.yaml

@@ -0,0 +1,19 @@
+- name: make sure nginx configuration names are valid
+  ansible.builtin.include_role:
+    name: nginx
+    tasks_from: make_sure_nginx_configuration_names_are_valid
+
+- name: make sure NGINX repos are setup
+  ansible.builtin.include_role:
+    name: nginx
+    tasks_from: main/repo_setup
+
+- name: make sure NGINX is installed
+  ansible.builtin.include_role:
+    name: nginx
+    tasks_from: main/nginx_install
+
+- name: make sure desirable NGINX configs are deployed
+  ansible.builtin.include_role:
+    name: nginx
+    tasks_from: main/config_deploy

roles/nginx/tasks/main/config_deploy.yaml

@@ -0,0 +1,132 @@
+- name: check, if a save of a previous `nginx.conf` is present
+  ansible.builtin.stat:
+    path: /etc/nginx/nginx.conf.ansiblesave
+  register: nginx__nginx_conf_ansiblesave_stat_result
+
+- name: handle the case, where a custom `nginx.conf` is to be used
+  when: nginx__use_custom_nginx_conf
+  block:
+    - name: when no `nginx.conf.ansiblesave` is present, save the current `nginx.conf`
+      when: not nginx__nginx_conf_ansiblesave_stat_result.stat.exists
+      ansible.builtin.copy:
+        force: true
+        dest: /etc/nginx/nginx.conf.ansiblesave
+        mode: "0644"
+        owner: root
+        group: root
+        remote_src: true
+        src: /etc/nginx/nginx.conf
+      become: true
+
+    - name: deploy the custom `nginx.conf`
+      ansible.builtin.copy:
+        content: "{{ nginx__custom_nginx_conf }}"
+        dest: "/etc/nginx/nginx.conf"
+        mode: "0644"
+        owner: root
+        group: root
+      become: true
+      notify: Restart `nginx.service`
+
+- name: handle the case, where no custom `nginx.conf` is to be used
+  when: not nginx__use_custom_nginx_conf
+  block:
+    - name: when a `nginx.conf.ansiblesave` is present, copy it to `nginx.conf`
+      when: nginx__nginx_conf_ansiblesave_stat_result.stat.exists
+      ansible.builtin.copy:
+        force: true
+        dest: /etc/nginx/nginx.conf
+        mode: "0644"
+        owner: root
+        group: root
+        remote_src: true
+        src: /etc/nginx/nginx.conf.ansiblesave
+      become: true
+      notify: Restart `nginx.service`
+
+    - name: delete the `nginx.conf.ansiblesave`, if it is present
+      when: nginx__nginx_conf_ansiblesave_stat_result.stat.exists
+      ansible.builtin.file:
+        path: /etc/nginx/nginx.conf.ansiblesave
+        state: absent
+      become: true
+
+- name: make sure mozilla dhparam is deployed
+  ansible.builtin.get_url:
+    force: true
+    dest: /etc/nginx-mozilla-dhparam
+    mode: "0644"
+    url: https://ssl-config.mozilla.org/ffdhe2048.txt
+  become: true
+  notify: Restart `nginx.service`
+
+- name: set `nginx__config_files_to_exist` fact initially to an empty list
+  ansible.builtin.set_fact:
+    nginx__config_files_to_exist: [ ]
+
+- name: handle the case, where tls.conf should be deployed
+  when: nginx__deploy_tls_conf
+  block:
+    - name: make sure tls.conf is deployed
+      ansible.builtin.copy:
+        force: true
+        dest: /etc/nginx/conf.d/tls.conf
+        mode: "0644"
+        owner: root
+        group: root
+        src: tls.conf
+      become: true
+      notify: Restart `nginx.service`
+
+    - name: add tls.conf to nginx__config_files_to_exist
+      ansible.builtin.set_fact:
+        nginx__config_files_to_exist: "{{ nginx__config_files_to_exist + [ 'tls.conf' ] }}"  # noqa: jinja[spacing]
+
+- name: handle the case, where redirect.conf should be deployed
+  when: nginx__deploy_redirect_conf
+  block:
+    - name: make sure redirect.conf is deployed
+      ansible.builtin.copy:
+        force: true
+        dest: /etc/nginx/conf.d/redirect.conf
+        mode: "0644"
+        owner: root
+        group: root
+        src: redirect.conf
+      become: true
+      notify: Restart `nginx.service`
+
+    - name: add redirect.conf to nginx__config_files_to_exist
+      ansible.builtin.set_fact:
+        nginx__config_files_to_exist: "{{ nginx__config_files_to_exist + [ 'redirect.conf' ] }}"  # noqa: jinja[spacing]
+
+- name: make sure all given configuration files are deployed
+  ansible.builtin.copy:
+    content: "{{ item.content }}"
+    dest: "/etc/nginx/conf.d/{{ item.name }}.conf"
+    mode: "0644"
+    owner: root
+    group: root
+  become: true
+  loop: "{{ nginx__configurations }}"
+  notify: Restart `nginx.service`
+
+- name: add names plus suffix from `nginx__configurations` to `nginx__config_files_to_exist` fact
+  ansible.builtin.set_fact:
+    nginx__config_files_to_exist: "{{ nginx__config_files_to_exist + [ item.name + '.conf' ] }}"  # noqa: jinja[spacing]
+  loop: "{{ nginx__configurations }}"
+
+- name: find configuration files to remove
+  ansible.builtin.find:
+    paths: /etc/nginx/conf.d/
+    recurse: false
+    excludes: "{{ nginx__config_files_to_exist }}"
+  register: nginx__config_files_to_remove
+
+- name: remove all configuration file, which should be removed
+  ansible.builtin.file:
+    path: "{{ item.path }}"
+    state: absent
+  become: true
+  loop: "{{ nginx__config_files_to_remove.files }}"
+  notify: Restart `nginx.service`

roles/nginx/tasks/main/nginx_install.yaml

@@ -0,0 +1,13 @@
+- name: make sure the `nginx` package is installed
+  ansible.builtin.apt:
+    name: nginx={{ nginx__version_spec }}*
+    state: present
+    allow_change_held_packages: true
+    update_cache: true
+  become: true
+
+- name: apt-mark hold `nginx`
+  ansible.builtin.dpkg_selections:
+    name: nginx
+    selection: hold
+  become: true

roles/nginx/tasks/main/repo_setup.yaml

@@ -0,0 +1,51 @@
+- name: gather package facts
+  ansible.builtin.package_facts:
+    manager: apt
+
+- name: make sure `gnupg` package is installed
+  ansible.builtin.apt:
+    name: gnupg
+    state: present
+    update_cache: true
+  become: true
+  when: "'gnupg' not in ansible_facts.packages"
+
+- name: make sure NGINX signing key is added
+  ansible.builtin.get_url:
+    url: https://nginx.org/keys/nginx_signing.key
+    dest: /etc/apt/trusted.gpg.d/nginx.asc
+    mode: "0644"
+    owner: root
+    group: root
+  become: true
+  notify: apt-get update
+
+- name: make sure NGINX APT repository is added
+  ansible.builtin.apt_repository:
+    repo: "deb [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/nginx.asc] https://nginx.org/packages/debian/ {{ ansible_distribution_release }} nginx"
+    state: present
+  become: true
+  notify: apt-get update
+
+- name: make sure NGINX APT source repository is added
+  ansible.builtin.apt_repository:
+    repo: "deb-src [arch=amd64 signed-by=/etc/apt/trusted.gpg.d/nginx.asc] https://nginx.org/packages/debian/ {{ ansible_distribution_release }} nginx"
+    state: present
+  become: true
+  notify: apt-get update
+
+- name: set up repository pinning to make sure nginx package gets installed from NGINX repositories
+  ansible.builtin.copy:
+    content: |
+      Package: *
+      Pin: origin nginx.org
+      Pin: release o=nginx
+      Pin-Priority: 900
+    dest: /etc/apt/preferences.d/99nginx
+    owner: root
+    group: root
+    mode: "0644"
+  become: true
+
+- name: Flush handlers to make sure "apt-get update" handler runs, if needed
+  ansible.builtin.meta: flush_handlers

roles/nginx/tasks/make_sure_nginx_configuration_names_are_valid.yaml

@@ -0,0 +1,6 @@
+- name: make sure nginx configuration names are valid
+  ansible.builtin.fail:
+    msg: "You used the following name: `{{ item.name }}`. Please make sure to not use the following names: `tls`, `redirect`."
+  when: item.name == "tls"
+        or item.name == "redirect"
+  loop: "{{ nginx__configurations }}"