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

docs: improve readme #20

Merged
merged 3 commits into from
Nov 1, 2023
Merged

docs: improve readme #20

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
cddbab5
refactor: adjust readme to be more useful
bra-i-am Oct 11, 2023
ef47baa
fix: improve clarity, structure & sections
bra-i-am Oct 23, 2023
a740e8f
docs: Add more ways of declaring the MFE
bra-i-am Oct 30, 2023
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
99 changes: 62 additions & 37 deletions README.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,65 +5,89 @@ frontend-app-validation-panel

Purpose
***************
The Validation Panel is a micro-frontend (MFE) that empowers course authors to initiate validation processes for the courses they intend to publish on the platform. These processes are routed to validator bodies for a thorough course review, feedback, and determination of approval or disapproval. This MFE offers a user-friendly interface, streamlining the course validation process for both authors and validators.
The Validation Panel is a micro-frontend (MFE) that enables course authors to initiate validation processes for the courses they intend to publish on the platform. These processes are routed to validators for a thorough review, feedback, and determination of approval or disapproval. This MFE offers a user-friendly interface, streamlining the course validation process for both authors and validators.

This application was designed for UNESCO's Open edX instance and depends on the
`Platform Global Teacher Campus Plugin <https://github.com/eduNEXT/platform-global-teacher-campus/tree/main#platform-global-teacher-campus-plugin>`_

Getting Started
***************

Prerequisites
=============

#. It is currently recommended to use `Tutor`_ as the development environment for this MFE. You can refer to the `relevant tutor-mfe documentation`_ for guidance or follow these steps to get started quickly:
The `devstack`_ is currently recommended as a development environment for your
new MFE. If you start it with ``make dev.up.lms`` that should give you
everything you need as a companion to this frontend.

#. Install TVM running
``pip install git+https://github.com/eduNEXT/tvm.git``

#. Initialize a new Tutor project
.. code-block::

tvm project init <project-name> <tutor-version>

# For example:
# tvm project init tvm-test v14.0.0

#. Access the new Tutor project folder with ``cd <project-name>``

#. Initialize the environment with ``source ./.tvm/bin/activate``
Note that it is also possible to use `Tutor`_ to develop an MFE. You can refer
to the `relevant tutor-mfe documentation`_ to get started using it.

#. Run ``tutor dev launch`` to install the necessary initial components

#. Stop the Tutor containers using ``tutor dev stop``

#. Ensure you have installed the `platform-global-teacher-campus <https://github.com/eduNEXT/platform-global-teacher-campus>`_ plugin as per its documentation to have access to the endpoints required by this MFE
Ensure you have installed the `Platform Global Teacher Campus Plugin <https://github.com/eduNEXT/platform-global-teacher-campus/tree/main#platform-global-teacher-campus-plugin>`_ as per its documentation to have access to the endpoints required by this MFE

Developing
============

Cloning and Startup
-------------------
#. Clone this repository inside the new Tutor project:
``git clone git@github.com:openedx/frontend-app-validation-panel.git``
1. Clone this repository to gain access to the project:

.. code-block::

git clone git@github.com:openedx/frontend-app-validation-panel.git

#. Use node v18.x.
The current version of the micro-frontend build scripts support node 18. Using other major versions of node *may* work, but this is unsupported. For convenience, this repository includes an .nvmrc file to help in setting the correct node version via `nvm <https://github.com/nvm-sh/nvm>`_.
2. Make sure are using Node version 18.x, as the micro-frontend build scripts support Node 18. This repository includes an **.nvmrc** file to helpset the correct Node version using `nvm <https://github.com/nvm-sh/nvm>`_.

#. Install npm dependencies:
``cd frontend-app-validation-panel && npm install``
3. Install the dependencies of the Validation Panel project:

.. code-block::

cd frontend-app-validation-panel
npm install

4. Update the application port to access the Validation Panel in development:
* Update the line `PORT` line in your ``.env.development`` file and specify the desired (e.g. `PORT=9999`).

* By default, the app runs on `http://localhost:2001/validation_panel`, overriding the port used by the course-authoring MFE, unless otherwise specified in ``.env.development:PORT`` and ``.env.development:LMS_BASE_URL``.

5. Start the development server:

.. code-block::

npm start

7. Next, enable the Validation Panel micro-frontend in `edx-platform` to make requests, adding the path to the Validation Panel app in `edx-platform`:
* Go to your environment settings (e.g. `edx-platform/lms/envs/private.py`)
* Add the environment variable, ``VALIDATION_PANEL_MICROFRONTEND_URL`` pointing to the Validation Panel App location considering the `PORT` determined in ``.env.development:PORT`` (e.g. ``http://localhost:2001``).

8. Restart the ``edx-platform`` ``lms`` by running the following command:

.. code-block::

make dev.restart-container

Deployment
============
This component follows the standard deploy process for MFEs. For details, see
the `MFE production deployment guide`_

Now, if you prefer to use Tutor, you will need to create an image containing the new MFE. With this in mind, you have to execute the following steps:

#. Create a ``docker-compose.override.yml`` file in the ``env > dev`` directory from the root of your new Tutor project
1. Declare the new MFE adding the following code in your config.yml
dcoa marked this conversation as resolved.
Show resolved Hide resolved

#. Add the following code to the YML file and adjust the path to your local clone of the frontend-app-validation-panel repository:
.. code-block::
.. code-block:: yml

MFE_VALIDATION_PANEL_MFE_APP:
name: validation_panel
port: < any free port >
repository: https://github.com/eduNEXT/frontend-app-validation-panel.git
version: < the wanted git branch or 'master' >

version: '3.7'
services:
course-authoring:
volumes:
- 'path/to/frontend-app-validation-panel:/openedx/app'
2. Apply the new settings with ``tutor config save``

#. Run ``tutor dev start`` and wait the containers to be mounted
3. Create the new image of the MFEs containing this new MFE usign ``tutor images build mfe``

#. After this, any changes you make to your local clone of the Validation Panel repository will be reflected at ``http://apps.local.overhang.io:2001/validation-panel``
4. Start the platform with the image recently created with ``tutor local launch``

License
=======
Expand Down Expand Up @@ -92,3 +116,4 @@ Please see `LICENSE <LICENSE>`_ for details.
.. _Tutor: https://github.com/overhangio/tutor

.. _relevant tutor-mfe documentation: https://github.com/overhangio/tutor-mfe#mfe-development
.. _MFE production deployment guide: https://openedx.github.io/frontend-platform/#production-deployment-strategy