From f2227b12e1370e7036c94e80dc1f402ba92bb2a9 Mon Sep 17 00:00:00 2001 From: Diana Catalina Olarte Date: Tue, 25 Jun 2024 18:10:03 +1000 Subject: [PATCH] docs: include feedback inside readme --- README.md | 228 +++++++++++++++++++++++++++++++++++------------------- 1 file changed, 147 insertions(+), 81 deletions(-) diff --git a/README.md b/README.md index c4b77f4..adbc878 100644 --- a/README.md +++ b/README.md @@ -1,57 +1,60 @@ # Distro plugin for [Tutor](https://docs.tutor.overhang.io) This plugin is a tool to facilitate the customization of an Open edX instance, adding commands and settings to have an easy-to-use -and a ready-to-deploy in local or development. +and a ready-to-deploy in a local or development environment. ## Installation -To install the latest release +To install the latest release, run: ```bash pip install git+https://github.com/eduNEXT/tutor-contrib-edunext-distro ``` -You can install a specific version by adding the tag at the end, e.g, `pip install git+https://github.com/eduNEXT/tutor-contrib-edunext-distro#v.17.0.0` +You can install a specific version by adding the tag at the end, e.g, `@v17.0.0` ## Usage -1. After installing the plugin run: +1. **Enable the plugin**: after installing the plugin, enable it by running: ```bash tutor plugins enable distro ``` -2. Configure Distro. The plugin manages a set of settings that you can add, refer to the following documentation to know the Distro variables: +2. **Configure the Distro plugin**: this plugin adds a new set of settings used to further customize your Open edX installation. Refer to the following documentation to know the Distro variables: - [How to customize distro](./docs/how_to_customize_distro.rst) - [How to add a new package](./docs/how_to_add_new_packages.rst) -:warning: Remember that from version 15, Distro plugin has no default values. +> [!NOTE] +> From version 15, this plugin has no default values. -3. Once you add the configuration, you can access the next commands (use it depending on your use case, more info below). +3. After enabling the plugin, you'll have the following [commands](#commands) available to use: ```bash # Validate the Distro settings are properly set tutor distro syntax-validator + # Validate the repositories for packages are valid tutor distro repository-validator -# Enable the theme(s) defined +# Enable themes tutor distro enable-themes -# Enable the package(s) defined + +# Enable private packages tutor distro enable-private-packages # Run Tutor commands tutor distro run-extra-commands ``` -4. Build the custom docker image running `tutor images build openedx` or `tutor images build openedx-dev`. +4. Launch your customized instance `tutor local launch` or `tutor dev launch`. -5. Launch your customized instance `tutor local launch` or `tutor dev launch`. +### Using a custom edx-platform branch -**Notes:** +If you want to use a custom edx-platform branch alongside the plugin, your branch must be compatible with the plugin's release. Refer to the [How to customize distro](./docs/how_to_customize_distro.rst) document to set up the repository. -- If you want to use a custom edx-platform, you will need to create a branch based on the release, you can see the compatibility table below for reference: +Please see the following table for details on compatibility. | openedx | tutor | | ------- | ----- | @@ -62,22 +65,29 @@ tutor distro run-extra-commands | palm | v16 | | quince | v17 | -- Define the docker images to be used and build it before starting the instance to avoid issues. - -Example: +Then, specify the docker image variables to identify your custom images, like the example: ```yaml DOCKER_IMAGE_OPENEDX: 'docker.io/ednxops/distro-edunext-edxapp:quince' DOCKER_IMAGE_OPENEDX_DEV: 'docker.io/ednxops/distro-edunext-edxapp-dev:quince' ``` +Finally, launch your instance or build a new image to reflect the changes. + +> [!NOTE] +> Check the [Tutor Documentation](https://docs.tutor.edly.io/configuration.html#custom-open-edx-docker-image) for more information on working with custom repositories and images. + # Packages -If you use case does not include variable modifications or private packages you can use `OPENEDX_EXTRA_PIP_REQUIREMENTS`. +A package is used to modify or extend the platform's functionality, this includes plugins and xblocks. + +If you are not adding configuration variables to your packages or installing private packages, you can use +[**OPENEDX_EXTRA_PIP_REQUIREMENTS**](https://docs.tutor.edly.io/configuration.html#installing-extra-xblocks-and-requirements). +instead. ## How to add a new package -In your config.yml you can set any package following this structure: +In your `config.yml` you can include a package by following this structure: ```yaml DISTRO_MY_PACKAGE_NAME_DPKG: @@ -99,30 +109,56 @@ DISTRO_MY_PACKAGE_NAME_DPKG: # won't be installed as editable. ``` -The package's variables will be used on cms and lms settings. +The package's variables will be loaded as LMS and CMS settings. -In the dev environment, your package will be cloned on **/openedx/extra_deps/MY-PLUGIN-NAME** -if you want to edit it you can -[mount a volume](https://docs.tutor.overhang.io/dev.html?highlight=bind#manual-bind-mount-to-any-directory) to that path. +In case you want to make your package +editable, then you can [mount it as a volume](https://docs.tutor.overhang.io/dev.html?highlight=bind#manual-bind-mount-to-any-directory) using that path. ### Private package -In your new package you can set the setting **private** to true, It's mean that this won't be cloned -from a public repository, to make it work you should run the command to clone private packages: +Setting the value **private** to `true` in your package configuration allows you to install a package from +a private repository. For it to work, enable it by running this command: ```bash tutor distro enable-private-packages ``` -- **local**: It will be necessary to build a new image and run the command `tutor local do init && tutor local start` again. -- **dev**: you must run the command `tutor dev do init && tutor dev start` again. +> [!IMPORTANT] +> After adding public or private packages in a **local** environment, you should run: +> +> ```bash +> tutor images build openedx +> tutor local do init +> tutor local start +> ``` +> +> or +> +> ```bash +> tutor local launch +> ``` + +> [!IMPORTANT] +> After adding public or private packages in a **dev** environment, you should run: +> +> ```bash +> tutor images build openedx +> tutor dev do init +> tutor dev start +> ``` +> +> or +> +> ```bash +> tutor dev launch +> ``` # Themes -We use [themes](https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/latest/configuration/changing_appearance/theming/) +We use a [theme](https://edx.readthedocs.io/projects/edx-installing-configuring-and-running/en/latest/configuration/changing_appearance/theming/) for changing the appearance across the Open edX platform. -Declare the path where your themes will be located with `tutor config save --set DISTRO_THEMES_ROOT="your_path"`, we recommend use **/openedx/themes** +Declare the path where your themes will be located with `tutor config save --set DISTRO_THEMES_ROOT="your_path"`, we recommend using **/openedx/themes** When you set the `DISTRO_THEMES_ROOT`, the theme will be in your `/env/build`. @@ -134,70 +170,87 @@ In the previous example, the theme will be in `env/build/openedx/themes` when yo ## How to add a theme -Set the theme(s) to clone: +1. Set a list of themes to clone by adding `DISTRO_THEMES` configuration to your `config.yml` file, each of them should follow the structure: ```yaml DISTRO_THEMES: - - domain: github.com # where the theme is stored - name: my-theme # folder for cloning the repo inside Tutor - path: my-account # used for the URL; for GitHub repositories correspond to the username - protocol: ssh # use ssh for private repos and https for public ones - repo: my-openedx-theme # name of the repository - version: release-compatible # branch to be cloned + - domain: github.com + name: my-theme + path: my-account + protocol: ssh + repo: my-openedx-theme + version: release-compatible ``` -Set theme(s) directory(ies): +Where: + +- **Domain** corresponds to the hosting service where the theme is stored. +- **Name** is the folder where the theme will be located inside Tutor. +- **Path** is used for the URL. For GitHub repositories correspond to the username. +- **Protocol** used for cloning the theme, `ssh` for private repos, and `https` for public ones. +- **Repo** is the name of the remote repository. +- **Version** designates the branch to be cloned. + +2. Set 1 or more theme directories: ```yaml DISTRO_THEME_DIRS: - /openedx/themes/my-openedx-theme ``` -Set themes name(s): +3. Set a list of the theme names that will be enabled in your instance: ```yaml DISTRO_THEMES_NAME: - my-theme ``` -If you have more than 1 theme installed you can use `DISTRO_DEFAULT_SITE_THEME` to set the default one. +> [!TIP] +> If you have more than 1 theme installed, you can use `DISTRO_DEFAULT_SITE_THEME` to set the default one, otherwise, the first one in the list name will be used. -Run the command to clone and enable the theme(s): +4. Run the command to clone and enable the themes: ```bash tutor distro enable-themes ``` -- **local**: you must build a new image to add the new themes and - compile statics and run the command `tutor local do init && tutor local start` again. -- **dev**: you must run the command `tutor dev do init && tutor dev start` again. - - **Since tutor 13.0.0** you should recompile statics in the container, you could run the next command to do it: - ```bash - openedx-assets themes --theme-dirs THEME_DIRS --themes THEME_NAMES - ``` - -# Build a new image - -**Requirements:** You should have enabled the distro plugin, also you should have run the commands `tutor distro enable-themes` and `tutor distro enable-private-packages`. - -1. You should change 2 variables in your config.yml to define the new DOCKER_IMAGE_OPENEDX and DOCKER_IMAGE_OPENEDX_DEV to use. - -2. You should run the next command: - -```bash -export DOCKER_BUILDKIT=1 -tutor images build -a BUILDKIT_INLINE_CACHE=1 --docker-arg="--cache-from" --docker-arg="/:" -a EDX_PLATFORM_REPOSITORY= -a EDX_PLATFORM_VERSION= openedx -``` - -3. That command will create a new image with the tag defined in your DOCKER_IMAGE_OPENEDX, now, you should run the next command: - -```bash -tutor images push openedx -``` - -# Validator Commands - -## Check the git repository URL +> [!IMPORTANT] +> After adding themes in a **local** environment, you should run: +> +> ```bash +> tutor images build openedx +> tutor local do init +> tutor local start +> ``` +> +> or +> +> ```bash +> tutor local launch +> ``` + +> [!IMPORTANT] +> After adding themes in a **dev** environment, you should run: +> +> ```bash +> tutor images build openedx +> tutor dev do init +> tutor dev start +> ``` +> +> or +> +> ```bash +> tutor dev launch +> ``` + +# Commands + +## Validators + +Helpers for ensuring the correct setting definition. + +### Repository validator If you want to make sure that the git repository urls in the config.yml file are valid, run the following command: @@ -205,7 +258,7 @@ If you want to make sure that the git repository urls in the config.yml file are tutor distro repository-validator ``` -The command will check the git URLs of the OPENEDX_EXTRA_PIP_REQUIREMENTS element, for example, git+https://github.com/openedx/DoneXBlock@2.0.1#egg=done-xblock +The command will check the git URLs of the `OPENEDX_EXTRA_PIP_REQUIREMENTS` element, for example, git+https://github.com/openedx/DoneXBlock@2.0.1#egg=done-xblock It will also check all elements that end in DPKG and have the parameter private: false, for example: @@ -224,7 +277,7 @@ DISTRO_EOX_HOOKS_DPKG: version: master ``` -## Check syntax in the configuration file +### Syntax validator If you want to validate the syntax of the config.yml file, run the following command: @@ -241,9 +294,16 @@ The command will check the configuration for: - INSTALL_EXTRA_FILE_REQUIREMENTS - OPENEDX_EXTRA_SETTINGS -# Run tutor extra commands +## Enablers + +Commands for clone and set up themes and private packages in your instance. + +Visit [Themes](#how-to-add-a-theme) and [Packages](#private-package) sections for better understanding. -You can run tutor extra commands by adding them into the **config.yml** in an attribute `DISTRO_EXTRA_COMMANDS` like this: +## Tutor extra commands + +This feature is useful for creating build pipelines or replicating instances with the same Tutor configuration with fewer steps. +You can run different tutor commands at once by adding them into the **config.yml** in the `DISTRO_EXTRA_COMMANDS` attribute, like this: ```yaml DISTRO_EXTRA_COMMANDS: @@ -251,18 +311,22 @@ DISTRO_EXTRA_COMMANDS: - tutor plugins index add https://overhang.io/tutor/main ``` -You can only insert commands enabled by the [Tutor CLI](https://docs.tutor.edly.io/reference/cli/index.html). Once you have added the commands you want to execute, you will need to run the following command: +> [!NOTE] +> You can only insert commands enabled by the [Tutor CLI](https://docs.tutor.edly.io/reference/cli/index.html). + +Once you have added the commands you want to execute, you will need to run the following command: ```bash tutor distro run-extra-commands ``` -# Other Options +# Other configurations available + +Useful for extending the edx-platform configuration. ## How to add custom middleware -You should set the variable **DISTRO_EXTRA_MIDDLEWARES** in your config.yml to add a new -middleware to **settings.MIDDLEWARE** +You should set the variable **DISTRO_EXTRA_MIDDLEWARES** in your config.yml to add a new middleware in `settings.MIDDLEWARE` ```yaml DISTRO_EXTRA_MIDDLEWARES: @@ -280,11 +344,13 @@ INSTALL_EXTRA_FILE_REQUIREMENTS: files: [/edunext/base.txt, /test/test.txt] ``` -It's important that `.txt` files are added in the requirements directory, similar to EXTRA PIP REQUIREMENTS from [Tutor](https://docs.tutor.overhang.io/configuration.html#installing-extra-xblocks-and-requirements). +It's important that `.txt` files are added in the requirements directory, similar to EXTRA PIP REQUIREMENTS from +[Tutor](https://docs.tutor.overhang.io/configuration.html#installing-extra-xblocks-and-requirements). ## How to enable openedx extra settings -You should set the variable **OPENEDX_EXTRA_SETTINGS** in your config.yml file if you need to enable `cms_env`, `lms_env` or `pre_init_lms_task` settings to plugins work as expected. For now, the principal settings should be like this: +You should set the variable **OPENEDX_EXTRA_SETTINGS** in your config.yml file if you need to enable `cms_env`, `lms_env`, or `pre_init_lms_task` settings to make +plugins work as expected. For now, the principal settings should be like this: ```yaml OPENEDX_EXTRA_SETTINGS: @@ -300,9 +366,9 @@ OPENEDX_EXTRA_SETTINGS: ] ``` -The list could grow according to the needs that arise at the time of configuring the plugins. +The list could grow according to the needs that arise at the time of configuring plugins. -:warning: **Note**: Other Options such as `INSTALL_EXTRA_FILE_REQUIREMENTS` and `OPENEDX_EXTRA_SETTINGS` are included in the v15 version, you can use them from this release. +> [!IMPORTANT] > **INSTALL_EXTRA_FILE_REQUIREMENTS** and **OPENEDX_EXTRA_SETTINGS** are included from version 15. # License