From 87262f73739fe8589017f71090a9cf8e7feb2ae4 Mon Sep 17 00:00:00 2001
From: Kevin Veen-Birkenbach <kevin@veen.world>
Date: Fri, 25 Apr 2025 14:44:33 +0200
Subject: [PATCH] Refactored ws implementation to use it in mastodon and in new
 espocrm role

---
 group_vars/all/09_ports.yml                   |  2 +-
 roles/docker-attendize/tasks/main.yml         |  2 +-
 roles/docker-espocrm/tasks/main.yml           | 17 ++++---
 .../templates/docker-compose.yml.j2           |  8 ++--
 .../docker-mastodon/tasks/create-domains.yml  |  9 ----
 roles/docker-mastodon/tasks/main.yml          | 11 +++--
 .../templates/docker-compose.yml.j2           |  2 +-
 .../templates/nginx.conf.j2                   |  2 +-
 roles/docker-mybb/tasks/setup-domain.yml      |  2 +-
 .../templates/nginx/docker.conf.j2            |  2 +-
 .../templates/nginx/host.conf.j2              |  2 +-
 .../templates/peertube.conf.j2                |  2 +-
 roles/nginx-docker-reverse-proxy/README.md    | 44 ++++++++++++-------
 .../nginx-docker-reverse-proxy/meta/main.yml  | 29 +++++++++++-
 .../templates/{ => headers}/iframe.conf.j2    |  0
 .../proxy_basic.conf.j2}                      |  2 +-
 .../{domain.conf.j2 => vhost/basic.conf.j2}   |  8 ++--
 .../templates/vhost/ws_generic.conf.j2}       | 34 +++++++-------
 roles/nginx-domain-setup/README.md            | 39 +++++++++++-----
 roles/nginx-domain-setup/defaults/main.yml    |  5 +++
 roles/nginx-domain-setup/meta/main.yml        | 25 +++++++++++
 roles/nginx-domain-setup/tasks/main.yml       |  8 ++--
 .../nginx-serve-files/templates/nginx.conf.j2 |  2 +-
 .../nginx-serve-html/templates/nginx.conf.j2  |  2 +-
 roles/nginx/tasks/main.yml                    |  4 +-
 roles/nginx/templates/nginx.conf.j2           |  1 +
 26 files changed, 173 insertions(+), 91 deletions(-)
 delete mode 100644 roles/docker-mastodon/tasks/create-domains.yml
 rename roles/nginx-docker-reverse-proxy/templates/{ => headers}/iframe.conf.j2 (100%)
 rename roles/nginx-docker-reverse-proxy/templates/{proxy_pass.conf.j2 => location/proxy_basic.conf.j2} (91%)
 rename roles/nginx-docker-reverse-proxy/templates/{domain.conf.j2 => vhost/basic.conf.j2} (74%)
 rename roles/{docker-mastodon/templates/mastodon.conf.j2 => nginx-docker-reverse-proxy/templates/vhost/ws_generic.conf.j2} (50%)
 create mode 100644 roles/nginx-domain-setup/defaults/main.yml
 create mode 100644 roles/nginx-domain-setup/meta/main.yml

diff --git a/group_vars/all/09_ports.yml b/group_vars/all/09_ports.yml
index 18a7bbd1..1908218a 100644
--- a/group_vars/all/09_ports.yml
+++ b/group_vars/all/09_ports.yml
@@ -1,7 +1,7 @@
 ports:
   # Ports which are exposed to localhost
   localhost:
-    web_socket:
+    websocket:
       mastodon:         4001
       espocrm:          4002
     oauth2_proxy:
diff --git a/roles/docker-attendize/tasks/main.yml b/roles/docker-attendize/tasks/main.yml
index 04ed1543..888db048 100644
--- a/roles/docker-attendize/tasks/main.yml
+++ b/roles/docker-attendize/tasks/main.yml
@@ -15,7 +15,7 @@
     
 - name: configure {{domains[application_id]}}.conf
   template: 
-    src: roles/nginx-docker-reverse-proxy/templates/domain.conf.j2 
+    src: roles/nginx-docker-reverse-proxy/templates/vhost/basic.conf.j2 
     dest: "{{nginx.directories.http.servers}}{{domains[application_id]}}.conf"
   notify: restart nginx
 
