Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: improve the documentation #210

Merged
merged 8 commits into from
Jul 10, 2024
Merged

docs: improve the documentation #210

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
17ff16e
docs: init improvements in readme
dcoa Jun 11, 2024
abddee3
docs: update usage section in readme
dcoa Jun 12, 2024
9e9e2d3
docs: change ansible for instance
dcoa Jun 12, 2024
5bb0a4f
docs: change edx scope
dcoa Jun 13, 2024
12d075f
docs: reference license file
dcoa Jun 13, 2024
4ba67a9
docs: fix description and style
dcoa Jun 24, 2024
b8c0963
docs: update config description
dcoa Jul 8, 2024
079646e
docs: update USE_EOX_TENANT note
dcoa Jul 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
213 changes: 111 additions & 102 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,106 +1,139 @@
==========
EOX Tenant
==========
|Maintainance Badge| |Test Badge| |PyPI Badge|

EOX tenant
----------
Eox-tenant is a multi-tenancy django app for `edx-platform`_. It is build as an `openedx plugin`_ so even as a django app it will auto install in the larger edx-platform core code once installed in the same python environment.
.. |Maintainance Badge| image:: https://img.shields.io/badge/Status-Maintained-brightgreen
:alt: Maintainance Status
.. |Test Badge| image:: https://img.shields.io/github/actions/workflow/status/edunext/eox-tenant/.github%2Fworkflows%2Ftests.yml?label=Test
:alt: GitHub Actions Workflow Test Status
.. |PyPI Badge| image:: https://img.shields.io/pypi/v/eox-tenant?label=PyPI
:alt: PyPI - Version

Eox-tenant is a plugin for `Open edX`_, and part of the Edunext Open edX Extensions (aka EOX), that replaces the microsites and site_configurations features, offering a more robust multi-tenancy model.

The code is written and maintained by `eduNEXT`_ and it is what we use to support our own multi-tenant services. It was initially created as an extension of the `microsites` and `site_configurations` features of the Open edX platform, but it has grown to completely replace them in order to support more robust multi tenancy model.
If you are looking for professional development or support with multitenancy or multi-sites in the Open edX platform, you can reach out to [email protected]

If you are looking for professional development or support with multi tenancy or multi sites in the Open edX platform, you can reach out at [email protected]
.. _Open edX: https://github.com/openedx/edx-platform/

.. _openedx plugin: https://github.com/edx/edx-platform/tree/master/openedx/core/djangoapps/plugins
.. _edx-platform: https://github.com/edx/edx-platform/
.. _eduNEXT: https://www.edunext.co
Installation
============

#. Add this plugin in your Tutor ``config.yml`` with the ``OPENEDX_EXTRA_PIP_REQUIREMENTS`` setting.

.. code-block:: yaml

OPENEDX_EXTRA_PIP_REQUIREMENTS:
- eox-tenant=={{version}}

#. Save the configuration with ``tutor config save``.
#. Build the image and launch your platform with ``tutor local launch``.

Usage
=====

Once your instance is running, you can access the Django admin site and locate the ``EDUNEXT OPENEDX MULTITENANCY`` models.

- **Microsites:** Store the microsite configuration.
- **Routes:** Configure the URL for a tenant.
- **Tenant configs:** Store the configuration for each tenant.
- **Tenant organizations:** Link each organization with one or multiple tenants.
mariajgrimaldi marked this conversation as resolved.
Show resolved Hide resolved

Add ``EDNX_USE_SIGNAL = True`` in each microsite/tenant that wants to use the plugin.

Compatibility Notes
--------------------

+------------------+-----------------------+
| Open edX Release | Version |
+==================+=======================+
| Ironwood | < 3.0 |
+------------------+-----------------------+
| Juniper | >= 3.0 < 4.0 |
+------------------+-----------------------+
| Koa | >= 4.0 <= 5.1.3 |
+------------------+-----------------------+
| Lilac | >= 4.0 < 6.2 |
+------------------+-----------------------+
| Maple | >= 6.0 |
+------------------+-----------------------+
| Nutmeg | >= 6.2 |
+------------------+-----------------------+
| Olive | >= 8.0 |
+------------------+-----------------------+
| Palm | >= v11.7.0 |
+------------------+-----------------------+
| Quince | >= v11.7.0 |
+------------------+-----------------------+
| Redwood | >= v11.7.0 |
+------------------+-----------------------+

