Files
computer-playbook/roles/sys-svc-proxy/templates/vhost
Kevin Veen-Birkenbach aa19a97ed6 CORS/CSP hardening & centralization
- Add reusable Nginx include: roles/sys-svc-proxy/templates/headers/access_control_allow.conf.j2
  (dynamic ACAO/credentials/methods/headers via role vars)
- Set global 'Vary: Origin' in nginx.conf.j2 to prevent cache poisoning
- CSP: allow Simple Icons via connect-src when feature is enabled
- Front proxy: rename vars to lowercase + flush handlers after config deploy
- Desktop: gate & load Simple Icons role; inject brand logos when enabled
- Bluesky + Logout: replace inline CORS with centralized include
- Simpleicons: public CORS (ACAO='*', no credentials), keep GET/OPTIONS, allow headers
- Taiga: adjust canonical domain to taiga.kanban.{{ PRIMARY_DOMAIN }}
- LibreTranslate: remove unused images/versions keys

Fixes: https://open.project.infinito.nexus/projects/cymais/work_packages/342/activity
Discussion: https://chatgpt.com/share/68da5e27-ffd4-800f-91a3-0ef103058d44
2025-09-29 12:23:58 +02:00
..

Nginx vHost Templates: Basic vs. WebSocket (ws_generic)

This directory provides two Nginx server templates for reverse proxying Dockerized applications behind Nginx:

  • basic.conf.j2
  • ws_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
  • 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!
    Use proxy_buffering off; (as in ws_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