mirror of
https://github.com/kevinveenbirkenbach/computer-playbook.git
synced 2025-12-07 18:05:09 +00:00
Kevin Veen-Birkenbach
986f959696
Refactor proxy/webserver configuration variables to a consistent webserver_* naming scheme across roles. Replace legacy variables like proxy_extra_configuration, client_max_body_size, vhost_flavour, location_ws and ws_port with webserver_extra_configuration, webserver_client_max_body_size, webserver_vhost_flavour, webserver_websocket_location and webserver_websocket_port. Update NGINX vhost and location templates (html, upload, ws, basic, ws_generic) as well as callers (sys-front-inj-all, sys-stk-front-proxy, various web-app-* and web-svc-* roles) to use the new naming. Tighten docker-compose Git repository handling by making docker_git_repository_pull depend on docker_git_repository_address being defined, a string and non-empty. This avoids accidental Git operations when the repository address is unset or of the wrong type. Refactor the BigBlueButton role structure and fix deployment bugs: introduce 01_core.yml to orchestrate docker/proxy setup, database seeding, websocket map deployment, docker-compose overrides and admin/bootstrap logic in a single once-executed entrypoint. Rename supporting task files (02_docker-compose.yml, 03_administrator.yml, 04_dependencies.yml) and update tasks/main.yml to delegate via include_tasks with run_once_web_app_bigbluebutton. Improve Greenlight admin creation behavior by treating the 'Email has already been taken' error as a non-fatal, unchanged outcome and running user:set_admin_role as a fallback, both for the primary password and the OIDC starred-password path. Also standardize vhost flavour selection for services like Mailu, Discourse, CDN, Collabora, Coturn, OnlyOffice, Simpleicons and web-svc-logout by explicitly passing webserver_vhost_flavour where needed and aligning client_max_body_size and websocket configuration with the new webserver_* variables. Reference: ChatGPT conversation https://chatgpt.com/share/6931c530-bba8-800f-9997-dd61dc1d497b
Nginx vHost Templates: Basic vs. WebSocket (ws_generic)
This directory provides two Nginx server templates for reverse proxying Dockerized applications behind Nginx:
basic.conf.j2ws_generic.conf.j2
When to Use Which Template?
1. basic.conf.j2
Use this template for standard HTTP/S applications.
It is optimized for typical web applications (e.g., static sites, PHP, Node.js, Django, etc.) that do not require persistent, bidirectional WebSocket connections.
-
Features:
- HTTP/2 support, TLS/SSL integration
- Reverse proxy with buffering enabled (
proxy_buffering on) - Allows advanced content filtering (e.g., via Lua body/headers)
- Suitable for most REST APIs, web frontends, and admin panels
-
Pros:
- Enables HTML/body manipulation (for injecting snippets, analytics, CSP, etc.)
- Optimized for efficient caching and GZIP compression
- Good default for "normal" web traffic
-
Cons:
- Not suitable for WebSocket endpoints (buffering can break WS)
- Slightly more latency for streaming data due to buffering
2. ws_generic.conf.j2
Use this template for applications requiring WebSocket support.
Designed for services (e.g., chat servers, real-time dashboards) needing fast, persistent connections using the WebSocket protocol.
-
Features:
- WebSocket-aware:
proxy_buffering off, special upgrade headers - Supports standard HTTP/S traffic alongside WebSockets
- Proper handling of connection upgrades and protocol switching
- WebSocket-aware:
-
Pros:
- Required for all WebSocket endpoints
- Allows instant, low-latency bidirectional traffic
- Prevents data loss or connection drops due to proxy buffering
-
Cons:
- Disables body/content filtering and response manipulation
- No buffering means less effective for caching/optimization
- Not suitable for scenarios requiring Lua/JS content injection
Summary Table
| Use Case | Template | Buffering | WebSocket? | Can Filter Content? |
|---|---|---|---|---|
| Static/Classic Website | basic.conf.j2 |
On | No | Yes |
| REST API | basic.conf.j2 |
On | No | Yes |
| Real-Time Chat/App | ws_generic.conf.j2 |
Off | Yes | No |
| Dashboard w/Live Data | ws_generic.conf.j2 |
Off | Yes | No |
| Needs HTML Injection | basic.conf.j2 |
On | No | Yes |
Good to Know
- Never enable buffering for true WebSocket connections!
Useproxy_buffering off;(as inws_generic.conf.j2) or connections may fail. - For most classic web applications, use the basic template.
- For apps where you want to inject or modify HTML (e.g., analytics scripts), only the basic template supports this.
Author & Project
By Kevin Veen-Birkenbach
Part of the Infinito.Nexus Project
Licensed under the Infinito.Nexus NonCommercial License