**NOTE**: Since 6.2 version, eox-tenant does not support Django 2.2

The following changes to the plugin settings are necessary. If the release you are looking for is
not listed, then the accumulation of changes from previous releases is enough.

**Ironwood**
+------------------+-----------------+
| Open edX Release | Version |
+==================+=================+
| Ironwood | < 3.0 |
+------------------+-----------------+
| Juniper | >= 3.0 < 4.0 |
+------------------+-----------------+
| Koa | >= 4.0 <= 5.1.3 |
+------------------+-----------------+
| Lilac | >= 4.0 < 6.2 |
+------------------+-----------------+
| Maple | >= 6.0 |
+------------------+-----------------+
| Nutmeg | >= 6.2 |
+------------------+-----------------+
| Olive | >= 8.0 |
+------------------+-----------------+
| Palm | >= v11.7.0 |
+------------------+-----------------+
| Quince | >= v11.7.0 |
+------------------+-----------------+
| Redwood | >= v11.7.0 |
+------------------+-----------------+

⚠️ Since the 6.2 version, eox-tenant does not support Django 2.2

The plugin is configured for the latest release (Redwood). The following changes in the plugin settings should be applied to be used for previous releases.

**Maple**

For version 11.X compatible

.. code-block:: yaml

GET_BRANDING_API: 'eox_tenant.edxapp_wrapper.backends.branding_api_h_v1'
GET_CERTIFICATES_MODULE: 'eox_tenant.edxapp_wrapper.backends.certificates_module_i_v1'
GET_SITE_CONFIGURATION_MODULE: 'eox_tenant.edxapp_wrapper.backends.site_configuration_module_i_v1'
GET_THEMING_HELPERS: 'eox_tenant.edxapp_wrapper.backends.theming_helpers_h_v1'
EOX_TENANT_EDX_AUTH_BACKEND: "eox_tenant.edxapp_wrapper.backends.edx_auth_i_v1"
EOX_TENANT_USERS_BACKEND: 'eox_tenant.edxapp_wrapper.backends.users_i_v1'
EDXMAKO_MODULE_BACKEND: 'eox_tenant.edxapp_wrapper.backends.edxmako_h_v1'
UTILS_MODULE_BACKEND: 'eox_tenant.edxapp_wrapper.backends.util_h_v1'
EOX_TENANT_EDX_AUTH_BACKEND = "eox_tenant.edxapp_wrapper.backends.edx_auth_i_v1"

Those settings can be changed in ``eox_tenant/settings/common.py`` or, for example, in the instance settings.

🚨 If the release you are looking for is not listed, please note:

**Juniper**
- If the Open edX release is compatible with the current eox-tenant version (see `Compatibility Notes <https://github.com/eduNEXT/eox-tenant?tab=readme-ov-file#compatibility-notes>`_), the default configuration is sufficient.
- If incompatible, you can refer to the README from the relevant version tag for configuration details (e.g., `v6.2.0 README <https://github.com/eduNEXT/eox-tenant/blob/v6.2.0/README.rst>`_).

For version >= 3.4
🚨 For version > 10.0.0 you need to enable eox-tenant adding in the LMS configuration:
dcoa marked this conversation as resolved.
Show resolved Hide resolved

.. code-block:: yaml

USE_EOX_TENANT = True

GET_OAUTH_DISPATCH_BACKEND: 'eox_tenant.edxapp_wrapper.backends.oauth_dispatch_j_v1'
Commands
--------

**Koa (optional)**
Synchronize Organizations
^^^^^^^^^^^^^^^^^^^^^^^^^

.. code-block:: yaml
This command will synchronize the course_org_filter values in lms_configs(TenantConfig model) or values(Microsite model) with the TenantOrganization registers if the organization does not exist, it will be created, otherwise, it will be added to the organizations model field.

GET_BRANDING_API: 'eox_tenant.edxapp_wrapper.backends.branding_api_l_v1'
EOX_TENANT_USERS_BACKEND: 'eox_tenant.edxapp_wrapper.backends.users_l_v1'
EDXMAKO_MODULE_BACKEND: eox_tenant.edxapp_wrapper.backends.edxmako_l_v1

**Lilac**
.. code-block:: bash

.. code-block:: yaml
./manage.py lms synchronize_organizations # only for TenantConfig and Microsite
./manage.py lms synchronize_organizations --model TenantConfig # only for TenantConfig
./manage.py lms synchronize_organizations --model Microsite # only for Microsite

