How To Add an MFE to a Sandbox

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.

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
```
    - 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
```
repos_to_cmd["mymfe"]="$edx_ansible_cmd mymfe.yml -e 'MYMFE_MFE_VERSION=$2'"
```
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 04 Dec 2020 this is where they go.
```
MYMFE_NGINX_PORT: 80
MYMFE_SSL_NGINX_PORT: 443
MYMFE_MFE_VERSION: $mymfe_version
MYMFE_MFE_ENABLED: $mymfe
MYMFE_SANDBOX_BUILD: True
```
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
```
booleanParam("mymfe",false,"Enable Logistration MFE")
stringParam("mymfe_version","master","The branch of the frontend-app-mymfe repository")
```
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.

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
    --- dependencies: - common - nginx
  2. playbooks/roles/mymfe/tasks/main.yml
    - name: Build My MFE include_role: name: mfe vars: MFE_ENVIRONMENT_EXTRA: '{{ mymfe_env_extra | default(MFE_DEPLOY_ENVIRONMENT_EXTRA) }}'
  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.
    mymfe_env_extra: MY_CONFIG_1: "{{ MYMFE_MYCONFIG_1 }}" MY_CONFIG_2: "{{ MYMFE_MYCONFIG_2 }}"
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
```
- 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: mymfe
      MFE_NAME: mymfe
    - role: splunkforwarder
      when: COMMON_ENABLE_SPLUNKFORWARDER
    - role: newrelic_infrastructure
      when: COMMON_ENABLE_NEWRELIC_INFRASTRUCTURE
```
3. Complete steps 1c-1f as above (no changes)
The change to edx/jenkins-job-dsl is also the same as above
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
```
MYMFE_MYCONFIG_1: 'some value'
MYMFE_MYCONFIG_2: 'some other value'
```