diff --git a/README.rst b/README.rst index 3ee4f482..123b9f07 100644 --- a/README.rst +++ b/README.rst @@ -489,6 +489,71 @@ For instance: Refer to the `patch catalog <#template-patch-catalog>`_ below for more details. +Hosting extra static files +~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The MFE plugin allows other plugins to serve extra static files through the MFE service. This enables hosting custom assets (CSS, images, JavaScript, themes, etc.) directly alongside MFE applications, without rebuilding the core MFE image. Assets are exposed via a dedicated volume, so updates can be deployed dynamically via simple pushes to that volume, speeding up tests and updates without full-image builds. + +To enable this functionality, set ``MFE_HOST_EXTRA_FILES`` to ``true``: + +.. code-block:: bash + + tutor config save --set MFE_HOST_EXTRA_FILES=true + +When this setting is enabled, the configured volume patches (explained below) will be applied in all environments so that extra files can be served. In development mode it will additionally expose port ``8002`` on the ``mfe`` service, allowing direct access to those files. In production deployments, port mapping is not required since files are served through Caddy. + +Then add your static files using volume patches. For local deployments, use the ``mfe-volumes`` patch: + +.. code-block:: python + + from tutor import hooks + + hooks.Filters.ENV_PATCHES.add_item( + ( + "mfe-volumes", + """ + - /path/to/static/files:/usr/share/caddy/myfiles:ro + """ + ) + ) + +For Kubernetes deployments, use the ``mfe-k8s-volumes`` patch: + +.. code-block:: python + + hooks.Filters.ENV_PATCHES.add_item( + ( + "mfe-k8s-volumes", + """ + # Add your custom volume definition here. This can be any valid Kubernetes volume type. + - name: myfiles-volume + configMap: + name: myfiles-configmap + ... + """ + ) + ) + +Your static files will be accessible at ``http(s)://{{ MFE_HOST }}/myfiles/``. + +For advanced routing configurations, you can use the ``mfe-caddyfile`` patch to define custom Caddy rules for handling your static files: + +.. code-block:: python + + hooks.Filters.ENV_PATCHES.add_item( + ( + "mfe-caddyfile", + """ + # Custom routing for static files + handle_path /myfiles/* { + root * /usr/share/caddy/myfiles + file_server + } + """ + ) + ) + + Installing from a private npm registry ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -762,6 +827,20 @@ Add any configurations for the mfe-caddyfile. File changed: ``tutormfe/templates/mfe/apps/mfe/Caddyfile`` +mfe-volumes +~~~~~~~~~~~ + +Add volumes to the mfe service in local Docker Compose deployment. + +File changed: ``local/docker-compose.yml`` + +mfe-k8s-volumes +~~~~~~~~~~~~~~~ + +Add volumes to the mfe deployment in Kubernetes. + +File changed: ``k8s/deployments.yml`` + Troubleshooting --------------- diff --git a/changelog.d/20250804_101420_andres.giraldo_tutor_paragon_mfe_integration.md b/changelog.d/20250804_101420_andres.giraldo_tutor_paragon_mfe_integration.md new file mode 100644 index 00000000..921699b8 --- /dev/null +++ b/changelog.d/20250804_101420_andres.giraldo_tutor_paragon_mfe_integration.md @@ -0,0 +1,2 @@ +- [Feature] Add `mfe-volumes` and `mfe-k8s-volumes` patches to enable plugins to serve static files through MFE service. (by @andres.giraldo) +- [Improvement] Ensure MFE container accessibility in dev mode with default port mapping and external file hosting support. (by @andres.giraldo) diff --git a/tutormfe/patches/k8s-deployments b/tutormfe/patches/k8s-deployments index ba34efd4..9cec6fe6 100644 --- a/tutormfe/patches/k8s-deployments +++ b/tutormfe/patches/k8s-deployments @@ -26,3 +26,6 @@ spec: - name: config configMap: name: mfe-caddy-config + {%- if MFE_HOST_EXTRA_FILES %} + {{ patch("mfe-k8s-volumes") | indent(8) }} + {%- endif %} diff --git a/tutormfe/patches/local-docker-compose-dev-services b/tutormfe/patches/local-docker-compose-dev-services index e816824d..352ae1f8 100644 --- a/tutormfe/patches/local-docker-compose-dev-services +++ b/tutormfe/patches/local-docker-compose-dev-services @@ -20,9 +20,12 @@ {%- endfor %} -{% if mfe_data.unmounted|length > 0 %} +{% if mfe_data.unmounted|length > 0 or MFE_HOST_EXTRA_FILES %} mfe: ports: +{%- if MFE_HOST_EXTRA_FILES %} + - 8002:8002 +{%- endif %} {%- for app_name, app in mfe_data.unmounted %} - {{ app["port"] }}:8002 # {{ app_name }} {%- endfor %} diff --git a/tutormfe/patches/local-docker-compose-services b/tutormfe/patches/local-docker-compose-services index 8d21950a..8ec8b7a3 100644 --- a/tutormfe/patches/local-docker-compose-services +++ b/tutormfe/patches/local-docker-compose-services @@ -4,5 +4,8 @@ mfe: restart: unless-stopped volumes: - ../plugins/mfe/apps/mfe/Caddyfile:/etc/caddy/Caddyfile:ro + {% if MFE_HOST_EXTRA_FILES %} + {{ patch("mfe-volumes") | indent(8) }} + {% endif %} depends_on: - lms diff --git a/tutormfe/plugin.py b/tutormfe/plugin.py index 70924799..d339d71b 100644 --- a/tutormfe/plugin.py +++ b/tutormfe/plugin.py @@ -28,6 +28,7 @@ "HOST": "apps.{{ LMS_HOST }}", "COMMON_VERSION": "{{ OPENEDX_COMMON_VERSION }}", "CADDY_DOCKER_IMAGE": "{{ DOCKER_IMAGE_CADDY }}", + "HOST_EXTRA_FILES": False, }, }