GET_BRANDING_API: 'eox_tenant.edxapp_wrapper.backends.branding_api_l_v1'
EOX_TENANT_USERS_BACKEND: 'eox_tenant.edxapp_wrapper.backends.users_l_v1'
EDXMAKO_MODULE_BACKEND: eox_tenant.edxapp_wrapper.backends.edxmako_l_v1
Create/Edit tenant configuration
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

**Maple**
`create_or_update_tenant_config` helps to add or edit ``TenantConfig`` and linked ``Routes`` via command line.

.. code-block:: yaml
.. code-block:: bash

GET_BRANDING_API: 'eox_tenant.edxapp_wrapper.backends.branding_api_l_v1'
EOX_TENANT_USERS_BACKEND: 'eox_tenant.edxapp_wrapper.backends.users_l_v1'
EDXMAKO_MODULE_BACKEND: eox_tenant.edxapp_wrapper.backends.edxmako_l_v1
# This command will create/edit an entry in TenantConfig with external_key lacolhost.com and update its JSONField(s) with passed JSON content.
./manage.py lms create_or_update_tenant_config --external-key lacolhost.com --config '{"lms_configs": {"PLATFORM_NAME": "Lacolhost"}, "studio_configs": {"PLATFORM_NAME": "Lacolhost"}}' lacolhost.com studio.lacolhost.com preview.lacolhost.com

# This command will create/edit an entry in TenantConfig with external_key lacolhost.com and update its JSONField(s) with passed JSON config file content.
./manage.py lms create_or_update_tenant_config --external-key lacolhost.com --config-file /tmp/some.json lacolhost.com studio.lacolhost.com preview.lacolhost.com

Those settings can be changed in ``eox_tenant/settings/common.py`` or, for example, in ansible configurations.
# Same as above, but it will override configuration instead of updating it.
./manage.py lms create_or_update_tenant_config --external-key lacolhost.com --config-file /tmp/some.json lacolhost.com studio.lacolhost.com preview.lacolhost.com --override

**NOTE**: the current ``common.py`` works with Open edX Redwood version.

Migration notes
---------------
===============

**Migrating from 0.* version to 1.0.0**

From version **1.0.0**\ , middlewares **RedirectionsMiddleware** and **PathRedirectionMiddleware** are not longer supported in this plugin.These middlewares were moved to the **eox-core** plugin `here <https://github.com/eduNEXT/eox-core/>`_. From this, you can have three cases:
From version **1.0.0**, **RedirectionsMiddleware** and **PathRedirectionMiddleware** are no longer supported in this plugin. These middleware were moved to the **eox-core** plugin `here <https://github.com/eduNEXT/eox-core/>`_. From this, you can have three cases:


#. You have already installed eox-core alongside eox-tenant. In this case you need to:
#. You have already installed eox-core alongside eox-tenant. In this case, you need to:

* Upgrade eox-core to version **2.0.0** (previous releases are not compatible with eox-tenant 1.0.0)
* Run the plugin migrations as indicated below:
Expand All @@ -111,7 +144,7 @@ From version **1.0.0**\ , middlewares **RedirectionsMiddleware** and **PathRedir
./manage.py lms migrate eox_core --fake-initial --settings=<your app settings>


#. You only have installed eox-tenant and you want to keep the functionality that middlewares offer. You need to:
#. You only have installed eox-tenant and you want to keep the functionality that middleware offer. You need to:

* Install eox-core version **2.0.0** as edx-platform requirement. You can use *Ansible* to add this plugin as an extra requirement.

Expand All @@ -123,57 +156,33 @@ From version **1.0.0**\ , middlewares **RedirectionsMiddleware** and **PathRedir
./manage.py manage.py lms migrate eox_core --fake-initial --settings=<your app settings>


#. In the case your are not using the redirection middlewares, and only have eox-tenant installed, you can simply apply the database migrations for the eox-tenant plugin:
#. In the case you are not using the redirection middleware, and only have eox-tenant installed, you can simply apply the database migrations for the eox-tenant plugin:

.. code-block:: bash

./manage.py manage.py lms migrate eox_tenant --settings=<your app settings>

The table corresponding to the Redirection model will not be deleted but it will be discarded from the Django state

Commands
########

Synchronize Organizations
*************************
This command will synchronize the course_org_filter values in lms_configs(TenantConfig model) or values(Microsite model) with the TenantOrganization registers, if the organization does not exist, it will be created, otherwise it will be add to the organizations model field.


