Skip to content

Commit

Permalink
docs: include feedback inside readme
Browse files Browse the repository at this point in the history
  • Loading branch information
@dcoa
dcoa committed Jun 25, 2024
1 parent 3ca6dc3 commit b5e8bab
Showing 1 changed file with 147 additions and 81 deletions.
228 changes: 147 additions & 81 deletions README.md
View file
Original file line number Diff line number Diff line change
@@ -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 |
| ------- | ----- |
Expand All @@ -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:
Expand All @@ -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 `<tutor_root>/env/build<distro_themes_root>`.

Expand All @@ -134,78 +170,95 @@ 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="<docker-user>/<docker-repository>:<image-tag>" -a EDX_PLATFORM_REPOSITORY=<your-edx-repo> -a EDX_PLATFORM_VERSION=<branch> 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 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
> ```

# 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:

```bash
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/[email protected]#egg=done-xblock
The command will check the git URLs of the `OPENEDX_EXTRA_PIP_REQUIREMENTS` element, for example, git+https://github.com/openedx/[email protected]#egg=done-xblock

It will also check all elements that end in DPKG and have the parameter private: false, for example:

Expand All @@ -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:

Expand All @@ -241,28 +294,39 @@ 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:
- tutor plugins install mfe && tutor plugins enable mfe
- 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:
Expand All @@ -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:
Expand All @@ -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

Expand Down

0 comments on commit b5e8bab

Please sign in to comment.