Merge pull request #4052 from open-craft/clemente/ansible-theme

Create ansible role that deploys a custom theme

playbooks/roles/edxapp/tasks/deploy.yml

@@ -87,6 +87,14 @@
     - install
     - install:code
 
+# Download a theme and apply small modifications like SASS changes
+# To enable/disable this, set SIMPLETHEME_ENABLE_DEPLOY
+# https://github.com/ansible/ansible/issues/19472 prevents including the
+# role conditionally
+- name: Install a theme through simpletheme
+  include_role:
+    name: "simple_theme"
+
 - name: Stat each requirements file with Github URLs to ensure it exists
   stat:
     path: "{{ item }}"

playbooks/roles/simple_theme/README.rst

+Simple theme
+############
+
+This role allows you to deploy a basic theme on deploy time. The theme can be
+customized via ansible variables in the following ways:
+- to redefine SASS variables (like colors)
+- to include some static files provided in a local directory (e.g. logo)
+- to download some static files from URLs (e.g. logo, favicon)
+- in addition the theme can be based on an existing theme from a repository
+
+This role will be included by edxapp. The main use case involves deploying a
+theme as part of deploying an instance. The new theme will be enabled when
+the instance starts.
+
+Configuration
+*************
+- The theme name for the deployed theme will be the one specifed in EDXAPP_DEFAULT_SITE_THEME
+- The theme will be deployed to a directory of that name.
+
+You have the option to use a skeleton theme. This is the base theme that will be
+copied to the target machine, and modified afterwards via the customizations
+applied by this role's variables.
+
+Example: if you have a theme in https://github.com/open-craft/edx-theme/tree/harvard-dcex:
+- Set EDXAPP_COMPREHENSIVE_THEME_SOURCE_REPO: "https://github.com/open-craft/edx-theme/"
+- and EDXAPP_COMPREHENSIVE_THEME_VERSION: "harvard-dcex"
+
+If you don't use a skeleton theme, the deployed theme will just contain the SASS
+variables definitions you provide through the other variables, and the static files
+you provide. For simple changes like colors+logo+image this will be enough.
+
+Static files (like logo and favicon) will be added from the following sources and in
+the following order:
+- If no skeleton theme nor static files are provided, the theme will have no static files
+- If a skeleton theme was provided, its static files will be used
+- Local files from SIMPLETHEME_STATIC_FILES_DIR will be copied, replacing previous ones
+- Files from SIMPLETHEME_STATIC_FILES_URLS will be downloaded, replacing previous ones
+
+Testing
+*******
+
+The intended use of this role is to be run as part of deploy, not after it.
+
+There are other cases in which you may want to run the role independently (after
+ the instance is running):
+- When testing this role.
+- If you plan to use it to deploy theme changes. Be aware that this will
+  overwrite the old theme.
+
+You can use ansible-playbook to test this role independently.
+It requires you to pass more variables manually because they're not available
+except when running inside "edxapp" role. For instance you might need to pass
+ edxapp_user (e.g. "vagrant" if you test inside devstack).
+
+Example script to test this role, to be run from devstack, from "vagrant" user:
+- export PYTHONUNBUFFERED=1
+- source /edx/app/edx_ansible/venvs/edx_ansible/bin/activate
+- cd /edx/app/edx_ansible/edx_ansible/playbooks
+- 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="https://github.com/open-craft/edx-theme/" -e EDXAPP_COMPREHENSIVE_THEME_VERSION="harvard-dcex" -e edxapp_user=vagrant -e common_web_group=www-data -e SIMPLETHEME_ENABLE_DEPLOY=true -e '{"SIMPLETHEME_STATIC_FILES_URLS": [{"url": "http://docs.ansible.com/ansible/latest/_static/images/logo_invert.png", "dest":"lms/static/images/logo.png"}, {"url": "http://docs.ansible.com/favicon.ico", "dest":"lms/static/images/favicon.ico"}]}' -e '{"EDXAPP_COMPREHENSIVE_THEME_DIRS":["/edx/var/edxapp/themes"], "EDXAPP_ENABLE_COMPREHENSIVE_THEMING": true}'
+
+
+Or, if you want to test the task as part of the deployment, change to role=edxapp,
+and add  --tags some-custom-tag-that-you-should-add-to-the-task

playbooks/roles/simple_theme/defaults/main.yml