diff --git a/roles/docker-espocrm/tasks/main.yml b/roles/docker-espocrm/tasks/main.yml
index 2b974b84..01e6828b 100644
--- a/roles/docker-espocrm/tasks/main.yml
+++ b/roles/docker-espocrm/tasks/main.yml
@@ -1,27 +1,26 @@
-# ./roles/docker-espocrm/tasks/main.yml
 ---
 - name: "include docker-central-database"
   include_role:
     name: docker-central-database
 
-# -- Nginx reverse proxy and Let's Encrypt certificates (same pattern as the Gitea role) --
-- name: "include role nginx-domain-setup for {{ application_id }}"
-  include_role:
+- name: "Include setup for domain '{{ domain }}'"
+  include_role: 
     name: nginx-domain-setup
   vars:
-    domain: "{{ domains[application_id] }}"
-    http_port: "{{ ports.localhost.http[application_id] }}"
+    ws_path:              "/ws"
+    ws_port:              "{{ ports.localhost.websocket[application_id] }}"
+    client_max_body_size: "100m"
+    vhost_flavour:        "ws_generic"
+    domain:               "{{ domains[application_id] }}"
+    http_port:            "{{ ports.localhost.http[application_id] }}"
 
-# -- Copy docker-compose.yml and .env --
 - name: "copy docker-compose.yml and env file"
   include_tasks: copy-docker-compose-and-env.yml
 
-# -- Ensure containers are (re)started after the initial setup --
 - name: flush docker service
   meta: flush_handlers
   when: applications.espocrm.setup | bool
 
-# -- Run database initialisation or upgrade --
 - name: "run database setup / upgrade"
   command:
     cmd: "docker compose run --rm web php command.php upgrade"
diff --git a/roles/docker-espocrm/templates/docker-compose.yml.j2 b/roles/docker-espocrm/templates/docker-compose.yml.j2
index e39d8af6..bda42090 100644
--- a/roles/docker-espocrm/templates/docker-compose.yml.j2
+++ b/roles/docker-espocrm/templates/docker-compose.yml.j2
@@ -7,7 +7,7 @@ services:
 {% include 'roles/docker-compose/templates/services/base.yml.j2' %}
     environment:
       # --- DB connection ----------------------------------------------------
-      - ESPOCRM_DATABASE_PLATFORM=Mysql          # EspoCRM expects ‘Mysql’ even for MariaDB
+      - ESPOCRM_DATABASE_PLATFORM=Mysql
       - ESPOCRM_DATABASE_HOST={{ database_host }}
       - ESPOCRM_DATABASE_PORT={{ database_port }}
       - ESPOCRM_DATABASE_NAME={{ database_name }}
@@ -27,7 +27,7 @@ services:
     volumes:
       - data:/var/www/html
 
-  daemon:                                 # ↔  was “espocrm-daemon” in the example
+  daemon:
     image: espocrm/espocrm:{{ applications.espocrm.version }}
 {% include 'roles/docker-compose/templates/services/base.yml.j2' %}
     entrypoint: docker-daemon.sh
@@ -37,7 +37,7 @@ services:
       - data:/var/www/html
     restart: unless-stopped
 
-  websocket:                              # ↔  was “espocrm-websocket” in the example
+  websocket:
     image: espocrm/espocrm:{{ applications.espocrm.version }}
 {% include 'roles/docker-compose/templates/services/base.yml.j2' %}
     environment:
@@ -57,4 +57,4 @@ services:
 {% include 'templates/docker/compose/volumes.yml.j2' %}
   data:
 
