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

Jump to bottom

reformat: RST syntax #82

Merged
merged 1 commit into from
Jul 25, 2024
Merged

reformat: RST syntax #82

Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
146 changes: 108 additions & 38 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,42 +1,64 @@
Course Discovery plugin for `Tutor <https://docs.tutor.edly.io>`_
=====================================================================
Course Discovery plugin for `Tutor`_
====================================

This is a plugin for `Tutor <https://docs.tutor.edly.io>`_ that integrates the `Course Discovery <https://github.com/edx/course-discovery/>`__ application in an Open edX platform. it is useful for integration with, for example, `Ecommerce <https://github.com/edx/ecommerce>`__ or an external course catalog.
This is a plugin for `Tutor`_ that integrates the `Course Discovery`_ application in an Open edX platform.
it is useful for integration with, for example, `Ecommerce`_ or an external course catalog.


.. _Tutor: https://docs.tutor.edly.io
.. _Course Discovery: https://github.com/edx/course-discovery/
.. _Ecommerce: https://github.com/edx/ecommerce

Installation
------------

This plugin requires tutor>=3.6.0. If you have installed tutor from a pre-compiled binary, it already comes bundled with the discovery plugin. Otherwise::
This plugin requires ``tutor>=3.6.0``. If you have installed tutor from a pre-compiled binary,
it already comes bundled with the discovery plugin. Otherwise:

.. code-block:: bash


tutor plugins install discovery

Then, to enable this plugin, run::
Then, to enable this plugin, run:

.. code-block:: bash

tutor plugins enable discovery

Restart and initialize your platform with::
Restart and initialize your platform with:

.. code-block:: bash

tutor local launch
tutor dev|local|k8s launch

Operations
----------

Creating a user
~~~~~~~~~~~~~~~

