overhangio
Improve Proxy Tutorial Documentation
The proxy tutorial documentation provides the necessary basics. It however doesn't explain which headers need to be set in order for Django to pick up the correct port and protocol information.
Also, based on the built-in template, Caddy doesn't honour the X-Forwarded-Port header, it simply overrides it, either to 80 or 443 depending on the ENABLE_HTTPS flag.
As this flag is controlled by the Quickstart dialogue with a slightly misleading question ("Activate SSL/TLS certificates for HTTPS access?"), I felt it makes sense to add a hint to the docs, as it took me quite some time to figure this out.
The question imho is misleading, as in this case (external proxy handling SSL/TLS) I don't want Caddy to generate certificates for me, but I also don't want it to overwrite the existing header.
Would it be another option to introduce a flag that controls whether Caddy trusts an upstream header?
Hi @waza-ari, thanks for your PR! First of all, I agree that the quickstart phrasing is ambiguous. It is a source of confusion. For instance, too many people just disable HTTPS but attempt (unsuccessfuly) to handle SSL termination via a proxy. For that reason, I think that we should modify the quickstart phrasing. Would you like to do that in this PR?
Second, I think that we could improve the contents of the proxy tutorial. I suggest the following:
- Emphasize the fact that we must keep
ENABLE_HTTPS=true. - Create a dedicated "Proxy configuration" section
- Include a paragraph in this section to explain that some headers need to be set by the proxy.
What do you think?
Hi @regisb, thanks for your feedback!
I agree that its a good idea to adjust the quickstart phrasing. I'll happily look into that and adjust the PR accordingly.
In addition to that I'll try to extend the documentation as suggested. Regarding the additional section, do you envision it tol contain generic information only (e.g. which sites need to be forwarded, which headers should be set) or do you also think it makes sense to include example configurations (for example for Treafik or nginx)?
The reason I'm specifically asking is that the current version of the document states:
As of v11.0.0, configuration files are no longer provided for the automatic configuration of your web proxy
Admittedly I'm not fully aware what has changed in v11 and what was previously provided (considering the "automatic configuration" phrasing), as I'm a relatively new tutor / openedx user. Could you give me your opinion on that before I start writing please?
Regarding the additional section, do you envision it tol contain generic information only (e.g. which sites need to be forwarded, which headers should be set) or do you also think it makes sense to include example configurations (for example for Treafik or nginx)?
I don't think that you should include too specific information. As you noticed, the proxy config templates were removed from the repo because it was too much work to maintain them. General, high level information should be enough.
Closed by the following commits: https://github.com/overhangio/tutor/commit/bb137c16d6bb3f8a60c6859a51663b4234fdda1a https://github.com/overhangio/tutor/commit/4a6896d8920518488a591a357a14b3ae0346ed1c
Thanks for your contribution!