-{% include 'templates/docker/compose/networks.yml.j2' %}
+{% include 'templates/docker/compose/networks.yml.j2' %}
\ No newline at end of file
diff --git a/roles/docker-mastodon/tasks/create-domains.yml b/roles/docker-mastodon/tasks/create-domains.yml
deleted file mode 100644
index e0729656..00000000
--- a/roles/docker-mastodon/tasks/create-domains.yml
+++ /dev/null
@@ -1,9 +0,0 @@
-- name: "include role for {{application_id}} to recieve certs & do modification routines"
-  include_role:
-    name: nginx-https-get-cert-modify-all
-    
-- name: configure {{domain}}.conf
-  template: 
-    src:  "mastodon.conf.j2" 
-    dest: "{{nginx.directories.http.servers}}{{domain}}.conf"
-  notify: restart nginx
\ No newline at end of file
diff --git a/roles/docker-mastodon/tasks/main.yml b/roles/docker-mastodon/tasks/main.yml
index 66c7a77a..249dc884 100644
--- a/roles/docker-mastodon/tasks/main.yml
+++ b/roles/docker-mastodon/tasks/main.yml
@@ -3,13 +3,18 @@
   include_role: 
     name: docker-central-database
 
-- name: "include create-domains.yml for mastodon"
-  include_tasks: create-domains.yml
+- name: "Include setup for domain '{{ domain }}'"
+  include_role: 
+    name: nginx-domain-setup
   loop: "{{ [domains.mastodon] + domains.mastodon_alternates }}"
   loop_control:
     loop_var: domain
   vars:
-    http_port: "{{ ports.localhost.http[application_id] }}"
+    http_port:            "{{ ports.localhost.http[application_id] }}"
+    ws_path:              "/api/v1/streaming"
+    ws_port:              "{{ ports.localhost.websocket[application_id] }}"
+    client_max_body_size: "80m"
+    vhost_flavour:        "ws_generic"
 
 - name: "copy docker-compose.yml and env file"
   include_tasks: copy-docker-compose-and-env.yml
diff --git a/roles/docker-mastodon/templates/docker-compose.yml.j2 b/roles/docker-mastodon/templates/docker-compose.yml.j2
index ec57ebbc..ea43f740 100644
--- a/roles/docker-mastodon/templates/docker-compose.yml.j2
+++ b/roles/docker-mastodon/templates/docker-compose.yml.j2
@@ -24,7 +24,7 @@ services:
     healthcheck:
       test: ['CMD-SHELL', 'wget -q --spider --proxy=off localhost:4000/api/v1/streaming/health || exit 1']
     ports:
-      - "127.0.0.1:{{ports.localhost.web_socket[application_id]}}:4000"
+      - "127.0.0.1:{{ports.localhost.websocket[application_id]}}:4000"
 {% include 'templates/docker/container/depends-on-database-redis.yml.j2' %}
 {% include 'templates/docker/container/networks.yml.j2' %}
 
diff --git a/roles/docker-matrix-compose/templates/nginx.conf.j2 b/roles/docker-matrix-compose/templates/nginx.conf.j2
index bb8a8539..48010d36 100644
--- a/roles/docker-matrix-compose/templates/nginx.conf.j2
+++ b/roles/docker-matrix-compose/templates/nginx.conf.j2
@@ -12,5 +12,5 @@ server {
     listen [::]:8448 ssl default_server;
 
     {% include 'roles/nginx-modifier-all/templates/global.includes.conf.j2'%}
-    {% include 'roles/nginx-docker-reverse-proxy/templates/proxy_pass.conf.j2' %}
+    {% include 'roles/nginx-docker-reverse-proxy/templates/location/proxy_basic.conf.j2' %}
 }
\ No newline at end of file
diff --git a/roles/docker-mybb/tasks/setup-domain.yml b/roles/docker-mybb/tasks/setup-domain.yml
index 83296202..a3fd2074 100644
--- a/roles/docker-mybb/tasks/setup-domain.yml
+++ b/roles/docker-mybb/tasks/setup-domain.yml
@@ -8,7 +8,7 @@
 
 - name: configure {{domains[application_id]}}.conf
   template: 
-    src:  "roles/nginx-docker-reverse-proxy/templates/domain.conf.j2" 
+    src:  "roles/nginx-docker-reverse-proxy/templates/vhost/basic.conf.j2" 
     dest: "{{nginx.directories.http.servers}}{{domains[application_id]}}.conf"
   notify: restart nginx
   vars: 