The discovery user interface will be available at http://discovery.local.edly.io for a local test instance, and at ``DISCOVERY_HOST`` (by default: http(s)://discovery.<your lms host>) in production. In order to run commands from the UI, a user must be created::
The discovery user interface will be available at http://discovery.local.edly.io for a local test instance,
and at ``DISCOVERY_HOST`` (by default: http(s)://discovery.<your lms host>) in production. To run
commands from the UI, a user must be created:

.. code-block:: bash

tutor local run discovery ./manage.py createsuperuser

Faraz32123 marked this conversation as resolved.
Show resolved Hide resolved
Then, you must login with this user at http://discovery.local.edly.io/admin.
Then, you must log in with this user at http://discovery.local.edly.io/admin.

Alternatively, you can login with oauth2 using a pre-existing user created on the LMS/CMS by accessing http(s)://discovery.<your lms host>/login. To do so, the proper domain names must exist and point to the production server.
Alternatively, you can log in with oauth2 using a pre-existing user created on the LMS/CMS by accessing
http(s)://discovery.<your lms host>/login. To do so, the proper domain names must exist and point to
the production server.

Index configuration
~~~~~~~~~~~~~~~~~~~

Discovery uses separate indices for different models (the names are: course, course_run, person and program by default). And you can overwrite theses
names by configuring ``DISCOVERY_INDEX_OVERRIDES``::
Discovery uses separate indices for different models (the names are: course, course_run, person, and
program by default). And you can overwrite these names by configuring ``DISCOVERY_INDEX_OVERRIDES``:

.. code-block:: yml

DISCOVERY_INDEX_OVERRIDES:
course_discovery.apps.course_metadata.search_indexes.documents.course: your-course-index-name
Expand All @@ -47,35 +69,50 @@ names by configuring ``DISCOVERY_INDEX_OVERRIDES``::
Re-indexing courses
~~~~~~~~~~~~~~~~~~~

While running tutor in production mode::
While running tutor in production mode:

.. code-block:: bash

tutor local run discovery ./manage.py refresh_course_metadata --partner_code=openedx
tutor local run discovery ./manage.py update_index --disable-change-limit

While running tutor in development mode::
While running tutor in development mode:

.. code-block:: bash

tutor dev run discovery ./manage.py refresh_course_metadata --partner_code=dev
tutor dev run discovery ./manage.py update_index --disable-change-limit

Caching programs
~~~~~~~~~~~~~~~~

In order to cache programs in the LMS, you will need to manually create a catalog integration. Make sure you use staff user for the below command. If ``lms_catalog_service_user`` is not a staff user, then make it a staff user in your LMS User model. This step should be performed just once::
To cache programs in the LMS, you will need to manually create a catalog integration.
Make sure you use staff user for the below command. If ``lms_catalog_service_user`` is not a staff user,
then make it a staff user in your LMS User model. This step should be performed just once:

.. code-block:: bash

tutor local run lms ./manage.py lms create_catalog_integrations --enabled \
--internal_api_url="" \
--service_username=lms_catalog_service_user

Then run the below command, this command will cause errors every time as it tries to cache programs from all sites that are added to your LMS sites model::
Then run the below command, this command will cause errors every time it tries to cache programs
from all sites that are added to your LMS sites model:

.. code-block:: bash

tutor local run lms ./manage.py lms cache_programs

Above command will give some errors as it tries to cache programs for all sites. So make use of an extra argument to the command .i.e. ``--domain``.
While running tutor in production mode::
The above command will give some errors as it tries to cache programs for all sites. So make use of an
extra argument to the command. i.e. ``--domain``. While running tutor in production mode:

.. code-block:: bash

tutor local run lms ./manage.py lms cache_programs --domain="local.edly.io"

While running tutor in development mode::
While running tutor in development mode:

.. code-block:: bash

tutor dev run lms ./manage.py lms cache_programs --domain="local.edly.io:8000"

Expand All @@ -84,12 +121,21 @@ This last step should be performed every time you create new or make changes to
Show Programs Tab
~~~~~~~~~~~~~~~~~

In order to make ``Programs`` tab work in the LMS dashboard, users will need to manually create an entry in ``Programs api config`` model in LMS Admin Panel. Go to http://local.edly.io/admin/programs/programsapiconfig/. Add ``Marketing path`` equal to ``/programs`` and enable it. Then Programs tab will be shown on the LMS where users can view their registered programs. It will show like as in below picture.
To make the ``Programs`` tab work in the LMS dashboard, users will need to manually create an entry
in the ``Programs api config`` model in the LMS Admin Panel. Go to http://local.edly.io/admin/programs/programsapiconfig/.
Add ``Marketing path`` equal to ``/programs`` and enable it. Then Programs tab will be shown on the LMS
where users can view their registered programs. It will show like in the below picture.

.. image:: https://github.com/overhangio/tutor-discovery/assets/122095701/e0224011-adc0-41e4-a104-af4cb0c24b82
:alt: Programs Tab on LMS dashboard

In the above image, User can see explore programs button which is pointing to ``http://localhost:8080/programs`` by default. This link does not exist. So, users can change this link to their custom build marketing site url to show all programs there. This can be done by modifying ``Site Configurations`` model in LMS Admin Panel. Go to http://local.edly.io/admin/site_configuration/siteconfiguration/. Open respective LMS site configuration and add below dict in ``site values`` field like below image::
In the above image, the user can see explore programs button which is pointing to ``http://localhost:8080/programs`` by default.
This link does not exist. So, users can change this link to their custom-built marketing site URL to show all programs there.
This can be done by modifying the ``Site Configurations`` model in the LMS Admin Panel. Go to
http://local.edly.io/admin/site_configuration/siteconfiguration/. Open the respective LMS site configuration and add the below
dictionary in ``site values`` field like the below image:

.. code-block:: python

"MKTG_URLS": {
"ROOT": "https://custom-marketing-site-here.com"
Expand All @@ -101,51 +147,75 @@ In the above image, User can see explore programs button which is pointing to ``
Install extra requirements
~~~~~~~~~~~~~~~~~~~~~~~~~~

In order to install extra requirements, use DISCOVERY_EXTRA_PIP_REQUIREMENTS and re-build the docker image.::
To install extra requirements, use ``DISCOVERY_EXTRA_PIP_REQUIREMENTS`` and re-build the docker image.

.. code-block:: bash

tutor config save \
--set 'DISCOVERY_EXTRA_PIP_REQUIREMENTS=["git+https://github.com/myusername/myplugin"]'
tutor config save --set 'DISCOVERY_EXTRA_PIP_REQUIREMENTS=["git+https://github.com/myusername/myplugin"]'

Then, build the image, pointing to your fork if necessary::
Then, build the image, pointing to your fork if necessary:

.. code-block:: bash

tutor images build discovery

Debugging
---------

To debug the course discovery service, you are encouraged to mount the course-discovery repo from the host in the development container:
To debug the course discovery service, you are encouraged to mount the course-discovery repo from the host
in the development container:

.. code-block:: bash

tutor dev start --mount /path/to/course-discovery/ discovery

You can then access the development server at http://discovery.local.edly.io:8381. Feel free to add breakpoints (``import pdb; pdb.set_trace()``) anywhere in your source code to debug your application.
You can then access the development server at http://discovery.local.edly.io:8381. Feel free to add breakpoints
(``import pdb; pdb.set_trace()``) anywhere in your source code to debug your application.

Once a local repository is mounted in the image, you will have to install nodejs dependencies and collect static assets::
Once a local repository is mounted in the image, you will have to install nodejs dependencies and collect static assets:

.. code-block:: bash

tutor dev run discovery npm install --development
tutor dev run discovery make static.dev

Troubleshooting
---------------

This Tutor plugin is maintained by Muhammad Faraz Maqsood from `Edly <https://edly.io/>`__. Community support is available from the official `Open edX forum <https://discuss.openedx.org>`__. Do you need help with this plugin? See the `troubleshooting <https://docs.tutor.edly.io/troubleshooting.html>`__ section from the Tutor documentation.


`Max retries exceeded with url`
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

When running in production with HTTPS enabled, you may face this error during the `init` phase of `tutor local launch`:

```
requests.exceptions.ConnectionError: HTTPSConnectionPool(host='<LMS_HOST>', port=443): Max retries exceeded with url: /api/courses/v1/courses/?page=1&page_size=10&username=discovery
```
.. code-block:: log

requests.exceptions.ConnectionError: HTTPSConnectionPool(host='<LMS_HOST>', port=443): Max retries exceeded with url: /api/courses/v1/courses/?page=1&page_size=10&username=discovery

This error may be due to an incorrect DNS resolution of the LMS DNS record. With some cloud providers (for instance: [DigitalOcean](https://digitalocean.com/)) the `/etc/hosts` file on the host automatically contains the following entry::
This error may be due to an incorrect DNS resolution of the LMS DNS record. With some cloud providers
(for instance: `DigitalOcean`_) the `/etc/hosts` file on the host automatically
contains the following entry:

.. code-block:: bash

127.0.1.1 <LMS HOST>

This entry may be present if you named your server with the LMS hostname.

.. _DigitalOcean: https://digitalocean.com/

Troubleshooting
---------------

This Tutor plugin is maintained by Muhammad Faraz Maqsood from `Edly`_.
Community support is available from the official `Open edX forum`_.
Do you need help with this plugin? See the `troubleshooting`_
section from the Tutor documentation.

.. _Edly: https://edly.io/
.. _Open edX forum: https://discuss.openedx.org
.. _troubleshooting: https://docs.tutor.edly.io/troubleshooting.html

License
-------

This work is licensed under the terms of the `GNU Affero General Public License (AGPL) <https://github.com/overhangio/tutor/blob/master/LICENSE.txt>`_.
This work is licensed under the terms of the `GNU Affero General Public License (AGPL)`_.

.. _GNU Affero General Public License (AGPL): https://github.com/overhangio/tutor/blob/master/LICENSE.txt
Loading