Notes on installing Open Edx with tutor and customising the theme for legacy pages and MFE. It also covers the setting and auto-updating local development environment.

Open Edx theme customisation.md

Installing Open Edx and theme customisation

These are notes I've made which trying to get a development version working on my local docker install.

Starting up from a new install

Running the first time in development. You have to build the opened-dev image, (see docs)

Make theme visible in dev

The indigo theme is the default when you start up using

tutor local launch/start

But in dev mode the basic Open Edx theme will be used unless you explicit install and enable the theme.

git clone https://github.com/overhangio/tutor-indigo.git
pip install -e ./tutor-indigo
tutor plugins enable indigo
tutor dev start

Each time a change is made to the indigo theme you need to run tutor config save in a separate terminal (while the site is running from the above command). This will rebuild the SCSS.

Subtlties of the theme

The indigo theme will only effect certain pages because Open Edx using Micro-Frontends (MFEs). To alter the styles of these you have to use another repo brand-openedx.

Setup a user and demo content

tutor dev do createuser --staff --superuser <yourusername> <youremail>
tutor dev do importdemocourse

Or you can do this in the local env (which has different DB settings).

tutor local do createuser --staff --superuser <yourusername> <youremail>
tutor local do importdemocourse

Developing the theme via Indigo and Brand Openedx

In production we would build the Brand Openedx repo along with the MFEs. In development this is a slow process (build time ~10 mins). Automatic generation of the files can be achieved by mounting brand-opendex from your local file system into a container. This will bypass node-modules versions.

We need to do this for both brand and the MFE we are working on e.g. learning

e.g.
tutor mounts add learning:/Users/egomez/code/web/openedx/brand-openedx:/openedx/brand-openedx
tutor mounts add learning:/Users/egomez/code/web/openedx/frontend-app-learning:/openedx/app

Now, in your frontend-app-authn folder, add the file name module.config.js and add the below content:

   module.exports = {
    localModules: [
     { moduleName: '@edx/brand', dir: '../brand-openedx'  },
    ],
  };

You will now have to build the frontend part otherwise it will fail with:

tutor_dev-authn-1  | > @edx/[email protected] start
tutor_dev-authn-1  | > fedx-scripts webpack-dev-server --progress --config ./webpack.dev-tutor.config.js
tutor_dev-authn-1  | 
tutor_dev-authn-1  | sh: 1: fedx-scripts: not found

Check that in package.json for your MFE that the brand package is pointing to a local file, or it will download the specified version.

e.g.

  "dependencies": {
    "@edx/brand": "file:brand-openedx",
    ...
  }

This command will build the MFE and make a symlink to the @edx/brand that you have on your local file system. Do not run in the docker container. Run it locally, it will make the link and it will appear in your container.

npm install

Then start tutor dev start and make changes to brand-openedx. Those will reflect automatically.

Useful links

• Tutor docs
• Blog post about enabling Tutor Indigo theme/plugin which applies only to legacy pages (i.e. Django templates)
• Repo for Tutor Indigo plugin
• How to use @edx/brand in local development and production - Discussion
• Micro-Frontend github project with useful README
• List of Open Edx apps and their repos
• Background on brand customisation

Issues I've had when applying this to Authn

I see:

tutor_dev-authn-1  | > @edx/[email protected] start
tutor_dev-authn-1  | > fedx-scripts webpack-dev-server --progress --config ./webpack.dev-tutor.config.js
tutor_dev-authn-1  | 
tutor_dev-authn-1  | Resolving modules from local directories via module.config.js.
tutor_dev-authn-1  | Using local version of @edx/brand from ../brand-openedx/.
tutor_dev-authn-1  | Error: Cannot find module '/openedx/brand-openedx/package.json'
tutor_dev-authn-1  | Require stack:
tutor_dev-authn-1  | - /openedx/app/node_modules/@openedx/frontend-build/config/getLocalAliases.js
tutor_dev-authn-1  | - /openedx/app/node_modules/@openedx/frontend-build/config/webpack.dev.config.js
tutor_dev-authn-1  | - /openedx/app/webpack.dev-tutor.config.js
tutor_dev-authn-1  | - /openedx/app/node_modules/webpack-cli/lib/webpack-cli.js
tutor_dev-authn-1  | - /openedx/app/node_modules/webpack-cli/lib/bootstrap.js
tutor_dev-authn-1  | - /openedx/app/node_modules/webpack-cli/bin/cli.js
tutor_dev-authn-1  | - /openedx/app/node_modules/@openedx/frontend-build/node_modules/webpack-dev-server/bin/webpack-dev-server.js
tutor_dev-authn-1  | - /openedx/app/node_modules/@openedx/frontend-build/bin/fedx-scripts.js
tutor_dev-authn-1  |     at Module._resolveFilename (node:internal/modules/cjs/loader:1134:15)
tutor_dev-authn-1  |     at Module._load (node:internal/modules/cjs/loader:975:27)
tutor_dev-authn-1  |     at Module.require (node:internal/modules/cjs/loader:1225:19)
tutor_dev-authn-1  |     at require (node:internal/modules/helpers:177:18)
tutor_dev-authn-1  |     at /openedx/app/node_modules/@openedx/frontend-build/config/getLocalAliases.js:48:47
tutor_dev-authn-1  |     at Array.forEach (<anonymous>)
tutor_dev-authn-1  |     at getLocalAliases (/openedx/app/node_modules/@openedx/frontend-build/config/getLocalAliases.js:45:18)
tutor_dev-authn-1  |     at Object.<anonymous> (/openedx/app/node_modules/@openedx/frontend-build/config/webpack.dev.config.js:31:17)
tutor_dev-authn-1  |     at Module._compile (node:internal/modules/cjs/loader:1356:14)
tutor_dev-authn-1  |     at Module._extensions..js (node:internal/modules/cjs/loader:1414:10) {
tutor_dev-authn-1  |   code: 'MODULE_NOT_FOUND',
tutor_dev-authn-1  |   requireStack: [
tutor_dev-authn-1  |     '/openedx/app/node_modules/@openedx/frontend-build/config/getLocalAliases.js',
tutor_dev-authn-1  |     '/openedx/app/node_modules/@openedx/frontend-build/config/webpack.dev.config.js',
tutor_dev-authn-1  |     '/openedx/app/webpack.dev-tutor.config.js',
tutor_dev-authn-1  |     '/openedx/app/node_modules/webpack-cli/lib/webpack-cli.js',
tutor_dev-authn-1  |     '/openedx/app/node_modules/webpack-cli/lib/bootstrap.js',
tutor_dev-authn-1  |     '/openedx/app/node_modules/webpack-cli/bin/cli.js',
tutor_dev-authn-1  |     '/openedx/app/node_modules/@openedx/frontend-build/node_modules/webpack-dev-server/bin/webpack-dev-server.js',
tutor_dev-authn-1  |     '/openedx/app/node_modules/@openedx/frontend-build/bin/fedx-scripts.js'
tutor_dev-authn-1  |   ]
tutor_dev-authn-1  | }
tutor_dev-authn-1  | Error in module.config.js parsing. module.config.js will be ignored.
tutor_dev-authn-1  | [webpack-cli] Invalid options object. Dev Server has been initialized using an options object that does not match the API schema.
tutor_dev-authn-1  |  - options.proxy should be an array:
tutor_dev-authn-1  |    [object { … } | function, ...]
tutor_dev-authn-1  |    -> Allows to proxy requests, can be useful when you have a separate API backend development server and you want to send API requests on the same domain.
tutor_dev-authn-1  |    -> Read more at https://webpack.js.org/configuration/dev-server/#devserverproxy