How To Add an MFE to a Sandbox

Owned by Rebecca Graber (Deactivated)
Last updated: Jan 04, 2022 by Justin Lapierre (Deactivated)
4 min read

The MFE role in ansible makes adding any microfrontend (MFE) to edx sandboxes a much more straightforward process than it was previously.

Note: Most of this was reverse-engineered from existing PRs, which were also copied from previous PRs created before the dawn of man. It’s possible there is a more streamlined way, and devs are encouraged to try and find it.

For purposes of this page, we’re assuming you’re adding a service called mymfe . Everywhere you see that, replace it with the real name of your MFE. Note that in order for this to work, the repo for mymfe must be named frontend-app-<mymfe> .

Also note, if your MFE repo contains hyphens in the name, it is convention to convert the hyphens to underscores in the configuration, leaving CLUSTER_NAME assigned the hyphenated name.

E.g. frontend-app-ora-grading would have a CLUSTER_NAME of 'ora-grading' but all the rest of the configuration should be ora_grading as per the instructions below.

MFE with No Special Configurations

This is for an MFE where you will not need to set up any particular environment variables in the MFE itself that are different on the sandbox vs other places.

  1. Update edx/configuration (sample PR, typo in variable name fixed here)

    1. In the edx continuous integration playbook , add a new instance of the mfe role pointing to mymfe , gated on a MYMFE_MFE_ENABLED flag. This ensures mymfe will be installed (but not necessarily deployed) when doing a full_installation_from_scratch , which is the default ami type for sandboxes (NOTE: If your mfe has hyphens in it’s name, such as ora-grading, for this configuration, use the hyphenated name)

      - role: mfe MFE_NAME: mymfe when: MYMFE_MFE_ENABLED

    2. Create a deploy playbook for the app. Basic MFE playbook with splunk and newrelic capability, at playbooks/mymfe.yml:

      - name: Deploy my MFE Frontend hosts: all become: True gather_facts: True vars: ENABLE_NEWRELIC: False CLUSTER_NAME: 'mymfe' MYMFE_ENABLED: True MYMFE_SANDBOX_BUILD: False roles: - role: mfe MFE_NAME: mymfe - role: splunkforwarder when: COMMON_ENABLE_SPLUNKFORWARDER - role: newrelic_infrastructure when: COMMON_ENABLE_NEWRELIC_INFRASTRUCTURE

    3. Set up the flag in the jenkins ansible_provision script to enable the MFE and determine which branch to build. Generally, if no branch (version) is specified, we want to build master.

      if [[ -z $mymfe ]]; then mymfe="false" fi if [[ -z $mymfe_version ]]; then MYMFE_MFE_VERSION="master" fi

    4. Add the new playbook to the edx_ansible role template. This is what makes sure the playbook will get called again if you run the ansible update script on your sandbox.
      Note: it is unclear if this is actually necessary for MFEs

    5. Add “mymfe” to the list of service DNS names in the launch_ec2 role’s “DNS names for services” task. This will CNAME mymfe-<sandboxname>.edx.org to the ec2 instance running the sandbox

    6. Add nginx and version configurations to the jenkins ansible_provision script . This will allow the sandbox to use nginx to serve the mfe when it is enabled. Note these nginx configurations may live somewhere else eventually, but as of Dec 4, 2020 this is where they go.

  2. Update the parameters block in CreateSandbox.groovy in edx/jenkins-job-dsl. This will make the option to toggle your MFE on a sandbox appear in the CreateSandbox job configuration UI. Sample PR here

  3. Update sandbox-internal. Sample PRs for lms here, ecommerce here, and learning MFE here. This is where you will update/add any variables needed by backend services to allow them to communicate with your MFE.

    1. In the examples above, the ecommerce service needed to add the payment MFE to it’s CORS whitelist, allow CORS to use credentials, and get the MFE url (always https://mymfe-deploy_host).

MFE with Special Configurations

This is for MFEs with environment variables that need to be configured differently for sandboxes vs other environments. For example, you may have new features behind a feature flag that should be visible on sandboxes but not prod. The MFE role takes care of pointing the mfe to the sandbox versions of lms and ecommerce so if those are the only env variables you need to set you will not need this.

  1. Update edx/configuration (sample PR) - note the PR has some extra changes to fix bugs in the payment mfe setup. Ignore those.

    1. Create a new role that extends the ‘mfe’ role:

      1. playbooks/roles/mymfe/meta/main.yml

      2. playbooks/roles/mymfe/tasks/main.yml

      3. playbooks/roles/mymfe/defaults/main.yml - this is where you will establish which specific configuration vars you will be overriding. You only need to include those that are specific to your mfe, things like the LMS url and ECOMMERCE url are already set by the mfe role.

    2. Create a deploy playbook for the app. Note that everything here is the same as in the non-configurable version except the roles. Sample basic playbook at playbooks/mymfe.yml

    3. Complete steps 1c-1f as above (no changes)

  2. The change to edx/jenkins-job-dsl is also the same as above

  3. Update sandbox-internal/ansible/vars/developer-sandbox.yml. This is where you will include the actual values you need for your special configurations. Note you’ll need to prefix all of them with MYMFE_ so they can be pulled in properly