Create ansible role that deploys a custom theme


This PR includes an ansible role that creates a new theme on deploy. The theme is based on a skeleton theme downloaded from a repository, and adds custom SASS overrides and custom static files on top.

*JIRA tickets*: none

*Discussions*: to be added

*Dependencies*: None


*Sandbox URL*: None

*Partner information*: None

*Deployment targets*: None that I know of

*Merge deadline*: None

*Testing instructions*:

1. In the vagrant VM, enable comprehensive theming in lms.env.json, with theme directory /edx/var/edxapp/themes
1. In the vagrant VM, enter into /edx/app/edx_ansible/edx_ansible and checkout the branch from this PR
2. As "vagrant" user:
source /edx/app/edx_ansible/venvs/edx_ansible/bin/activate
cd /edx/app/edx_ansible/edx_ansible/playbooks

  1. Here comes the part you'll want to customize (this line is in README.rst too):
    ansible-playbook -i localhost, -c local run_role.yml -e role=simple_theme -e configuration_version=master -e edx_platform_version=master -e EDXAPP_DEFAULT_SITE_THEME=mytheme2 -e '{"SIMPLETHEME_SASS_OVERRIDES": [{"variable": "main-color", "value":"#823456"}, {"variable": "action-primary-bg", "value":"$main-color"}]}' -e EDXAPP_COMPREHENSIVE_THEME_SOURCE_REPO="" -e EDXAPP_COMPREHENSIVE_THEME_VERSION="harvard-dcex" -e edxapp_user=vagrant -e common_web_group=www-data -e SIMPLETHEME_ENABLE_DEPLOY=true -e '{"EDXAPP_COMPREHENSIVE_THEME_DIRS":["/edx/var/edxapp/themes"], "EDXAPP_ENABLE_COMPREHENSIVE_THEMING": true}'
    3. This will create a new theme in the themes directory. It will have the provided values inside. No other theme will be modified.
    4. Add the theme through admin. Do update_assets as usual or restart LMS to compile the theme
    5. You should see the theme with the changes you requested. It will be based on the skeleton theme you provided in `EDXAPP_COMPREHENSIVE_THEME_SOURCE_REPO` and it will have SASS changes on top of that. You can remove the theme and run again with different values.
    6. Try different values, e.g. a new name instead of mytheme2, and don't pass `EDXAPP_COMPREHENSIVE_THEME_SOURCE_REPO`/`…_VERSION`.
    7. If possible, try to do a full deployment by running the edxapp role against an unprovisioned machine, and verify that after provisioning, it runs openedx with the new theme enabled.

*Author notes and concerns*:

1. The main use case is to run as part of edxapp role, i.e. to use it when provisioning a new machine. The instructions above are a workaround to test it independently without having to redeploy each time.
2. I'm using EDXAPP_COMPREHENSIVE_THEME_SOURCE_REPO to download a base theme. These variables were already present in edxapp for exactly this functionality, but were unused yet.


  • [ ] @smarnach

  • [ ] @mtyaka

  • [ ] edX reviewer[s] TBD

In defaults/main.yml you'll find the available values, but you must your new values through ansible values.

Make sure that the following steps are done before merging:

  • [ ] A DevOps team member has approved the PR.

  • [ ] Are you adding any new default values that need to be overridden when this change goes live? If so:

  • [ ] Update the appropriate internal repo (be sure to update for all our environments)

  • [ ] If you are updating a secure value rather than an internal one, file a DEVOPS ticket with details.

  • [ ] Add an entry to the CHANGELOG.

  • [ ] Have you performed the proper testing specified on the [Ops Ansible Testing Checklist](


Muhammad Nadeem Shahzad
January 9, 2018, 2:47 PM

I have build sandbox with PR and tested logo and favicon theme changes, all are looking fine. I have approved and merged PR.



Muhammad Nadeem Shahzad


Open Source Pull Request Bot

Contributor Name

Daniel Clemente Laboreo




Epic Link


OSCM Assignee


Platform Map Area (Levels 1 & 2)


Platform Map Area (Levels 3 & 4)


Blended Hour Utilization Percentage


edX Theme


edX Squad


Github Lines Added


Github Lines Deleted


Story Points