Grove is built for managing multiple Open edX instances in a Kubernetes cluster. It uses Tutor for deploying those instances. Therefore Grove needs to support instance-level customization. Here we will talk about those customization features.
Grove Template repository has a
defaults directory, in which we specify a set of default configurations. Whenever Grove creates a new instance, it copies these configuration files to the
defaults directory contains the following files:
config.yml- A default set of configurations for Tutor. Tutor will use this file to deploy instances.
grove.yml- Configuration file used by Grove. More details can be found below.
requirements.txt- Python requirements file for the instance.
Note that content of the
defaults directory is only copied while deploying a new instance via Gitlab Trigger. A "new deployment" means that there is no
instances/<INSTANCE_NAME> directory. Creating a new instance by running the
./control/tutor command locally will not copy the
defaults folder. We need to manually copy the
defaults directory in that case. Run the following command to create a new instance locally:
cp -r ./defaults/ ./instances/<INSTANCE_NAME> && ./control/tutor <INSTANCE_NAME> config save
<INSTANCE_NAME> is the new instance's name.
Grove provides some useful features via
Installing a custom theme¶
By default, Grove installs
edx-simple-theme, which is an easy-to-customize Open edX comprehensive theme. But we are not limited to using it. Grove has the following configuration in
grove.yml to install a custom theme via Tutor.
COMPREHENSIVE_THEME_NAME: The name of the theme. Used as theme name in LMS, CMS, and as the clone folder name. Defaults to
COMPREHENSIVE_THEME_SOURCE_REPO: The Git repository for the theme. Defaults to
COMPREHENSIVE_THEME_VERSION: Branch for the theme. Defaults to
ENABLE_SIMPLE_THEME_SCSS_OVERRIDES: Whether we want to override SCSS variables for the theme. Only works with open-craft/edx-simple-theme.
SIMPLE_THEME_SCSS_OVERRIDES: A list of supported SCSS variable names and their values. Only works with open-craft/edx-simple-theme. Example:
SIMPLE_THEME_SCSS_OVERRIDES: - value: '#0075b4' variable: footer-bg - value: '#6d9cae' variable: footer-bg
SIMPLE_THEME_STATIC_FILES_URLS: A list of static file URLs and their destination path. Each static file is downloaded from the URL and saved in the destination path within
edx-simple-themein the tutor env directory. This is used to override various default static images in the Open edX platform such as favicon, header/footer icons, banner images, etc. Example:
SIMPLE_THEME_STATIC_FILES_URLS: - dest: lms/static/images/logo.png url: <LOGO_URL> - dest: lms/static/images/favicon.ico url: <FAVICON_URL>
Image build configuration¶
Any change in theming, installing XBlock, or custom Django app requires rebuilding the instance image. But we would not want to build all the images (e.g. forum) every time. Grove provides
IMAGE_BUILD_CONFIG to specify which images to rebuild for an instance. It is a map where each key is an image name. For each image name, we need to specify
DOCKER_IMAGE_VAR - the name of the variable Tutor uses to specify image name in the docker registry (in the case of Grove the GitLab container registry).
For example the value of
DOCKER_IMAGE_VAR for the
openedx image is
TUTOR_DOCKER_IMAGE_OPENEDX. For the
ecommerce image, it is
TUTOR_ prefix is added as we are going to set these variables in the build environment.
Instance level customization¶
Once we've created/deployed a new instance we can now freely modify the instance-specific configuration in the
Every instance has it's own separate virtual environment in the
instances/<INSTANCE_NAME>/.venv directory. Any packages listed in the instance's
requirements.txt will be installed here.
There are some helper commands to work with this virtual environment:
grove venv update <INSTANCE_NAME>: Update or create the virtual environment from the instance's requirements.txt
grove venv reset <INSTANCE_NAME>: Rebuild the virtual environment for the instance.
grove venv shell <INSTANCE_NAME>: Starts a Python shell with the virtual environment activated.
Overriding files in Tutor env directory¶
Grove stores the Tutor
env directory of each instance in a separate s3 storage. Since that directory is not tracked by Git, it's hard to maintain any changes that are applied to its items. To solve this issue, Grove provides an easy way to override or add any file to the Tutor
instances/<INSTANCE_NAME>/env-overrides directory for this purpose. Any file kept there will be rendered to the
env directory, thus overriding an existing file that matches its path. To render these files Grove uses Tutor's
For example, to install a custom XBlock we need to put the pip requirement in the
env/build/openedx/requirements/private.txt file. Therefore, we put it in the
env-overrides/build/openedx/requirements/private.txt file and it will be rendered to
env/build/openedx/requirements/private.txt by Grove.
Custom Tutor Plugin¶
If we need to add a tutor plugin:
- Add the package to
./grove venv update <INSTANCE_NAME>to install it to the virtual environment.
- Add it to the
Site configurations can be added for your instance using the
SITE_CONFIG configuration in
This can either be configured directly by modifying the config file or by passing the json using
TUTOR_SITE_CONFIG key with the deployment request. Example:
SITE_CONFIG: homepage_overlay_html: >- <h1> Welcome to the customized instance </h1> <p> This banner is customized using the site configurations </p> static_template_about_content: <p>This is a custom about page</p> version: 0