+---
+#
+# edX Configuration
+#
+# github:     https://github.com/edx/configuration
+# wiki:       https://openedx.atlassian.net/wiki/display/OpenOPS
+# code style: https://openedx.atlassian.net/wiki/display/OpenOPS/Ansible+Code+Conventions
+# license:    https://github.com/edx/configuration/blob/master/LICENSE.TXT
+#
+#
+# Simple theme. Creates a basic theme at deploy time.
+#
+# See documentation in README.rst
+
+#
+# This file contains the variables you'll need to pass to the role, and some
+# example values.
+
+
+
+# Skeleton theme. Check README.rst
+# EDXAPP_COMPREHENSIVE_THEME_SOURCE_REPO
+# EDXAPP_COMPREHENSIVE_THEME_VERSION
+
+
+# Enable/disable deploy
+# This flag isn't at the edxapp role because of https://github.com/ansible/ansible/issues/19472
+SIMPLETHEME_ENABLE_DEPLOY: False
+
+
+# This variable holds the main path where the role will copy files.
+# EDXAPP_COMPREHENSIVE_THEME_DIRS.0 can be
+# "/edx/var/edxapp/themes" or
+# "/edx/app/edxapp/themes" or
+# "/edx/app/edxapp/themes/edx-platform"
+# or any other.
+# If you have more than 1 theme dirs, you'll need to override this internal variable
+simpletheme_folder: "{{ EDXAPP_COMPREHENSIVE_THEME_DIRS.0 }}/{{ EDXAPP_DEFAULT_SITE_THEME }}"
+
+
+# Define SASS variables
+# Apart from giving direct values like '#123456', you may give values that use
+# previously defined variables, like '$some-variable', as long as this variable
+# is earlier in the list.
+#
+# Sample configuration:
+# SIMPLETHEME_SASS_OVERRIDES:
+#   - variable: main-color
+#     value: '#123456'
+#   - variable: action-primary-bg
+#     value: '$main-color'
+#   - variable: action-primary-fg
+#     value: '#fff'
+#   - variable: link-color
+#     value: 'red'
+#   - variable: action-secondary-bg
+#     value: '#07f'
+#
+SIMPLETHEME_SASS_OVERRIDES: []
+
+# Files from the specified directory will be copied to the static/ directory.
+# This is mainly designed to include images and JS.
+# Expected file structure is e.g.
+# - lms
+#   - images
+#     - logo.png
+#     - favicon.ico
+#   - js
+#     - myscript.js
+# - cms
+#   - images
+#     - logo.png
+#
+# Paths will be transformed like this:
+# lms/images/logo.png → lms/static/images/logo.png
+# lms/js/myscript.js → lms/static/js/myscript.js
+# etc.
+#
+# Sample:
+# SIMPLETHEME_STATIC_FILES_DIR: "{{ role_path }}/files/example_static_dir"
+SIMPLETHEME_STATIC_FILES_DIR: ""
+
+
+# These files will be downloaded and included in the static directory after the
+# files from SIMPLETHEME_STATIC_FILES_DIR have been copied.
+# Local paths must be relative, e.g. "lms/static/images/favicon.ico"
+# Example which downloads logo and favicon:
+# SIMPLETHEME_STATIC_FILES_URLS:
+#   - url: http://docs.ansible.com/ansible/latest/_static/images/logo_invert.png
+#     dest: lms/static/images/logo.png
+#   - url: http://docs.ansible.com/favicon.ico
+#     dest: lms/static/images/favicon.ico
+SIMPLETHEME_STATIC_FILES_URLS: []
+
+
+# This fragment will be inserted in _lms-overrides and will affect all pages
+# Sample:
+# SIMPLETHEME_EXTRA_SASS: |
+#   .header-global h1.logo a img {
+#     height: 50px;
+#   }
+#   .header-global.slim h2 {
+#     width: 60% !important;
+#   }
+#   .wrapper-footer {
+#     border-top: 3px solid $main-color;
+#   }
+SIMPLETHEME_EXTRA_SASS: ""

playbooks/roles/simple_theme/files/default_skeleton/lms/static/sass/discussion/lms-discussion-main.scss

+@import 'lms/static/sass/discussion/lms-discussion-main';
+@import '../lms-overrides';

playbooks/roles/simple_theme/files/default_skeleton/lms/static/sass/lms-course.scss

+@import 'lms/static/sass/lms-course';
+@import 'lms-overrides';

