Top to bttom, left to right, Clouflare logo, Open edX logo, Cloudflare tunnel logo, Tutor logo. Background, Argo movie poster from Wikipedia.
The tutor clouflared plugin, is a plugin that integrates Open edX tutor tool, with cloudflared service, so that it allows to run the platform, without the need to have the machine/server http/https 80/443 necessary open the public internet. This is done by utilizing cloudflare tunnel/proxy tool cloudflared1.
This plugin project is also part of a personal initiative, of which the goal is to decrease the cost of running Open edX2. By using this plugin, operators can deploy Open edX on-premises, as such no need for AWS, Azure, or GCP billing. thus reducing the ongoing cost for only the yearly domain registry.
Also, another use case for this plugin can be for Open edX developers to quickly share with a client, project manager or any relevant stakeholder, what have they just developed.
When using this plugin, there would be no need to allow incoming traffic to the machine/server, at the network level it should be possible3
- Owning a domain, cost about ~12 USD per year.
- Have the domain NS server be handled by Cloudflare, set your nameserver to behandled by cloudfalre if your domain is not already on cloudflare.
- Have tutor version >= 16 locally installed. See tutor docs
Install the plugin:
pip install git+https://github.com/ghassanmas/tutor-contrib-cloudflaredThen enable the plugin by:
tutor plugins enable cloudflared
tutor config saveThere are important tutor settings to be set so that https works as expected see tutor proxy doc.
This is beacuse cloudflared in a away or another runs as proxy server
- First change the defualt site port to something other than 80
tutor config save --set CADDY_HTTP_PORT=81 - Change web proxy settings
tutor config save --set ENABLE_WEB_PROXY=false
To utilzie this plugin,
This plugin has a specific command that shall do all the necessary checks:
tutor cloudflared doctor- It checks that user is not using the default tutor host overhang.io
- It checks that all hosts are sharing same root domain
- It checks that the root domain nameserver is handled by Cloudflare, this is essetial to utilize cloudflared tunnel service.
- it checks if LMS_HOST is a subdomain because of cloudflare restricrtion If this is true then tutor by default would assing several hosts as subdomain of subdomain. However subdomain.subdomain.domain.tld can only be used if user is utilziing advance certficate from cloudflare which is not free.
First build the image by tutor images build cloudflared
tutor local do init --limit=cloudflared
Note: It has been taken care of the init script to be Idempotent.
The init command will do the following
- If not logged in yet, It would ask you to login, by printing a spesfic URL, that you need to follow and choose the correct domain you intent to use for running Open edX.
- It would create a tunnel if not exits
- it would iterate over the public hosts (which are set via
CLOUDFLARED_PUBLIC_HOSTSbelow and create dns route for each one.- Note: that each host in
CLOUDFLARED_PUBLIC_HOSTSshould be defined in config.yml, otherwise it would skip it.
- Note: that each host in
tutor cloudflared set-tunnel-uuid
This command would set the UUID of the cloudflared tunnel as a config value, given it would be used for rednering.
That's it, doing the above, should be enough to be able to luach and browse Open edX from anywhere via tutor local luanch or tutor local start
Below are the list of the configuration their default, and how when to change them.
CLOUDFLARED_TUNNEL_NAME- defaults:
openedx - side effect when changed: needs to rerun 1) init, and 2) resetting tunnel uuid.
- defaults:
CLOUDFLARED_TUNNEL_UUID- default: No deafult, it's set by the command
tutor cloudflared set-tunnel-uuiddescribed above.
- default: No deafult, it's set by the command
CLOUDFLARED_PUBLIC_HOSTS- defaults: list
['LMS_HOST', 'CMS_HOST', 'MFE_HOST','DISCOVERY_HOST', 'ECOMMERCE_HOST', 'PREVIEW_LMS_HOST'] - Add a host:
tutor config save --append CLOUDFLARED_PUBLIC_HOSTS=MY_SERVICE_HOST,- Note: Assuming that the value of
MY_SERVICE_HOSTis set, via e.gtutor config save --set MY_SERVICE_HOST=url.
- Note: Assuming that the value of
- Remove a host:
tutor config save --remove CLOUDFLARED_PUBLIC_HOSTS=MY_SERVICE_HOST
- defaults: list
cloudflare has a restriction of it's (proxy/free ssl) featuer that is you need to be on a premium plan so they can cover two level subdomain.4.
When the LMS is not the first level domain, and given 4.1 above, then chances are that (MFE_HOST,PREVIEW_HOST) are no longer a subdomain of the LMS_HOST. If this is the siutation then if would be needed to reset the domain cookie settings, because both origins/domains the MFE and the Preview rely on a cookie that would be set by the LMS. For more info check tutor upstream issue5.
So if you are changing the deafult MFE_HOST, and PREVIEW_HOST then it's important to change the cookie settings SESSION_COOKIE_DOMAIN or set SHARED_COOKIE_DOMAIN to a value of common domain between them, this can be done by creating a tutor file plugins:
nano "$(tutor plugins printroot)"/myplugin.pyOf which it's content
from tutor import hooks
hooks.Filters.ENV_PATCHES.add_item(
("openedx-lms-common-settings",
"""
SHARED_COOKIE_DOMAIN = "{{ LMS_HOST|common_domain(PREVIEW_LMS_HOST) }}"
"""
)
)And then: enable it and save
tutor plugins enable myplugin
tutor config save And finally restart the lms.
The docker image is build because the default cloudflared docker image doesn't work with tutor.
Spefically tutor expects the value of ENTRYPOINT not be set or to take it from docker arg. Which is not the case for cloudflared default image6
This software is licensed under the terms of the AGPLv3.
Footnotes
-
Cloudfalre cloudflared tool, previously know as Argo Tunnel https://www.cloudflare.com/products/tunnel/ git rpeo ↩
-
See Open edX roadmap issue openedx/platform-roadmap/issues/169 ↩
-
Also called Zero trust security model ↩