Installation

This section covers the one-time setup required to connect your Open edX site to Branding by Aulasneo. Once completed, you will not need to repeat these steps unless your deployment configuration changes.

Step 1: Install the Tutor Branding Plugin 

In your Tutor root directory, within the Python virtual environment used for Tutor, run:

pip install tutor-contrib-branding

Then enable the plugin:

tutor plugins enable branding

Verify the installation with:

tutor plugins list

The branding plugin should appear in the list as enabled.

Step 2: Rebuild the MFE Image (Recommended)

Rebuilding the MFE image is not strictly mandatory, but it is strongly recommended to enable the theme variant switch that appears at the bottom of every MFE page. This switch allows users (and administrators) to toggle between light, dark, and any other configured variants, or to set automatic mode based on the operating system preference.

tutor images build mfe

Note

This step can take several minutes depending on your build environment. Ensure your internet connection is stable and that you have sufficient disk space for the build.

Step 3: Restart the MFE Service 

After rebuilding the image, restart the MFE container to apply the new image:

tutor local restart mfe

For Kubernetes deployments, use:

tutor k8s restart mfe

Step 4: Create and Build Your Theme 

Follow the instructions in Quick Start to create your first CSS theme, logo set, and build. When the build is complete, you will find a Copy Tutor Command button in the build list.

Step 5: Apply the Tutor Command 

Click Copy Tutor Command in the Branding by Aulasneo interface, then paste the command in your Tutor virtual environment:

tutor config save --set BRANDING_PARAGON_THEME_URLS='...' \
  --set BRANDING_MFE_LOGO_URL='...' \
  # ... (full command as copied from the interface)

Step 6: Save Configuration and Restart Services 

Save the Tutor configuration and restart the relevant services:

tutor config save
tutor local restart lms cms

Important

You do not need to rebuild the Open edX or MFE Docker images after applying the Tutor command. The theme files are served from the Branding by Aulasneo server and injected by the MFE at runtime.

After Services Restart 

Once services have restarted, perform a hard refresh (Ctrl+Shift+R on most browsers, or Cmd+Shift+R on macOS) on your Open edX site to force the browser to load the new CSS. Browsers cache CSS aggressively; a normal refresh may not reflect your changes.

When You Need to Re-Run the Tutor Command 

After initial setup, you only need to re-run the Tutor command in the following situations:

You are adding a logo set for the first time.
You are adding a white logo, trademark logo, or favicon for the first time (adding assets not previously included in the build).
You are adding or replacing any font file.
You are adding a new theme variant.
You are creating a new build (new build IDs generate new asset URLs).

You do not need to re-run the Tutor command for the following changes, which take effect after a hard browser refresh:

Changing colors, spacing, or other properties in the core theme.
Modifying an existing theme variant.
Replacing an existing logo or image with another.
Changing the typography settings in the theme.

Back to Home