diff --git a/roles/docker-nextcloud/templates/nginx/docker.conf.j2 b/roles/docker-nextcloud/templates/nginx/docker.conf.j2
index 9b1f7340..470c120f 100644
--- a/roles/docker-nextcloud/templates/nginx/docker.conf.j2
+++ b/roles/docker-nextcloud/templates/nginx/docker.conf.j2
@@ -75,7 +75,7 @@ http {
         add_header X-Robots-Tag                         "noindex, nofollow"     always;
         add_header X-XSS-Protection                     "1; mode=block"         always;
         add_header X-Frame-Options "SAMEORIGIN" always;
-        {% include 'roles/nginx-docker-reverse-proxy/templates/iframe.conf.j2' %}
+        {% include 'roles/nginx-docker-reverse-proxy/templates/headers/iframe.conf.j2' %}
 
         # Remove X-Powered-By, which is an information leak
         fastcgi_hide_header X-Powered-By;
diff --git a/roles/docker-nextcloud/templates/nginx/host.conf.j2 b/roles/docker-nextcloud/templates/nginx/host.conf.j2
index 419f813e..78a297db 100644
--- a/roles/docker-nextcloud/templates/nginx/host.conf.j2
+++ b/roles/docker-nextcloud/templates/nginx/host.conf.j2
@@ -18,7 +18,7 @@ server
   client_body_buffer_size 400M;
   fastcgi_buffers 64 4K;
 
-  {% include 'roles/nginx-docker-reverse-proxy/templates/proxy_pass.conf.j2' %}
+  {% include 'roles/nginx-docker-reverse-proxy/templates/location/proxy_basic.conf.j2' %}
 
   location ^~ /.well-known {
     rewrite ^/\.well-known/host-meta\.json  /public.php?service=host-meta-json  last;
diff --git a/roles/docker-peertube/templates/peertube.conf.j2 b/roles/docker-peertube/templates/peertube.conf.j2
index c274e7a5..459c498f 100644
--- a/roles/docker-peertube/templates/peertube.conf.j2
+++ b/roles/docker-peertube/templates/peertube.conf.j2
@@ -5,7 +5,7 @@ server {
 
   {% include 'roles/nginx-modifier-all/templates/global.includes.conf.j2'%}
   
-  {% include 'roles/nginx-docker-reverse-proxy/templates/iframe.conf.j2' %}
+  {% include 'roles/nginx-docker-reverse-proxy/templates/headers/iframe.conf.j2' %}
   
   ##
   # Application
diff --git a/roles/nginx-docker-reverse-proxy/README.md b/roles/nginx-docker-reverse-proxy/README.md
index 5337b2b1..a2a704cd 100644
--- a/roles/nginx-docker-reverse-proxy/README.md
+++ b/roles/nginx-docker-reverse-proxy/README.md
@@ -1,19 +1,31 @@
-# role nginx-docker-reverse-proxy
+# Nginx Docker Reverse Proxy 🚀
 
-Uses nginx as an [reverse proxy](https://en.wikipedia.org/wiki/Reverse_proxy) for local docker applications.
+## Description
 
-## debug
-```bash
-curl -I {{address}}
-```
-- https://serverfault.com/questions/434915/nginx-proxy-caching-how-to-check-if-it-is-working
+This Ansible role deploys **Nginx** as a high-performance [reverse proxy](https://en.wikipedia.org/wiki/Reverse_proxy) in front of Docker-hosted services.  
+It provides automatic TLS integration, WebSocket support, and a flexible templating system for per-application configuration.
 
-## performance
-- https://stackoverflow.com/questions/33703230/caching-images-on-all-folder-levels-of-nginx-reverse-proxy
-- https://www.tweaked.io/guide/nginx-proxying/
-- https://serverfault.com/questions/796735/nginx-reverse-proxy-is-slow/796740
-- https://serverfault.com/questions/741610/what-is-the-difference-between-proxy-request-buffering-and-proxy-buffering-on-ng
-- https://askubuntu.com/questions/1103626/should-i-enable-client-max-body-size-proxy-request-buffering-and-proxy-bufferin
-- https://serverfault.com/questions/692577/whats-the-difference-between-proxy-buffer-and-proxy-cache-module-in-nginx-confi
-- https://github.com/sissbruecker/linkding/issues/88
-- https://www.bogotobogo.com/DevOps/Docker/docker/compose/Nginx-Reverse-Proxy-Multiple-Containers.php
+## Overview
+
+Optimised for Arch Linux, the role installs Nginx, prepares opinionated configuration snippets and exposes a simple interface for other roles to drop in new virtual-hosts.  
+It plays well with **Let’s Encrypt**, **OAuth2 Proxy**, and your existing Docker stack.
+
+## Purpose
+
+The goal of this role is to deliver a **hassle-free, production-ready reverse proxy** for self-hosted containers, suitable for homelabs and small-scale production workloads.
+
+## Features
+
+- **Automatic TLS & HSTS** — integrates with the *nginx-https* role for certificate management.  
+- **Flexible vHost templates** — *basic* and *ws_generic* flavours cover standard HTTP and WebSocket applications.  
+- **Security headers** — sensible defaults plus optional X-Frame-Options / CSP based on application settings.  
+- **WebSocket & HTTP/2 aware** — upgrades, keep-alive tuning, and gzip already configured.  
+- **OAuth2 gating** — drop-in support when *docker-oauth2-proxy* is present.  
+- **Modular includes** — headers, locations, and global snippets are factored for easy extension.
+
+## Credits 📝
+
+Developed and maintained by **Kevin Veen-Birkenbach**.  
+More at <https://www.veen.world>
+
+Part of the **CyMaIS Project** — licensed under the [CyMaIS NonCommercial License (CNCL)](https://s.veen.world/cncl)
diff --git a/roles/nginx-docker-reverse-proxy/meta/main.yml b/roles/nginx-docker-reverse-proxy/meta/main.yml
index 03d1e23a..7d13e95c 100644
--- a/roles/nginx-docker-reverse-proxy/meta/main.yml
+++ b/roles/nginx-docker-reverse-proxy/meta/main.yml
@@ -1,3 +1,28 @@
+---
+galaxy_info:
+  author: "Kevin Veen-Birkenbach"
+  description: "Nginx reverse proxy front-end for local Docker applications."
+  license: "CyMaIS NonCommercial License (CNCL)"
+  license_url: "https://s.veen.world/cncl"
+  company: |
+    Kevin Veen-Birkenbach
+    Consulting & Coaching Solutions
+    https://www.veen.world
+  min_ansible_version: "2.9"
+  platforms:
+    - name: Archlinux
+      versions:
+        - rolling
+  galaxy_tags:
+    - nginx
+    - docker
+    - reverse_proxy
+    - web
+    - automation
+    - archlinux
+  repository: https://s.veen.world/cymais
+  issue_tracker_url: https://s.veen.world/cymaisissues
+  documentation: https://s.veen.world/cymais
 dependencies:
-- docker
-- nginx-https
+  - role: docker
+  - role: nginx-https
\ No newline at end of file
diff --git a/roles/nginx-docker-reverse-proxy/templates/iframe.conf.j2 b/roles/nginx-docker-reverse-proxy/templates/headers/iframe.conf.j2
similarity index 100%
rename from roles/nginx-docker-reverse-proxy/templates/iframe.conf.j2
rename to roles/nginx-docker-reverse-proxy/templates/headers/iframe.conf.j2
diff --git a/roles/nginx-docker-reverse-proxy/templates/proxy_pass.conf.j2 b/roles/nginx-docker-reverse-proxy/templates/location/proxy_basic.conf.j2
similarity index 91%
rename from roles/nginx-docker-reverse-proxy/templates/proxy_pass.conf.j2
rename to roles/nginx-docker-reverse-proxy/templates/location/proxy_basic.conf.j2
index 233239da..94d612e6 100644
--- a/roles/nginx-docker-reverse-proxy/templates/proxy_pass.conf.j2
+++ b/roles/nginx-docker-reverse-proxy/templates/location/proxy_basic.conf.j2
@@ -14,7 +14,7 @@ location {{location | default("/")}}
   proxy_set_header X-Forwarded-Port 443;
   proxy_set_header Accept-Encoding "";
 
-  {% include 'roles/nginx-docker-reverse-proxy/templates/iframe.conf.j2' %}
+  {% include 'roles/nginx-docker-reverse-proxy/templates/headers/iframe.conf.j2' %}
 
   # WebSocket specific header
   proxy_http_version 1.1;
diff --git a/roles/nginx-docker-reverse-proxy/templates/domain.conf.j2 b/roles/nginx-docker-reverse-proxy/templates/vhost/basic.conf.j2
similarity index 74%
rename from roles/nginx-docker-reverse-proxy/templates/domain.conf.j2
rename to roles/nginx-docker-reverse-proxy/templates/vhost/basic.conf.j2
index 51772f84..2e59b23b 100644
--- a/roles/nginx-docker-reverse-proxy/templates/domain.conf.j2
+++ b/roles/nginx-docker-reverse-proxy/templates/vhost/basic.conf.j2
@@ -18,18 +18,18 @@ server
   {% if applications | get_oauth2_enabled(application_id) %}
     {% if applications[application_id].oauth2_proxy.location is defined %}
       {# Exposed and Unprotected Location #}
-      {% include 'proxy_pass.conf.j2' %}
+      {% include 'roles/nginx-docker-reverse-proxy/templates/location/proxy_basic.conf.j2' %}
       {% set oauth2_proxy_enabled = true %}
       {% set location = applications[application_id].oauth2_proxy.location %}
       {# Gated Location by OAuth2 Proxy #}
-      {% include 'proxy_pass.conf.j2' %}
+      {% include 'roles/nginx-docker-reverse-proxy/templates/location/proxy_basic.conf.j2' %}
     {% else %}
       {% set oauth2_proxy_enabled = true %}
       {# Protected Domain by OAuth2 Proxy #}
-      {% include 'proxy_pass.conf.j2'%}
+      {% include 'roles/nginx-docker-reverse-proxy/templates/location/proxy_basic.conf.j2'%}
     {% endif %}
   {% else %}
     {# Exposed Domain - Not protected by OAuth2 Proxy #}
-    {% include 'proxy_pass.conf.j2' %}
+    {% include 'roles/nginx-docker-reverse-proxy/templates/location/proxy_basic.conf.j2' %}
   {% endif %}
 }
diff --git a/roles/docker-mastodon/templates/mastodon.conf.j2 b/roles/nginx-docker-reverse-proxy/templates/vhost/ws_generic.conf.j2
similarity index 50%
rename from roles/docker-mastodon/templates/mastodon.conf.j2
rename to roles/nginx-docker-reverse-proxy/templates/vhost/ws_generic.conf.j2
index 4bf18304..06b49cc8 100644
--- a/roles/docker-mastodon/templates/mastodon.conf.j2
+++ b/roles/nginx-docker-reverse-proxy/templates/vhost/ws_generic.conf.j2
@@ -4,15 +4,14 @@ map $http_upgrade $connection_upgrade {
 }
 
 server {
-  server_name {{domain}};
+  server_name {{ domain }};
 
   {% include 'roles/letsencrypt/templates/ssl_header.j2' %}
+  {% include 'roles/nginx-modifier-all/templates/global.includes.conf.j2' %}
 
-  {% include 'roles/nginx-modifier-all/templates/global.includes.conf.j2'%}
-
+  client_max_body_size {{ client_max_body_size | default('100m') }};
   keepalive_timeout    70;
   sendfile             on;
-  client_max_body_size 80m;
 
   gzip on;
   gzip_disable "msie6";
@@ -25,24 +24,23 @@ server {
 
   add_header Strict-Transport-Security "max-age=31536000";
 
-  {% include 'roles/nginx-docker-reverse-proxy/templates/proxy_pass.conf.j2' %}
+  {% include 'roles/nginx-docker-reverse-proxy/templates/location/proxy_basic.conf.j2' %}
 
-  location /api/v1/streaming {
-    proxy_set_header Host $host;
-    proxy_set_header X-Real-IP $remote_addr;
-    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+  {% if ws_path is defined %}
+    location {{ ws_path }} {
+    proxy_set_header Host              $host;
+    proxy_set_header X-Real-IP         $remote_addr;
+    proxy_set_header X-Forwarded-For   $proxy_add_x_forwarded_for;
     proxy_set_header X-Forwarded-Proto https;
-    proxy_set_header Proxy "";
 
-    proxy_pass http://127.0.0.1:{{ports.localhost.web_socket[application_id]}};
-    proxy_buffering off;
-    proxy_redirect off;
-    proxy_http_version 1.1;
-    proxy_set_header Upgrade $http_upgrade;
-    proxy_set_header Connection $connection_upgrade;
-
-    tcp_nodelay on;
+    proxy_pass           http://127.0.0.1:{{ ws_port }};
+    proxy_buffering      off;
+    proxy_http_version   1.1;
+    proxy_set_header     Upgrade        $http_upgrade;
+    proxy_set_header     Connection     $connection_upgrade;
+    tcp_nodelay          on;
   }
+  {% endif %}
 
   error_page 500 501 502 503 504 /500.html;
 }
diff --git a/roles/nginx-domain-setup/README.md b/roles/nginx-domain-setup/README.md
index b08af5b4..e32d4ed1 100644
--- a/roles/nginx-domain-setup/README.md
+++ b/roles/nginx-domain-setup/README.md
@@ -1,16 +1,35 @@
-# Nginx Domain Setup Role 🚀
+# Nginx Domain Setup 🚀
 
-This role streamlines your Nginx configuration by performing several essential tasks:
+## Description
 
-- **Modify Nginx configuration** with the `nginx-modifier-all` role.
-- **Request and receive HTTPS certificates** using the `nginx-https-get-cert` role.
-- **Deploy a domain configuration file** from a Jinja2 template.
-- **Optionally secure your domain** with OAuth2 via the `docker-oauth2-proxy` role if enabled.
+This role bootstraps **per-domain Nginx configuration**: it requests TLS certificates, applies global modifiers, deploys a ready-made vHost file, and can optionally lock down access via OAuth2.
 
-## Author
+## Overview
 
-Developed by [Kevin Veen-Birkenbach](https://www.veen.world) 😎
+A higher-level orchestration wrapper, *nginx-domain-setup* ties together several lower-level roles:
 
----
+1. **`nginx-modifier-all`** – applies global tweaks and includes.  
+2. **`nginx-https-get-cert`** – obtains Let’s Encrypt certificates.  
+3. **Domain template deployment** – copies a Jinja2 vHost from *nginx-docker-reverse-proxy*.  
+4. **`docker-oauth2-proxy`** *(optional)* – protects the site with OAuth2.
 
-Happy automating! 🎉
+The result is a complete, reproducible domain rollout in a single playbook task.
+
+## Purpose
+
+Provide **one-stop, idempotent domain provisioning** for Nginx-based homelabs or small production environments.
+
+## Features
+
+- **End-to-end TLS** — certificate retrieval and secure headers included.  
+- **Template-driven vHosts** — choose *basic* or *ws_generic* flavours (or your own).  
+- **Conditional OAuth2** — easily toggle authentication per application.  
+- **Handler-safe** — automatically triggers an Nginx reload when templates change.  
+- **Composable** — designed to be called repeatedly for many domains.
+
+## Credits 📝
+
+Developed and maintained by **Kevin Veen-Birkenbach**.  
+Learn more at <https://www.veen.world>
+
+Part of the **CyMaIS Project** — licensed under the [CyMaIS NonCommercial License (CNCL)](https://s.veen.world/cncl)
\ No newline at end of file
diff --git a/roles/nginx-domain-setup/defaults/main.yml b/roles/nginx-domain-setup/defaults/main.yml
new file mode 100644
index 00000000..149cb6fd
--- /dev/null
+++ b/roles/nginx-domain-setup/defaults/main.yml
@@ -0,0 +1,5 @@
+# default vhost flavour
+vhost_flavour:        "basic"               # valid: basic | ws_generic
+
+# build the full template path from the flavour
+vhost_template_src:   "roles/nginx-docker-reverse-proxy/templates/vhost/{{ vhost_flavour }}.conf.j2"
\ No newline at end of file
diff --git a/roles/nginx-domain-setup/meta/main.yml b/roles/nginx-domain-setup/meta/main.yml
new file mode 100644
index 00000000..1e261d42
--- /dev/null
+++ b/roles/nginx-domain-setup/meta/main.yml
@@ -0,0 +1,25 @@
+---
+galaxy_info:
+  author: "Kevin Veen-Birkenbach"
+  description: "Automated domain provisioning (TLS, vHost, OAuth2) for Nginx."
+  license: "CyMaIS NonCommercial License (CNCL)"
+  license_url: "https://s.veen.world/cncl"
+  company: |
+    Kevin Veen-Birkenbach
+    Consulting & Coaching Solutions
+    https://www.veen.world
+  min_ansible_version: "2.9"
+  platforms:
+    - name: Archlinux
+      versions:
+        - rolling
+  galaxy_tags:
+    - nginx
+    - tls
+    - letsencrypt
+    - oauth2
+    - automation
+    - archlinux
+  repository: https://s.veen.world/cymais
+  issue_tracker_url: https://s.veen.world/cymaisissues
+  documentation: https://s.veen.world/cymais
\ No newline at end of file
diff --git a/roles/nginx-domain-setup/tasks/main.yml b/roles/nginx-domain-setup/tasks/main.yml
index 8ae1b912..b55d513b 100644
--- a/roles/nginx-domain-setup/tasks/main.yml
+++ b/roles/nginx-domain-setup/tasks/main.yml
@@ -2,10 +2,10 @@
   include_role:
     name: nginx-https-get-cert-modify-all
     
-- name: "copy nginx domain configuration to {{configuration_destination}}"
-  template: 
-    src:  "roles/nginx-docker-reverse-proxy/templates/domain.conf.j2" 
-    dest: "{{configuration_destination}}"
+- name: "copy nginx domain configuration to {{ configuration_destination }}"
+  template:
+    src:  "{{ vhost_template_src }}"
+    dest: "{{ configuration_destination }}"
   notify: restart nginx
   
 - name: "include the docker-oauth2-proxy role {{domain}}"
diff --git a/roles/nginx-serve-files/templates/nginx.conf.j2 b/roles/nginx-serve-files/templates/nginx.conf.j2
index 744eda4f..7409343a 100644
--- a/roles/nginx-serve-files/templates/nginx.conf.j2
+++ b/roles/nginx-serve-files/templates/nginx.conf.j2
@@ -6,7 +6,7 @@ server
 
   {% include 'roles/nginx-modifier-all/templates/global.includes.conf.j2'%}
 
-  {% include 'roles/nginx-docker-reverse-proxy/templates/iframe.conf.j2' %}
+  {% include 'roles/nginx-docker-reverse-proxy/templates/headers/iframe.conf.j2' %}
   charset utf-8;
   
   location /
diff --git a/roles/nginx-serve-html/templates/nginx.conf.j2 b/roles/nginx-serve-html/templates/nginx.conf.j2
index 7293cbb7..2c492ac5 100644
--- a/roles/nginx-serve-html/templates/nginx.conf.j2
+++ b/roles/nginx-serve-html/templates/nginx.conf.j2
@@ -6,7 +6,7 @@ server
 
   {% include 'roles/nginx-modifier-all/templates/global.includes.conf.j2'%}
 
-  {% include 'roles/nginx-docker-reverse-proxy/templates/iframe.conf.j2' %}
+  {% include 'roles/nginx-docker-reverse-proxy/templates/headers/iframe.conf.j2' %}
   charset utf-8;
   
   location /
diff --git a/roles/nginx/tasks/main.yml b/roles/nginx/tasks/main.yml
index 98f8d0a4..fcf05d8c 100644
--- a/roles/nginx/tasks/main.yml
+++ b/roles/nginx/tasks/main.yml
@@ -1,7 +1,9 @@
 ---
 - name: install nginx
   pacman:
-    name:   nginx
+    name:
+      - nginx
+      - nginx-mod-stream # Enable Stream support
     state:  present
   notify: restart nginx
   when: run_once_nginx is not defined
diff --git a/roles/nginx/templates/nginx.conf.j2 b/roles/nginx/templates/nginx.conf.j2
index 2211dead..17e6d14b 100644
--- a/roles/nginx/templates/nginx.conf.j2
+++ b/roles/nginx/templates/nginx.conf.j2
@@ -1,3 +1,4 @@
+load_module /usr/lib/nginx/modules/ngx_stream_module.so; # Enable Stream support
 worker_processes auto;
 
 events