playbooks/roles/simple_theme/files/default_skeleton/lms/static/sass/lms-main-v1.scss

+@import 'lms/static/sass/lms-main-v1';
+
+@import 'lms-overrides';

playbooks/roles/simple_theme/files/default_skeleton/lms/static/sass/lms-main-v2.scss

+@import 'lms/static/sass/lms-main-v2';
+
+@import 'lms-overrides';

playbooks/roles/simple_theme/files/example_static_dir/lms/js/myscript.js

+// sample script deployed by simple_theme

playbooks/roles/simple_theme/meta/main.yml

+---
+#
+# edX Configuration
+#
+# github:     https://github.com/edx/configuration
+# wiki:       https://openedx.atlassian.net/wiki/display/OpenOPS
+# code style: https://openedx.atlassian.net/wiki/display/OpenOPS/Ansible+Code+Conventions
+# license:    https://github.com/edx/configuration/blob/master/LICENSE.TXT
+#
+
+dependencies: []

playbooks/roles/simple_theme/tasks/deploy.yml

+---
+#
+# edX Configuration
+#
+# github:     https://github.com/edx/configuration
+# wiki:       https://openedx.atlassian.net/wiki/display/OpenOPS
+# code style: https://openedx.atlassian.net/wiki/display/OpenOPS/Ansible+Code+Conventions
+# license:    https://github.com/edx/configuration/blob/master/LICENSE.TXT
+#
+#
+#
+# Simple theme
+#
+# See documentation in README.rst
+
+# Require comprehensive theming
+# EDXAPP_COMPREHENSIVE_THEME_DIRS.0 is usually "/edx/app/edxapp/themes"
+- assert:
+    that:
+      - "EDXAPP_COMPREHENSIVE_THEME_DIRS | length > 0"
+      - "EDXAPP_ENABLE_COMPREHENSIVE_THEMING"
+    msg: "Simple-theme deployment requires comprehensive theming to be enabled"
+
+- assert:
+    that:
+      - "EDXAPP_DEFAULT_SITE_THEME != ''"
+    msg: "Simple-theme needs to know the name of the deployed theme. Pass it in EDXAPP_DEFAULT_SITE_THEME"
+
+
+- name: Check whether theme directory already exists
+  stat: path="{{ simpletheme_folder }}"
+  register: simpletheme_folder_stat
+
+# Note that if a theme already exists in the destination directory, it won't be
+# deleted or redownloaded. It would be better to redownload, but for that we
+# need https://github.com/ansible/ansible-modules-core/issues/5292 to be fixed,
+# or to implement a workaround.
+- block:
+  - name: Download skeleton theme
+    git:
+      repo: "{{ EDXAPP_COMPREHENSIVE_THEME_SOURCE_REPO }}"
+      dest: "{{ simpletheme_folder }}"
+      version: "{{ EDXAPP_COMPREHENSIVE_THEME_VERSION | default('master') }}"
+      # force: yes  # Disabled due to ansible bug, see above
+  # Done in a separate step because "git:" doesn't have owner/group parameters
+  - name: Adjust owner/group of downloaded skeleton theme
+    file:
+      dest: "{{ simpletheme_folder }}"
+      owner: "{{ edxapp_user }}"
+      group: "{{ common_web_group }}"
+      recurse: yes
+  when: EDXAPP_COMPREHENSIVE_THEME_SOURCE_REPO != "" and not simpletheme_folder_stat.stat.exists
+
+# If no skeleton theme, we still need some SASS files to include our SASS partials
+- block:
+  - name: Create default skeleton (dirs)
+    file:
+      path: "{{ simpletheme_folder }}/{{ item.path }}"
+      state: directory
+      owner: "{{ edxapp_user }}"
+      group: "{{ common_web_group }}"
+    with_filetree: "../files/default_skeleton"
+    when: item.state == 'directory'
+  - name: Create default skeleton (files)
+    copy:
+      src: "{{ item.src }}"
+      dest: "{{ simpletheme_folder }}/{{ item.path }}"
+      owner: "{{ edxapp_user }}"
+      group: "{{ common_web_group }}"
+    with_filetree: "../files/default_skeleton"
+    when: item.state != 'directory'
+  when: EDXAPP_COMPREHENSIVE_THEME_SOURCE_REPO == "" and not simpletheme_folder_stat.stat.exists
+
+# These are directories to hold the compiled templates included in this role
+- name: Create directory to hold the theme and styles
+  file:
+    path: "{{ simpletheme_folder }}/{{ item }}"
+    state: directory
+    owner: "{{ edxapp_user }}"
+    group: "{{ common_web_group }}"
+  with_items:
+    - "."
+    - "lms/static/sass/partials/base"
+
+- name: Compile the templates
+  template:
+    src: "{{ item }}.j2"
+    dest: "{{ simpletheme_folder }}/{{ item }}"
+    owner: "{{ edxapp_user }}"
+    group: "{{ common_web_group }}"
+  with_items:
+    # List of files from ./templates to be processed
+    - "lms/static/sass/partials/base/_variables.scss"
+    - "lms/static/sass/_lms-overrides.scss"
+
+
+# Copying static files is done in two steps: create directories + copy files
+# (while renaming their path to add "static/"). There could be a 1-step solution,
+# e.g requesting with_filetree with depth 1 (if this is possible in ansible).
+# Note: with_fileglob doesn't take directories, but with_filetree does.
+
+- block:
+  - name: Create directories for static files to be copied
+    file:
+      path: "{{ simpletheme_folder }}/{{ item.path | regex_replace('^([^/]+)/(.+)$','\\1/static/\\2') }}"
+      state: directory
+      owner: "{{ edxapp_user }}"
+      group: "{{ common_web_group }}"
+    with_filetree: "{{ SIMPLETHEME_STATIC_FILES_DIR }}"
+    when: item.state == 'directory'
+  - name: Copy static files (adding "static/")
+    copy:
+      src: "{{ item.src }}"
+      dest: "{{ simpletheme_folder }}/{{ item.path | regex_replace('^([^/]+)/(.+)$','\\1/static/\\2') }}"
+      owner: "{{ edxapp_user }}"
+      group: "{{ common_web_group }}"
+    with_filetree: "{{ SIMPLETHEME_STATIC_FILES_DIR }}"
+    when: item.state != 'directory'
+  when: SIMPLETHEME_STATIC_FILES_DIR != ""
+
+
+# Downloading remote files is done in two steps: create directorie + download each file.
+# This step is done after the static files from SIMPLETHEME_STATIC_FILES_DIR have been
+# copied, therefore remote files may overwrite the previously installed static files.
+- block:
+  - name: Create directories for static files to be downloaded
+    file:
+      path: "{{ simpletheme_folder }}/{{ item.dest | dirname }}"
+      state: directory
+      owner: "{{ edxapp_user }}"
+      group: "{{ common_web_group }}"
+    with_items: "{{ SIMPLETHEME_STATIC_FILES_URLS }}"
+  - name: Download static files to be included in theme
+    get_url:
+      url: "{{ item.url }}"
+      dest: "{{ simpletheme_folder }}/{{ item.dest }}"
+      force: yes
+      owner: "{{ edxapp_user }}"
+      group: "{{ common_web_group }}"
+    with_items: "{{ SIMPLETHEME_STATIC_FILES_URLS }}"

