Skip to content

docs: add Optional Security Headers via Reverse Proxy section to the Caddy HTTPS guide#1286

Merged
Classic298 merged 1 commit into
open-webui:mainfrom
CmdKratosDev:docs/caddy-security-headers
Jun 6, 2026
Merged

docs: add Optional Security Headers via Reverse Proxy section to the Caddy HTTPS guide#1286
Classic298 merged 1 commit into
open-webui:mainfrom
CmdKratosDev:docs/caddy-security-headers

Conversation

@CmdKratosDev
Copy link
Copy Markdown
Contributor

PR: docs: add "Optional: Security Headers via Reverse Proxy" section to the Caddy HTTPS guide

Motivation

The existing Security Headers
documentation covers setting headers at the application layer via environment variables — the
recommended and primary path.

What is currently missing is guidance for operators who run Open WebUI behind a shared reverse proxy
serving multiple applications, or who are on managed hosting without direct docker run / Compose env
var access. These operators may need to set headers at the proxy layer, but caddy.md currently
includes no security-header guidance and no pointer to hardening.md — and, importantly, no warning
about setting headers in both layers at once (which produces duplicate headers).

This PR closes that gap for the Caddy guide with one small, focused, purely additive section. (If it's
useful, the same can follow for the nginx and HAProxy guides — kept separate to keep each change easy
to review.)

What changes

  • docs/reference/https/caddy.md — new section ## Optional: Security Headers via Reverse Proxy,
    inserted after ## Testing HTTPS, before ## Updating Open WebUI.

The section:

  1. Opens with a clear pointer to hardening.md as the recommended primary path (env vars).
  2. Explains the single-layer rule — choose app layer OR proxy layer, not both — and what duplicate
    headers actually do (CSP combined by intersection; HSTS / X-Frame-Options become browser-dependent).
  3. Names the relevant env vars so an operator who already uses them knows to skip the section.
  4. Provides a copy-paste header block for the five unambiguous headers (HSTS, X-Frame-Options,
    X-Content-Type-Options, Referrer-Policy, Permissions-Policy), with an explicit HSTS caveat.
  5. Deliberately leaves CSP to the CONTENT_SECURITY_POLICY env var (it is too deployment-specific to
    ship a generic proxy-layer policy), pointing back to the hardening docs.

Notes

  • The header values match the set documented in hardening.md.
  • The snippet was tested against a default Open WebUI install in a local lab; operators should still
    verify against their own deployment (curl -sI one-liner included in the section).
  • No changes to application logic, environment variable defaults, or hardening.md.
  • No new directives — the header block uses only standard Caddy syntax already consistent with the
    existing config examples in this file.

A docs discussion (#1270) floated this idea; this PR opens the concrete change for easier review.

…y guide

Purely additive section in docs/reference/https/caddy.md for operators who
run Open WebUI behind a shared reverse proxy or managed hosting without
app-layer env-var access. Includes a single-layer-only warning (duplicate
headers), the five unambiguous headers with an HSTS caveat, and a pointer to
the hardening docs; CSP is intentionally left to the CONTENT_SECURITY_POLICY
env var.
@Classic298
Copy link
Copy Markdown
Collaborator

This is excellent, thank you.

@Classic298 Classic298 merged commit c4e655e into open-webui:main Jun 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants