tutor/docs/tutorials/proxy.rst

.. _web_proxy:

Running Open edX behind a web proxy
===================================

In a vanilla deployment of Open edX with Tutor, a web proxy is launched to process incoming web requests. This web proxy is an instance of `Caddy <https://caddyserver.com/>`__ running inside a Docker container. This Docker container listens to ports 80 and 443 on the host.

Quite often, there is already a web proxy running on the host, and this web proxy also listens to ports 80 and 443. In such a configuration, the Caddy container will not be able to start out of the box. So you should make small changes to the Tutor configuration by running::

    tutor config save --set ENABLE_WEB_PROXY=false --set CADDY_HTTP_PORT=81

With these changes, Tutor will no longer listen to ports 80 and 443 on the host. In this configuration, the Caddy container will only listen to port 81 on the host. Web requests will follow this path::

    Client → Web proxy (http(s)://yourhost) → Caddy (0.0.0.0:81) → uwsgi (LMS/CMS/...)

.. warning::
    In this setup, the Caddy HTTP port (81) will be exposed to the world. Make sure to configure your server firewall to block unwanted connections to the Caddy container. Alternatively, you can configure the Caddy container to accept only local connections::

        tutor config save --set ENABLE_WEB_PROXY=false --set CADDY_HTTP_PORT=127.0.0.1:81

It is then your responsibility to configure the web proxy on the host. There are too many use cases and proxy vendors, so Tutor does not provide configuration files that will work for everyone. You should configure your web proxy to:

- Capture traffic for the following hostnames: LMS_HOST, PREVIEW_LMS_HOST, CMS_HOST, as well as any additional host exposed by your plugins (MFE_HOST, ECOMMERCE_HOST, etc.). See each plugin documentation for more information.
- If SSL/TLS is enabled:
    - Perform SSL/TLS termination using your own certificates.
    - Forward http traffic to https.
- Set the following headers appropriately: ``X-Forwarded-Proto``, ``X-Forwarded-Port``.
- Forward all traffic to ``localhost:81`` (or whatever port indicated by CADDY_HTTP_PORT, see above).
- If possible, add support for `HTTP/3 <https://en.wikipedia.org/wiki/HTTP/3>`__, which considerably improves performance for Open edX (see `this comment <https://github.com/overhangio/tutor/issues/845#issuecomment-1566964289>`__).

.. note::
    If you want to run Open edX at ``https://...`` urls (as you probably do in production) it is *crucial* that the ``ENABLE_HTTPS`` flag is set to ``true``. If not, the web services will be configured to run at ``http://...`` URLs, and all sorts of trouble will happen. Therefore, make sure to continue answering ``y`` ("yes") to the quickstart dialogue question "Activate SSL/TLS certificates for HTTPS access?".
docs: reorganize local guides in tutorials There is too much information in each of the local/k8s/dev docs pages. The "guides" that are listed in each one of those pages are moved either to "common tasks" or to a dedicated "tutorials" section. This paves the way for more comprehensive tutorials, where we describe how to run the latest master branches of Open edX. I am well aware that, as they stand, the tutorials are of poor quality and should be rewritten. This is a task for another day/commit. For now, we only move the contents to a separate part of the docs. Also, we should add a "reference" section to the docs, where we add the result of `tutor <subcommand> --help`. 2021-09-16 08:53:52 +00:00			`.. _web_proxy:`

			`Running Open edX behind a web proxy`
			`===================================`

docs: adjust web proxy tutorial 2022-11-29 08:49:32 +00:00			In a vanilla deployment of Open edX with Tutor, a web proxy is launched to process incoming web requests. This web proxy is an instance of `Caddy <https://caddyserver.com/>`__ running inside a Docker container. This Docker container listens to ports 80 and 443 on the host.
docs: reorganize local guides in tutorials There is too much information in each of the local/k8s/dev docs pages. The "guides" that are listed in each one of those pages are moved either to "common tasks" or to a dedicated "tutorials" section. This paves the way for more comprehensive tutorials, where we describe how to run the latest master branches of Open edX. I am well aware that, as they stand, the tutorials are of poor quality and should be rewritten. This is a task for another day/commit. For now, we only move the contents to a separate part of the docs. Also, we should add a "reference" section to the docs, where we add the result of `tutor <subcommand> --help`. 2021-09-16 08:53:52 +00:00
docs: adjust web proxy tutorial 2022-11-29 08:49:32 +00:00			`Quite often, there is already a web proxy running on the host, and this web proxy also listens to ports 80 and 443. In such a configuration, the Caddy container will not be able to start out of the box. So you should make small changes to the Tutor configuration by running::`
docs: reorganize local guides in tutorials There is too much information in each of the local/k8s/dev docs pages. The "guides" that are listed in each one of those pages are moved either to "common tasks" or to a dedicated "tutorials" section. This paves the way for more comprehensive tutorials, where we describe how to run the latest master branches of Open edX. I am well aware that, as they stand, the tutorials are of poor quality and should be rewritten. This is a task for another day/commit. For now, we only move the contents to a separate part of the docs. Also, we should add a "reference" section to the docs, where we add the result of `tutor <subcommand> --help`. 2021-09-16 08:53:52 +00:00
docs: adjust web proxy tutorial 2022-11-29 08:49:32 +00:00			`tutor config save --set ENABLE_WEB_PROXY=false --set CADDY_HTTP_PORT=81`

			`With these changes, Tutor will no longer listen to ports 80 and 443 on the host. In this configuration, the Caddy container will only listen to port 81 on the host. Web requests will follow this path::`

			`Client → Web proxy (http(s)://yourhost) → Caddy (0.0.0.0:81) → uwsgi (LMS/CMS/...)`
docs: reorganize local guides in tutorials There is too much information in each of the local/k8s/dev docs pages. The "guides" that are listed in each one of those pages are moved either to "common tasks" or to a dedicated "tutorials" section. This paves the way for more comprehensive tutorials, where we describe how to run the latest master branches of Open edX. I am well aware that, as they stand, the tutorials are of poor quality and should be rewritten. This is a task for another day/commit. For now, we only move the contents to a separate part of the docs. Also, we should add a "reference" section to the docs, where we add the result of `tutor <subcommand> --help`. 2021-09-16 08:53:52 +00:00
			`.. warning::`
docs: adjust web proxy tutorial 2022-11-29 08:49:32 +00:00			`In this setup, the Caddy HTTP port (81) will be exposed to the world. Make sure to configure your server firewall to block unwanted connections to the Caddy container. Alternatively, you can configure the Caddy container to accept only local connections::`

			`tutor config save --set ENABLE_WEB_PROXY=false --set CADDY_HTTP_PORT=127.0.0.1:81`
docs: reorganize local guides in tutorials There is too much information in each of the local/k8s/dev docs pages. The "guides" that are listed in each one of those pages are moved either to "common tasks" or to a dedicated "tutorials" section. This paves the way for more comprehensive tutorials, where we describe how to run the latest master branches of Open edX. I am well aware that, as they stand, the tutorials are of poor quality and should be rewritten. This is a task for another day/commit. For now, we only move the contents to a separate part of the docs. Also, we should add a "reference" section to the docs, where we add the result of `tutor <subcommand> --help`. 2021-09-16 08:53:52 +00:00
docs: adjust web proxy tutorial 2022-11-29 08:49:32 +00:00			`It is then your responsibility to configure the web proxy on the host. There are too many use cases and proxy vendors, so Tutor does not provide configuration files that will work for everyone. You should configure your web proxy to:`
Added more info to required headers and a pitfall regarding misleading wording in the quickstart dialogue 2022-10-08 08:44:29 +00:00
docs: adjust web proxy tutorial 2022-11-29 08:49:32 +00:00			`- Capture traffic for the following hostnames: LMS_HOST, PREVIEW_LMS_HOST, CMS_HOST, as well as any additional host exposed by your plugins (MFE_HOST, ECOMMERCE_HOST, etc.). See each plugin documentation for more information.`
			`- If SSL/TLS is enabled:`
			`- Perform SSL/TLS termination using your own certificates.`
			`- Forward http traffic to https.`
			- Set the following headers appropriately: ``X-Forwarded-Proto``, ``X-Forwarded-Port``.
			- Forward all traffic to ``localhost:81`` (or whatever port indicated by CADDY_HTTP_PORT, see above).
feat: add support for http/3 It was observed that waiting time was cut in half after http/3 was enabled. Plus, supporting http/3 is super easy :) Close #845 2023-06-23 15:04:58 +00:00			- If possible, add support for `HTTP/3 <https://en.wikipedia.org/wiki/HTTP/3>`__, which considerably improves performance for Open edX (see `this comment <https://github.com/overhangio/tutor/issues/845#issuecomment-1566964289>`__).
Added more info to required headers and a pitfall regarding misleading wording in the quickstart dialogue 2022-10-08 08:44:29 +00:00
			`.. note::`
docs: adjust web proxy tutorial 2022-11-29 08:49:32 +00:00			If you want to run Open edX at ``https://...`` urls (as you probably do in production) it is crucial that the ``ENABLE_HTTPS`` flag is set to ``true``. If not, the web services will be configured to run at ``http://...`` URLs, and all sorts of trouble will happen. Therefore, make sure to continue answering ``y`` ("yes") to the quickstart dialogue question "Activate SSL/TLS certificates for HTTPS access?".