playbooks/roles/simple_theme/tasks/main.yml

+---
+#
+#
+# Simple theme
+#
+# See documentation in README.rst
+
+# This flag should have been called EDXAPP_SIMPLETHEME_DEPLOY
+# but it would be incompatible with include_role because of
+# https://github.com/ansible/ansible/issues/19472
+# Therefore we use "include" here (instead of "include_role")
+# And because the theme is only needed for the web application, we skip running
+# the role for the Celery workers
+- include: deploy.yml
+  when: SIMPLETHEME_ENABLE_DEPLOY and (celery_worker is not defined or not (celery_worker|bool))
+

playbooks/roles/simple_theme/templates/lms/static/sass/_lms-overrides.scss.j2

+/* Extra SASS as defined by simple_theme starts here: */
+{{ SIMPLETHEME_EXTRA_SASS }}
+/* Extra SASS as defined by simple_theme ends here. */
+

playbooks/roles/simple_theme/templates/lms/static/sass/partials/base/_variables.scss.j2

+@import 'lms/static/sass/partials/base/variables';
+
+/* Variables from simple_theme role start here */
+{% for item in SIMPLETHEME_SASS_OVERRIDES %}
+${{ item.variable }}: {{ item.value }};
+{% endfor %}
+/* Variables from simple_theme role end here */
+