.. code-block:: bash

./manage.py lms synchronize_organizations # only for TenantConfig and Microsite
./manage.py lms synchronize_organizations --model TenantConfig # only for TenantConfig
./manage.py lms synchronize_organizations --model Microsite # only for Microsite

Create/Edit tenant configuration
********************************
`create_or_update_tenant_config` helps to add or edit ``TenantConfig`` and linked ``Routes`` via command line.

.. code-block:: bash

# this command will create/edit entry in TenantConfig with external_key lacolhost.com and update its JSONField(s) with passed json content.
./manage.py lms create_or_update_tenant_config --external-key lacolhost.com --config '{"lms_configs": {"PLATFORM_NAME": "Lacolhost"}, "studio_configs": {"PLATFORM_NAME": "Lacolhost"}}' lacolhost.com studio.lacolhost.com preview.lacolhost.com

# this command will create/edit entry in TenantConfig with external_key lacolhost.com and update its JSONField(s) with passed json config file content.
./manage.py lms create_or_update_tenant_config --external-key lacolhost.com --config-file /tmp/some.json lacolhost.com studio.lacolhost.com preview.lacolhost.com

# Same as above, but it will override configuration instead of updating it.
./manage.py lms create_or_update_tenant_config --external-key lacolhost.com --config-file /tmp/some.json lacolhost.com studio.lacolhost.com preview.lacolhost.com --override

Caveats
-------

- SSO that uses the LMS while authenticating does so with server-to-server communication. Therefore, when the `AvailableScreenMiddleware` gets the current domain, it finds that `lms:8000` as in `SOCIAL_AUTH_EDX_OAUTH2_URL_ROOT` which does not exist, then raises 404 exception. In order to avoid this error, set in your LMS settings file:
- SSO that uses the LMS while authenticating does so with server-to-server communication. Therefore, when the `AvailableScreenMiddleware` gets the current domain, it finds that `lms:8000` as in `SOCIAL_AUTH_EDX_OAUTH2_URL_ROOT` which does not exist, then raises a 404 exception. To avoid this error, set in your LMS settings file:

.. code-block:: python

SOCIAL_AUTH_EDX_OAUTH2_URL_ROOT = SOCIAL_AUTH_EDX_OAUTH2_PUBLIC_URL_ROOT

How to Contribute
-----------------
=================

Contributions are welcome! See our `CONTRIBUTING`_ file for more
information – it also contains guidelines for how to maintain high code
quality, which will make your contribution more likely to be accepted.

.. _CONTRIBUTING: https://github.com/eduNEXT/eox-tenant/blob/master/CONTRIBUTING.rst

License
=======

This project is licensed under the AGPL-3.0 License. See the `LICENSE <LICENSE.txt>`_ file for details.
2 changes: 1 addition & 1 deletion eox_tenant/edxapp_wrapper/backends/branding_api_l_v1.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@

def get_branding_api():
"""Allow to get the branding api module
https://github.com/edx/edx-platform/blob/open-release/lilac.master/lms/djangoapps/branding/api.py
https://github.com/openedx/edx-platform/blob/open-release/lilac.master/lms/djangoapps/branding/api.py

Returns:
branding_api module.
Expand Down
2 changes: 1 addition & 1 deletion eox_tenant/settings/common.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@
def plugin_settings(settings):
"""
Set of plugin settings used by the Open Edx platform.
More info: https://github.com/edx/edx-platform/blob/master/openedx/core/djangoapps/plugins/README.rst
More info: https://github.com/openedx/edx-platform/blob/master/openedx/core/djangoapps/plugins/README.rst
"""
# Plugin settings.
settings.CONTENTSTORE_PATH = 'cms.djangoapps.contentstore.utils'
Expand Down
2 changes: 1 addition & 1 deletion eox_tenant/settings/production.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@
def plugin_settings(settings): # pylint: disable=function-redefined
"""
Set of plugin settings used by the Open Edx platform.
More info: https://github.com/edx/edx-platform/blob/master/openedx/core/djangoapps/plugins/README.rst
More info: https://github.com/openedx/edx-platform/blob/master/openedx/core/djangoapps/plugins/README.rst
"""
# Backend settings.
settings.CONTENTSTORE_PATH = getattr(settings, 'ENV_TOKENS', {}).get(
Expand Down
Loading