diff --git a/CHANGELOG.md b/CHANGELOG.md index b040e44901..5852ed3393 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -8,6 +8,8 @@ Versioning](https://semver.org/spec/v2.0.0.html). ## [Unrealeased] +## [2.25.0] + ### Added - Add ready-only user profile in the learner dashboard preferences page. @@ -2037,7 +2039,8 @@ us: - finish integrating the missing pages and improve the sandbox environment; - test and polish the use of richie as a django app / node dependency. -[unreleased]: https://github.com/openfun/richie/compare/v2.25.0-beta.1...master +[unreleased]: https://github.com/openfun/richie/compare/v2.25.0...master +[2.25.0]: https://github.com/openfun/richie/compare/v2.25.0-beta.1...v2.25.0 [2.25.0-beta.1]: https://github.com/openfun/richie/compare/v2.25.0-beta.0...v2.25.0-beta.1 [2.25.0-beta.0]: https://github.com/openfun/richie/compare/v2.24.1...v2.25.0-beta.0 [2.24.1]: https://github.com/openfun/richie/compare/v2.24.0...v2.24.1 diff --git a/cookiecutter/{{cookiecutter.organization}}-richie-site-factory/template/{{cookiecutter.site}}/requirements/base.txt b/cookiecutter/{{cookiecutter.organization}}-richie-site-factory/template/{{cookiecutter.site}}/requirements/base.txt index 57ed28b60f..b76642d765 100644 --- a/cookiecutter/{{cookiecutter.organization}}-richie-site-factory/template/{{cookiecutter.site}}/requirements/base.txt +++ b/cookiecutter/{{cookiecutter.organization}}-richie-site-factory/template/{{cookiecutter.site}}/requirements/base.txt @@ -5,6 +5,6 @@ django-storages==1.13.2 dockerflow==2022.8.0 gunicorn==21.2.0 psycopg2-binary==2.9.9 -richie==2.25.0-beta.1 +richie==2.25.0 unidecode==1.3.6 # required by django-check-seo sentry-sdk==1.39.1 diff --git a/cookiecutter/{{cookiecutter.organization}}-richie-site-factory/template/{{cookiecutter.site}}/src/frontend/package.json b/cookiecutter/{{cookiecutter.organization}}-richie-site-factory/template/{{cookiecutter.site}}/src/frontend/package.json index 8e929c71ae..37c9ca163e 100644 --- a/cookiecutter/{{cookiecutter.organization}}-richie-site-factory/template/{{cookiecutter.site}}/src/frontend/package.json +++ b/cookiecutter/{{cookiecutter.organization}}-richie-site-factory/template/{{cookiecutter.site}}/src/frontend/package.json @@ -21,7 +21,7 @@ "CMS" ], "dependencies": { - "richie-education": "2.25.0-beta.1" + "richie-education": "2.25.0" }, "devDependencies": { "@formatjs/cli": "6.2.4", diff --git a/docs/cookiecutter.md b/docs/cookiecutter.md index 26ddfe0e48..06a297e28b 100644 --- a/docs/cookiecutter.md +++ b/docs/cookiecutter.md @@ -25,7 +25,7 @@ If you chose to install Cookiecutter, you can now run it against our [template][2] as follows: ```bash -cookiecutter gh:openfun/richie --directory cookiecutter --checkout v2.25.0-beta.1 +cookiecutter gh:openfun/richie --directory cookiecutter --checkout v2.25.0 ``` If you didn't want to install it on your machine, we provide a Docker image @@ -33,7 +33,7 @@ built with our [own repository][4] that you can use as follows: ```bash docker run --rm -it -u $(id -u):$(id -g) -v $PWD:/app \ -fundocker/cookiecutter gh:openfun/richie --directory cookiecutter --checkout v2.25.0-beta.1 +fundocker/cookiecutter gh:openfun/richie --directory cookiecutter --checkout v2.25.0 ``` The `--directory` option is to indicate that our Cookiecutter template is in diff --git a/src/frontend/package.json b/src/frontend/package.json index 1984f878a6..7e1a882049 100644 --- a/src/frontend/package.json +++ b/src/frontend/package.json @@ -1,6 +1,6 @@ { "name": "richie-education", - "version": "2.25.0-beta.1", + "version": "2.25.0", "description": "A CMS to build learning portals for Open Education", "main": "sandbox/manage.py", "scripts": { diff --git a/tests_e2e/package.json b/tests_e2e/package.json index 673a95883d..cb932b9643 100644 --- a/tests_e2e/package.json +++ b/tests_e2e/package.json @@ -1,6 +1,6 @@ { "name": "richie-tests-e2e", - "version": "2.25.0-beta.1", + "version": "2.25.0", "description": "End-to-end tests for the Richie project", "repository": "https://github.com/openfun/richie", "author": "Open FUN (France Université Numérique)", diff --git a/website/package.json b/website/package.json index ba1e0ddf3b..7f66f4ba50 100644 --- a/website/package.json +++ b/website/package.json @@ -1,6 +1,6 @@ { "name": "richie-education-docs", - "version": "2.25.0-beta.1", + "version": "2.25.0", "description": "Documentation website for the Richie project", "scripts": { "build": "docusaurus build", diff --git a/website/versioned_docs/version-2.25.0/accessibility-testing.md b/website/versioned_docs/version-2.25.0/accessibility-testing.md new file mode 100644 index 0000000000..6b0eedcc72 --- /dev/null +++ b/website/versioned_docs/version-2.25.0/accessibility-testing.md @@ -0,0 +1,46 @@ +--- +id: accessibility-testing +title: Automated accessibility checks +sidebar_label: Accessibility testing +--- + +Richie includes automated accessibility checks built through a `Cypress` end-to-end testing infrastructure. + +Automated accessibility checks can only surface around 30% of possible problems on any given page. This does not mean they are not useful, but they cannot replace human audits and developer proficiency. + +We use `axe` to run these checks. You can find more about axe on the [`axe-core` GitHub repository](https://github.com/dequelabs/axe-core). + +## Testing environment setup + +Both `Cypress` and `axe` are used through their respective NPM packages. This means everything goes through `yarn` commands. You need to have `node` and `yarn` installed locally to run the tests. + +```bash +cd tests_e2e +yarn install +``` + +This should install everything you need. + +## Running the tests + +There are two ways to use the `Cypress` tests: through a terminal-based runner and through the `Cypress` UI. Both are started through `yarn` but they have different use cases. + +```bash +yarn cypress run +``` + +You can start by running the tests directly from the terminal. This is the quickest way to make sure all views pass checks (or find out which ones do not). This is also the starting point for work on running `Cypress` in the CI. + +```bash +yarn cypress open +``` + +This command simply opens the `Cypress` UI. From there, you can run all or some of the test suites with live reloading. This is a great way to understand why some tests are failing, especially when it comes to a11y violations. + +When there are a11y violations, an assertion fails and prints out a list in the `Cypress` UI. You can then click on a violation to print more information in the browser console. + +## Documentation reference + +- [List of all possible violations covered by `axe`](https://dequeuniversity.com/rules/axe/3.4) +- [`Cypress` documentation](https://docs.cypress.io) +- [`axe` and `Cypress` integration](https://github.com/avanslaars/cypress-axe) diff --git a/website/versioned_docs/version-2.25.0/api/course-run-synchronization-api.md b/website/versioned_docs/version-2.25.0/api/course-run-synchronization-api.md new file mode 100644 index 0000000000..eae4f07e43 --- /dev/null +++ b/website/versioned_docs/version-2.25.0/api/course-run-synchronization-api.md @@ -0,0 +1,56 @@ +--- +id: course-run-synchronization-api +title: Course run synchronization API +sidebar_label: course run sync +--- + +API endpoint allowing remote systems to synchronize their course runs with a Richie instance. + +## Synchronization endpoint [/api/1.0/course-runs-sync] + +This documentation describes version "1.0" of this API endpoint. + +### Synchronize a course run [POST] + +It takes a JSON object containing the course run details: + +- resource_link: `https://lms.example.com/courses/course-v1:001+001+001/info` (string, required) - + url of the course syllabus on the LMS from which a unique course identifier can be extracted +- start: `2018-02-01T06:00:00Z` (string, optional) - ISO 8601 date, when this session of the + course starts +- end: `2018-02-28T06:00:00Z` (string, optional) - ISO 8601 date, when this session of the course + ends +- enrollment_start: `2018-01-01T06:00:00Z` (string, optional) - ISO 8601 date, when enrollment + for this session of the course starts +- enrollment_end: `2018-01-31T06:00:00Z` (string, optional) - ISO 8601 date, when enrollment for + this session of the course ends +- languages: ['fr', 'en'] (array[string], required) - ISO 639-1 code (2 letters) for the course's + languages + + ++ Request (application/json) + + Headers + + Authorization: `SIG-HMAC-SHA256 xxxxxxx` (string, required) - Authorization header + containing the digest of the utf-8 encoded json representation of the submitted data + for the given secret key and SHA256 digest algorithm (see [synchronizing-course-runs] + for an example). + + Body + ```json + { + "resource_link": "https://lms.example.com/courses/course-v1:001+001+001/info", + "start": "2021-02-01T00:00:00Z", + "end": "2021-02-31T23:59:59Z", + "enrollment_start": "2021-01-01T00:00:00Z", + "enrollment_end": "2021-01-31T23:59:59Z", + "languages": ["en", "fr"] + } + ``` + ++ Response 200 (application/json) + + + Body + ```json + { + "success": True + } + ``` diff --git a/website/versioned_docs/version-2.25.0/assets/images/crowdin-join-richie.gif b/website/versioned_docs/version-2.25.0/assets/images/crowdin-join-richie.gif new file mode 100644 index 0000000000..dc7aa84464 Binary files /dev/null and b/website/versioned_docs/version-2.25.0/assets/images/crowdin-join-richie.gif differ diff --git a/website/versioned_docs/version-2.25.0/assets/images/demo-screenshot.jpg b/website/versioned_docs/version-2.25.0/assets/images/demo-screenshot.jpg new file mode 100644 index 0000000000..5ce932ca8a Binary files /dev/null and b/website/versioned_docs/version-2.25.0/assets/images/demo-screenshot.jpg differ diff --git a/website/versioned_docs/version-2.25.0/building-the-frontend.md b/website/versioned_docs/version-2.25.0/building-the-frontend.md new file mode 100644 index 0000000000..ac099791e3 --- /dev/null +++ b/website/versioned_docs/version-2.25.0/building-the-frontend.md @@ -0,0 +1,81 @@ +--- +id: building-the-frontend +title: Building Richie's frontend in your own project +sidebar_label: Building the frontend +--- + +Richie offers plenty of opportunities to customize the way it works and make it suit the needs of your own project. Most of these go through Django settings. + +Part of Richie is a React frontend however. If you want to change how it works in ways that cannot be changed from the Django settings, you will need to build your own frontend. + +## Installing `richie-education` + +If you have not already, you should create a directory for the frontend in your project. We recommend you mirror Richie's file structure so it's easier to keep track of the changes you make. + +```bash +mkdir -p src/frontend +``` + +Then, you need to bootstrap your own frontend project in this new directory. + +```bash +cd src/frontend +yarn init +``` + +With each version of Richie, we build and publish an `NPM` package to enable Richie users to build their own Javascript and CSS. You're now ready to install it. + +```bash +yarn add richie-education +``` + +In your `package.json` file, you should see it in the list of dependencies. Also, there's a `node_modules` directory where the package and its dependencies are actually installed. + +```json +"dependencies": { + "richie-education": "1.12.0" +}, +``` + +## Building the Javascript bundle + +You are now ready to run your own frontend build. We'll just be using webpack directly. + +```bash +yarn webpack --config node_modules/richie-education/webpack.config.js --output-path ./build --richie-dependent-build +``` + +Here is everything that is happening: + +- `yarn webpack` — run the webpack CLI; +- `--config node_modules/richie-education/webpack.config.js` — point webpack to `richie-education`'s webpack config file; +- `--output-path ./build` — make sure we get our output where we need it to be; +- `--richie-dependent-build` — enable some affordances with import paths. We pre-configured Richie's webpack to be able to run it from a dependent project. + +You can now run your build to change frontend settings or override frontend components with your own. + +## Building the CSS + +If you want to change styles in Richie, or add new styles for components & templates you develop yourself, you can run the SASS/CSS build yourself. + +Start by creating your own `main` file. The `_` underscore at the beginning is there to prevent sass from auto-compiling the file. + +```bash +mkdir -p src/frontend/scss +touch src/frontend/scss/_mains.scss +``` + +Start by importing Richie's main scss file. If you prefer, you can also directly import any files you want to include — in effect re-doing Richie's `_main.scss` on your own. + +```sass +@import "richie-education/scss/main"; +``` + +You are now ready to run the CSS build: + +``` +cd src/frontend +yarn build-sass +``` + +This gives you one output CSS file that you can put in the static files directory of your project and use to override Richie's style or add your own parts. diff --git a/website/versioned_docs/version-2.25.0/contributing.md b/website/versioned_docs/version-2.25.0/contributing.md new file mode 100644 index 0000000000..ad7f1a5375 --- /dev/null +++ b/website/versioned_docs/version-2.25.0/contributing.md @@ -0,0 +1,65 @@ +--- +id: contributing-guide +title: Contributing guide +sidebar_label: Contributing guide +--- + +This project is intended to be community-driven, so please, do not hesitate to get in touch if you have any question related to our implementation or design decisions. + +We try to raise our code quality standards and expect contributors to follow the recommandations +from our [handbook](https://openfun.gitbooks.io/handbook/content). + +## Checking your code + +We use strict flake8, pylint, isort and black linters to check the validity of our backend code: + + $ make lint-back + +We use strict eslint and prettier to check the validity of our frontend code: + + $ make lint-front + +## Running tests + +On the backend, we use pytest to run our test suite: + + $ make test-back + +On the frontend, we use karma to run our test suite: + + $ make test-front + +## Running migrations + +The first time you start the project with `make bootstrap`, the `db` container automatically +creates a fresh database named `richie` and performs database migrations. Each time a new +**database migration** is added to the code, you can synchronize the database schema by running: + + $ make migrate + +## Handling new dependencies + +Each time you add new front-end or back-end dependencies, you will need to rebuild the +application. We recommend to use: + + $ make bootstrap + +## Going further + +To see all available commands, run: + + $ make + +We also provide shortcuts for docker compose commands as sugar scripts in the +`bin/` directory: + +``` +bin +├── exec +├── pylint +├── pytest +└── run +``` + +More details and tips & tricks can be found in our [development with Docker +documentation](docker-development.md) diff --git a/website/versioned_docs/version-2.25.0/cookiecutter.md b/website/versioned_docs/version-2.25.0/cookiecutter.md new file mode 100644 index 0000000000..06a297e28b --- /dev/null +++ b/website/versioned_docs/version-2.25.0/cookiecutter.md @@ -0,0 +1,123 @@ +--- +id: cookiecutter +title: Start your own site +sidebar_label: Start your own site +--- + +We use [Cookiecutter](https://github.com/audreyr/cookiecutter) to help you +set up a production-ready learning portal website based on +[Richie](https://github.com/openfun/richie) in seconds. + +## Run Cookiecutter + +There are 2 options to run Cookiecutter: +- [install it on your machine][1] +- run it with Docker + +While you think of it, navigate to the directory in which you want to create +your site factory: + +``` +cd /path/to/your/code/directory +``` + +If you chose to install Cookiecutter, you can now run it against our +[template][2] as follows: + +```bash +cookiecutter gh:openfun/richie --directory cookiecutter --checkout v2.25.0 +``` + +If you didn't want to install it on your machine, we provide a Docker image +built with our [own repository][4] that you can use as follows: + +```bash +docker run --rm -it -u $(id -u):$(id -g) -v $PWD:/app \ +fundocker/cookiecutter gh:openfun/richie --directory cookiecutter --checkout v2.25.0 +``` + +The `--directory` option is to indicate that our Cookiecutter template is in +a `cookiecutter` directory inside our git repository and not at the root. + +You will be prompted to enter an organization name, which will determine the +name of your repository. For example, if you choose "foo" as organization +name, your repository will be named `foo-richie-site-factory`. It's +nice if you keep it that way so all richie site factories follow this +convention. + +When you confirm the organization name, Cookiecutter will generate your +project from the Cookiecutter template and place it at the level where you +currently are. + +### Bootstrap your project + +Enter the newly created project and add a new site to your site factory: + +```bash +cd foo-richie-site-factory +make add-site +``` + +This script also uses Cookiecutter against our [site template][3]. + +Once your new site is created, activate it: + +```bash +bin/activate +``` + +Now bootstrap the site to build its docker image, create its media folder, +database, etc.: + +```bash +make bootstrap +``` + +Once the bootstrap phase is finished, you should be able to view the site at +[localhost:8070](http://localhost:8070). + +You can create a full fledge demo to test your site by running: + +```bash +make demo-site +``` + +Note that the README of your newly created site factory contains detailed +information about how to configure and run a site. + +Once you're happy with your site, don't forget to backup your work e.g. by +committing it and pushing it to a new git repository. + +## Theming + +You probably want to change the default theme. The cookiecutter adds an extra scss frontend folder with a couple of templates that you can use to change the default styling of the site. +* `sites//src/frontend/scss/extras/colors/_palette.scss` +* `sites//src/frontend/scss/extras/colors/_theme.scss` + +To change the default logo of the site, you need to create the folder `sites//src/backend/base/static/richie/images` and then override the new `logo.png` picture. + +For more advanced customization, refer to our recipes: + +* [How to customize search filters](filters-customization.md) +* [How to override frontend components in Richie](frontend-overrides.md) + +## Update your Richie site factory + +If we later improve our scripts, you will be able to update your own site +factory by replaying Cookiecutter. This will override your files in the +project's scaffolding but, don't worry, it will respect all the sites you +will have created in the `sites` directory: + +``` +cookiecutter --overwrite-if-exists gh:openfun/richie --directory=cookiecutter +``` + +## Help us improve this project + +After starting your project, please submit an issue let us know how it went and +what other features we should add to make it better. + +[1]: https://cookiecutter.readthedocs.io/en/latest/installation.html +[2]: https://github.com/openfun/richie/tree/master/cookiecutter +[3]: https://github.com/openfun/richie/tree/master/cookiecutter/{{cookiecutter.organization}}-richie-site-factory/template +[4]: https://github.com/openfun/dockerfiles diff --git a/website/versioned_docs/version-2.25.0/css-guidelines.md b/website/versioned_docs/version-2.25.0/css-guidelines.md new file mode 100644 index 0000000000..eb51e8b672 --- /dev/null +++ b/website/versioned_docs/version-2.25.0/css-guidelines.md @@ -0,0 +1,45 @@ +--- +id: css-guidelines +title: CSS Guidelines +sidebar_label: CSS Guidelines +--- + +The purpose of these CSS guidelines is to make our CSS as easy as possible to maintain, prune and/or modify over time. To that end, they forgo some of the unwanted parts of CSS. They also require the use of a CSS preprocessor (we picked SASS) to be used effortlessly. + +Our approach is two-pronged. First, we put every piece of CSS as close as we can to the place it is used in a template or component. Second, we use strict class naming rules that act as a replacement to CSS selector combinations. + +## File structuration + +Rules should be placed where their purpose is most apparent, and where they are easiest to find. + +Generally, this means CSS rules should live as close as possible to the place they are used. For example, the selectors and rules that define the look for a component should live in a `.scss` file in the same folder as the JS file for this component. This goes for templates too. Such files can only contain rules that are __specific to this component/template and this one only__ + +Only general base rules, utility rules, site layout rules as well as our custom variables should live in the central `app/static/scss` folder. + +## Code structuration + +In order to understand what classes are about at a glance and avoid collisions, naming conventions must be enforced for classes. + +Following the [BEM naming convention](http://getbem.com/introduction/), we will write our classes as follows : + + .block {} + .block__element {} + .block--modifier {} + +- `.block` represents the higher level of an abstraction or component. +- `.block__element` represents a descendent of .block that helps form .block as a whole. +- `.block--modifier` represents a different state or version of .block. + +We use double hyphens and double underscores as delimiters so that names themselves can be hyphen-delimited (e.g. `.site-search__field--full`). + +Yes, this notation is ugly. However, it allows our classes to express what they are doing. Both our CSS and our markup become more meaningful. It allows us to easily see what classes are related to others, and how they are related, when we look at the markup. + +## Quick pointers + +- In general, __do not use IDs__. _They can cause specificity wars and are not supposed to be reusable, and are therefore not very useful._ +- Do not nest selectors unnecessarily. _It will increase specificity and affect where else you can use your styles._ +- Do not qualify selectors unnecessarily. _It will impact the number of different elements you can apply styles to._ +- Comment profusely, _whenever you think the CSS is getting complex or it would not be easy to understand its intent._ +- Use !important proactively. _!important is a very useful tool when used proactively to make a state or a very specific rule on a tightly-scoped selector stronger. It is however to be avoided at all costs as an easy solution to specificity issues, reactively._ + +(Direct) child selectors can sometimes be useful. Please remember that the key selector to determine performance is the rightmost one. i.e. `div > #example` is A LOT more efficient than `#example > div` although it may appear otherwise at first glance. Browsers parse multi part selectors from the right. See [CSS Wizardry](http://csswizardry.com/2011/09/writing-efficient-css-selectors/) for more details. diff --git a/website/versioned_docs/version-2.25.0/discover.md b/website/versioned_docs/version-2.25.0/discover.md new file mode 100644 index 0000000000..08d9d09adb --- /dev/null +++ b/website/versioned_docs/version-2.25.0/discover.md @@ -0,0 +1,60 @@ +--- +id: discover +title: Discover Richie +sidebar_label: Discover Richie +--- + +`Learning Management Systems` (LMS) are great tools for hosting and playing interactive online +courses and MOOCs. + +However, if you need to build a complete website with flexible content to aggregate your courses, +in several languages and from different sources, **you will soon need a CMS**. + +At "France Université Numérique", we wanted to build an OpenSource portal with `Python` and +`Django`. That's why we built `Richie` on top of [DjangoCMS](https://www.django-cms.org), one of +the best CMS on the market, as a toolbox to easily create full fledged websites with a catalog of +online courses. + +![screenshot of richie demo site](assets/images/demo-screenshot.jpg) + +Among the features that `Richie` offers out of the box: + +- multi-lingual by default, +- advanced access rights and moderation, +- catalog of courses synchronized with one or more `LMS` instances, +- search engine based on `Elasticsearch` and pre-configured to offer full-text queries, + multi-facetting, auto-complete,... +- flexible custom pages for courses, organizations, categories, teachers, blog posts, + programs (and their inter-relations), +- Extensible with any third-party `DjangoCMS` plugin or any third-party `Django` application. + +## Quick preview + +If you're looking for a quick preview of `Richie`, you can take a look and have a tour of +`Richie` on our dedicated [demo site](https://demo.richie.education). + +It is connected back-to-back with a demo of OpenEdX running on +[OpenEdX Docker](https://github.com/openfun/openedx-docker). + +Two users are available for testing: + +- admin: `admin@example.com`/`admin` +- student: `edx@example.com`/`edx` + +The database is regularly flushed. + +## Start your own site + +The next step after discovering Richie on the demo is to start your own project. We provide a +production-ready template based on [Cookiecutter](https://github.com/audreyr/cookiecutter) that +allows you to generate your project in seconds. + +Follow the guide on [starting your own Richie site with Cookiecutter](./cookiecutter.md). + +Once you created a new site, you will be able to fully customize it: + +- override any Django template or portion of template, +- [override ReactJS components](./frontend-overrides.md), +- override some css rules or rebuild the whole css with your own variables and customizations, +- add any [DjangoCMS](https://www.django-cms.org) plugin or feature, +- add any [Django third-party application](https://djangopackages.org). diff --git a/website/versioned_docs/version-2.25.0/displaying-connection-status.md b/website/versioned_docs/version-2.25.0/displaying-connection-status.md new file mode 100644 index 0000000000..bcf0a9ec36 --- /dev/null +++ b/website/versioned_docs/version-2.25.0/displaying-connection-status.md @@ -0,0 +1,127 @@ +--- +id: displaying-connection-status +title: Displaying OpenEdX connection status in Richie +sidebar_label: Displaying connection status +--- + +This guide explains how to configure Richie and OpenEdX to share the OpenEdX connection status +and display profile information for the logged-in user in Richie. + +In Richie, the only users that are actually authenticated on the DjangoCMS instance producing the +site, are editors and staff users. Your instructors and learners will not have user accounts on +Richie, but authentication is delegated to a remote service that can be OpenEdX, KeyCloack, or +your own centralized identity management service. + +In the following, we will explain how to use OpenEdX as your authentication delegation service. + +## Prerequisites + +Richie will need to make CORS requests to the OpenEdX instance. As a consequence, you need to +activate CORS requests on your OpenEdX instance: + +```python +FEATURES = { + ... + "ENABLE_CORS_HEADERS": True, +} +``` + +Then, make sure the following settings are set as follows on your OpenEdX instance: + +```python +CORS_ALLOW_CREDENTIALS = True +CORS_ALLOW_INSECURE = False +CORS_ORIGIN_ALLOW_ALL = False +CORS_ORIGIN_WHITELIST: ["richie.example.com"] # The domain on which Richie is hosted +``` + +## Allow redirects + +When Richie sends the user to the OpenEdX instance for authentication, and wants OpenEdX to +redirect the user back to Richie after a successful login or signup, it prefixes the path with +`/richie`. Adding the following rule to your Nginx server (or equivalent) and replacing the +richie host by yours will allow this redirect to follow through to your Richie instance: + +``` +rewrite ^/richie/(.*)$ https://richie.example.com/$1 permanent; +``` + +## Configure authentication delegation + +Now, on your Richie instance, you need to configure the service to which Richie will delegate +authentication using the `RICHIE_AUTHENTICATION_DELEGATION` setting: + +```python +RICHIE_AUTHENTICATION_DELEGATION = { + "BASE_URL": "https://lms.example.com", + "BACKEND": "openedx-hawthorn", + "PROFILE_URLS": { + "dashboard": { + "label": _("Dashboard"), + "href": "{base_url:s}/dashboard", + }, + }, +} +``` + +The following should help you understand how to configure this setting: + +### BASE_URL + +The base url on which the OpenEdX instance is hosted. This is used to construct the complete url +of the login/signup pages to which the frontend application will send the user for authentication. + +- Type: string +- Required: Yes +- Value: for example https://lms.example.com + + +### BACKEND + +The name of the ReactJS backend to use for the targeted LMS. + +- Type: string +- Required: Yes +- Value: Richie ships with the following Javascript backends: + + `openedx-dogwood`: backend for OpenEdX versions equal to `dogwood` or `eucalyptus` + + `openedx-hawthorn`: backend for OpenEdX versions equal to `hawthorn` or higher + + `openedx-fonzie`: backend for OpenEdX via [Fonzie](https://github.com/openfun/fonzie) + (extra user info and JWT tokens) + + `base`: fake backend for development purposes + + +### PROFILE_URLS + +Mapping definition of custom links presented to the logged-in user as a dropdown menu when he/she +clicks on his/her username in Richie's page header. + +Links order will be respected to build the dropdown menu. + +- Type: dictionary +- Required: No +- Value: For example, to emulate the links proposed in OpenEdX, you can configure this setting + as follows: + + ```python + { + "dashboard": { + "label": _("Dashboard"), + "href": "{base_url:s}/dashboard", + }, + "profile": { + "label": _("Profile"), + "href": "{base_url:s}/u/(username)", + }, + "account": { + "label": _("Account"), + "href": "{base_url:s}/account/settings", + } + } + ``` + + The `base_url` variable is used as a Python format parameter and will be replaced by the value + set for the above authentication delegation `BASE_URL` setting. + + If you need to bind user data into a url, wrap the property between brackets. For example, the + link configured above for the profile page `{base_url:s}/u/(username)` would point to + `https://lms.example.com/u/johndoe` for a user carrying the username `johndoe`. diff --git a/website/versioned_docs/version-2.25.0/django-react-interop.md b/website/versioned_docs/version-2.25.0/django-react-interop.md new file mode 100644 index 0000000000..8eac2352a0 --- /dev/null +++ b/website/versioned_docs/version-2.25.0/django-react-interop.md @@ -0,0 +1,119 @@ +--- +id: django-react-interop +title: Connecting React components with Django +sidebar_label: Django & React +--- + +`richie` is a hybrid app, that relies on both HTML pages generated by the backend (Django/DjangoCMS) based on templates, and React components rendered on the frontend for parts of these HTML pages. + +## Rendering components + +We needed a convention that enables us to easily mark those areas of the page that React needs to take control of, and to tell React which component to load there. + +We decided to use a specific CSS class name along with its modifiers. We reserve the `richie-react` class and its modified children for this purpose. + +Additionally, components including internationalized data or strings need to know which locale to use. They will pick up the locale specified through the `lang` attribute of the `` element, which is a requirement to have an accessible page anyway. + +They use the BCP47/RFC5646 format. + +```html + +``` + +### Example + +Here is how we would call a `` component from a template, a plugin or a snippet: + +```html +
+``` + +When our JS is loaded, it will recognize this as an element it must take over, and render the FeaturedCourses component in this element. + +## Passing properties to components + +Some of Richie's React components, and some of those you might want to write, require arguments or "props" to be passed to them. We could work around that by adding API routes to fetch these props, but that would add complexity and reduce performance. + +Instead, we decided to normalize a simpler way for components in Richie to accept input from the Django template that is adding them to the DOM. + +We can add a `data-props` attribute on the element with the `richie-react` class and write a JSON object as the value for this attribute. Each key-value pair in this object will be passed as a `propName={propValue}` to the React component. + +### Example + +Here is how we would pass a `categories={[ "sociology", "anthropology" ]}` prop to our `` component: + +```html +
+``` + +When the component is rendered, it will be passed a `categories` prop with the relevant categories. + +## Built-in components + +Here are the React component that Richie comes with and uses out of the box. + +### <RootSearchSuggestField /> + +Renders a course search bar, like the one that appears in the default `Search` page. + +Interactions will send the user to the `courseSearchPageUrl` url passed in the props, including the selected filter and/or search terms. + +It also autocompletes user input with course names and allows users to go directly to the course page if they select a course name among the selected results. + +Props: + +- `courseSearchPageUrl` [required] — URL for the course search page users should be sent to when they select a suggestion that is not a course, or launch a search with text terms. +- `context` [required] — see [context](#context). + +### <Search /> + +Renders the full-page course search engine interface, including the search results, and filters pane, but not the suggest field (which can be added separately with ``) nor the page title. + +NB: the `Search` Django template basically renders just this page. If you need this, use it instead. It is included here for completeness' sake. + +Props: + +- `context` [required] — see [context](#context). + +### <SearchSuggestField /> + +Renders the course search bar that interacts directly with ``. + +It automatically communicates with `` through browser history APIs and a shared React provider. This one, unlike ``, is meant to be used in combination with `` (on the same page). + +Props: + +- `context` [required] — see [context](#context). + +### <UserLogin /> + +Renders a component that uses the `/users/whoami` endpoint to determine if the user is logged in and show them the appropriate interface: Signup/Login buttons or their name along with a Logout button. + +Props: + +- `loginUrl` [required] — the URL where the user is sent when they click on "Log in"; +- `logoutUrl` [required] — a link that logs the user out and redirects them (can be the standard django logout URL); +- `signupUrl` [required] — the URL where the user is sent when they click on "Sign up". + +## Context + +All built-in components for Richie accept a `context` prop, that may be required or optional, depending on the component. + +It is used to pass app-wide contextual information pertaining to the current instance, deployment or theme of Richie. + +Here is the expected shape for this object: + +```js + { + assets: { + // SVG sprite used throughout Richie + icons: "/path/to/icons/sprite.svg" + } + } +``` +Note that it might be expanded in further versions of Richie. diff --git a/website/versioned_docs/version-2.25.0/docker-development.md b/website/versioned_docs/version-2.25.0/docker-development.md new file mode 100644 index 0000000000..450d043a79 --- /dev/null +++ b/website/versioned_docs/version-2.25.0/docker-development.md @@ -0,0 +1,124 @@ +--- +id: docker-development +title: Developing Richie with Docker +sidebar_label: Docker development +--- + +Now that you have `Richie` up and running, you can start working with it. + +## Settings + +Settings are defined using [Django +Configurations](https://django-configurations.readthedocs.io/en/stable/) for +different environments: + +- `Development`: settings for development on developers' local environment, +- `Test`: settings used to run our test suite, +- `ContinousIntegration`: settings used on the continuous integration platform, +- `Feature`: settings for deployment of each developers' feature branches, +- `Staging`: settings for deployment to the staging environment, +- `PreProduction`: settings for deployment to the pre-production environment, +- `Production`: settings for deployment to the production environment. + +The `Development` environment is defined as the default environment. + +## Front-end tools + +If you intend to work on the front-end development of the CMS, we also have +sweet candies for you! 🤓 + +```bash +# Start the Sass watcher +$ make watch-sass + +# In a new terminal or session, start the TypeScript watcher +$ make watch-ts +``` + +## Container control + +You can stop/start/restart a container: + + $ docker compose [stop|start|restart] [app|postgresql|mysql|elasticsearch] + +or stop/start/restart all containers in one command: + + $ docker compose [stop|start|restart] + +## Debugging + +You can easily see the latest logs for a container: + + $ docker compose logs [app|postgresql|mysql|elasticsearch] + +Or follow the stream of logs: + + $ docker compose logs --follow [app|postgresql|mysql|elasticsearch] + +If you need to debug a running container, you can open a Linux shell with the +`docker compose exec` command (we use a sugar script here, see next section): + + $ bin/exec [app|postgresql|mysql|elasticsearch] bash + +While developing on `Richie`, you will also need to run a `Django shell` and it +has to be done in the `app` container (we use a sugar script here, see next +section): + + $ bin/run app python sandbox/manage.py shell + +## Using sugar scripts + +While developing using Docker, you will fall into permission issues if you mount +the code directory as a volume in the container. Indeed, the Docker engine will, +by default, run the containers using the `root` user. Any file created or +updated by the app container on your host, as a result of the volume mounts, +will be owned by the local root user. One way to solve this is to use the +`--user="$(id -u)"` flag when calling the `docker compose run` or +`docker compose exec` commands. By using the user flag trick, the running +container user ID will match your local user ID. But, as it's repetitive and +error-prone, we provide shortcuts that we call our "sugar scripts": + +- `bin/run`: is a shortcut for `docker compose run --rm --user="$(id -u)"` +- `bin/exec`: is a shortcut for `docker compose exec --user="$(id -u)"` +- `bin/pylint`: runs `pylint` in the `app` service using the test docker compose + file +- `bin/pytest`: runs `pytest` in the `app` service using the test docker compose + file + +## Cleanup + +If you work on the Docker configuration and make repeated modifications, +remember to periodically clean the unused docker images and containers by +running: + + $ docker image prune + $ docker container prune + +## Troubleshooting + +### ElasticSearch service is always down + +If your `elasticsearch` container fails at booting, checkout the logs via: + +```bash +$ docker compose logs elasticsearch +``` + +You may see entries similar to: + +``` +[1]: max virtual memory areas vm.max_map_count [65530] is too low, increase to at least [262144] +``` + +In this case, increase virtual memory as follows (UNIX systems): + +``` +$ sudo sysctl -w vm/max_map_count=262144 +``` + +This fix will apply to your current session. To make it permanent on your system, edit the +`/etc/sysctl.conf` file and add the following line: + +``` +vm.max_map_count=262144 +``` diff --git a/website/versioned_docs/version-2.25.0/filters-customization.md b/website/versioned_docs/version-2.25.0/filters-customization.md new file mode 100644 index 0000000000..0ec9408189 --- /dev/null +++ b/website/versioned_docs/version-2.25.0/filters-customization.md @@ -0,0 +1,198 @@ +--- +id: filters-customization +title: Customizing search filters +sidebar_label: Search filters customization +--- + +You may want to customize the filters on the left side bar of the search page. + +Richie makes it easy to choose which filters you want to display among the existing filters +and in which order. You can also configure the existing filters to change their title or the +way they behave. Lastly, you can completely override a filter or create your own custom filter +from scratch. + +## Filters configuration + +Filters must first be defined in the `FILTERS_CONFIGURATION` setting. It is a dictionary defining +for each filter, a predefined `class` in the code where the filter is implemented and the +parameters to apply to this class when instantiating it. + +Let's study a few examples of filters in the default configuration: + +``` +FILTERS_CONFIGURATION = { + ... + "pace": { + "class": "richie.apps.search.filter_definitions.StaticChoicesFilterDefinition", + "params": { + "fragment_map": { + "self-paced": [{"bool": {"must_not": {"exists": {"field": "pace"}}}}], + "lt-1h": [{"range": {"pace": {"lt": 60}}}], + "1h-2h": [{"range": {"pace": {"gte": 60, "lte": 120}}}], + "gt-2h": [{"range": {"pace": {"gt": 120}}}], + }, + "human_name": _("Weekly pace"), + "min_doc_count": 0, + "sorting": "conf", + "values": { + "self-paced": _("Self-paced"), + "lt-1h": _("Less than one hour"), + "1h-2h": _("One to two hours"), + "gt-2h": _("More than two hours"), + }, + }, + }, + ... +} +``` + +This filter uses the `StaticChoicesFilterDefinition` filter definition class and allows filtering +on the `pace` field present in the Elasticsearch index. The `values` parameter defines 4 ranges +and their human readable format that will appear as 4 filtering options to the user. + +The `fragment_map` parameter defines a fragment of the Elasticsearch query to apply on the `pace` +field when one of these options is selected. + +The `human_name`parameter defines how the filter is entitled. It is defined as a lazy i18n string +so that it can be translated. + +The `sorting` parameter determines how the facets are sorted in the left side panel of the filter: +- `conf`: facets are sorted as defined in the `values` configuration parameter +- `count`: facets are sorted according to the number of course results associated with each facet +- `name`: facets are sorted by their name in alphabetical order + +The `min_doc_count` parameter defines how many associated results a facet must have at the minimum +before it is displayed as an option for the filter. + +Let's study another interesting example: + +``` +FILTERS_CONFIGURATION = { + ... + "organizations": { + "class": "richie.apps.search.filter_definitions.IndexableHierarchicalFilterDefinition", + "params": { + "human_name": _("Organizations"), + "is_autocompletable": True, + "is_drilldown": False, + "is_searchable": True, + "min_doc_count": 0, + "reverse_id": "organizations", + }, + }, + ... +} +``` + +This filter uses the `IndexableHierarchicalFilterDefinition` filter definition class and allows +filtering on the link between course pages and other pages identified by their IDs like for +example here `Organization` pages. + +In the example above, when an option is selected, results will only include the courses for which +the `organizations` field in the index is including the ID of the selected organization page. + +The `reverse_id` parameter should point to a page's reverse ID (see DjangoCMS documentation) in +the CMS. The filter will propose a filtering option for each children organization under this +page. + +The `is_autocompletable` field determines whether organizations should be searched and suggested +by the autocomplete feature (organizations must have an associated index and API endpoint for +autocompletion carrying the same name). + +The `is_drilldown` parameter determines whether the filter is limited to one active value at a +time or allows multi-facetting. + +The `is_searchable` field determines whether organizations filters should present a "more options" +button in case there are more facet options in results than can be displayed (organizations must +have an associated API endpoint for full-text search, carrying the same name). + +Lastly, let's look at nested filters which, as their name indicates, allow filtering on nested +fields. + +For example, in the course index, one of the fields is named `course_runs` and contains a list of +objects in the following format: + +``` +"course_runs": [ + { + "start": "2022-09-09T09:00:00.000000", + "end": "2021-10-30T00:00:00.000000Z", + "enrollment_start": "2022-08-01T09:00:00.000000Z", + "enrollment_end": "2022-09-08T00:00:00.000000Z", + "languages": ["en", "fr"], + }, + { + "start": "2023-03-01T09:00:00.000000", + "end": "2023-06-03T00:00:00.000000Z", + "enrollment_start": "2023-01-01T09:00:00.000000Z", + "enrollment_end": "2023-03-01T00:00:00.000000Z", + "languages": ["fr"], + }, +] +``` + +If we want to filter courses that are available in the english language, we can thus configure the +following filter: + +``` +FILTERS_CONFIGURATION = { + ... + "course_runs": { + "class": "richie.apps.search.filter_definitions.NestingWrapper", + "params": { + "filters": { + "languages": { + "class": "richie.apps.search.filter_definitions.LanguagesFilterDefinition", + "params": { + "human_name": _("Languages"), + # There are too many available languages to show them all, all the time. + # Eg. 200 languages, 190+ of which will have 0 matching courses. + "min_doc_count": 1, + }, + }, + } + }, + }, + ... +} +``` + +## Filters presentation + +Which filters are displayed in the left side bar of the search page and in which order is defined +by the `RICHIE_FILTERS_PRESENTATION` setting. + +This setting is expecting a list of strings, which are the names of the filters as defined +in the `FILTERS_CONFIGURATION` setting decribed in the previous section. If it, for example, +contains the 3 filters presented in the previous section, we could define the following +presentation: + +``` +RICHIE_FILTERS_PRESENTATION = ["organizations", "languages", "pace"] +``` + +## Writing your own custom filters + +You can write your own filters from scratch although we must warn you that it is not trivial +because it requires a good knowledge of Elasticsearch and studying the mapping defined in the +[courses indexer][1]. + +A filter is a class deriving from [BaseFilterDefinition][2] and defining methods to return the +information to display the filter and query fragments for elasticsearch: +- `get_form_fields`: returns the form field instance that will be used to parse and validate this + filter's values from the querystring +- `get_query_fragment`: returns the query fragment to use as filter in ElasticSearch +- `get_aggs_fragment`: returns the query fragment to use to extract facets from + ElasticSearch aggregations +- `get_facet_info`: returns the dynamic facet information from a filter's Elasticsearch facet + results. Together with the facet's static information, it will be used to display the filter + in its current status in the left side panel of the search page. + +We will not go into more details here about how filter definition classes work, but you can refer +to the code of the existing filters as good examples of what is possible. The code, although not +trivial, was given much care and includes many comments in an attempt to help writing new custom +filters. Of course, don't hesitate to ask for help by +[opening an issue](https://github.com/openfun/richie/issues)! + +[1]: https://github.com/openfun/richie/blob/master/src/richie/apps/search/indexers/courses.py +[2]: https://github.com/openfun/richie/blob/master/src/richie/apps/search/filter_definitions/base.py diff --git a/website/versioned_docs/version-2.25.0/frontend-overrides.md b/website/versioned_docs/version-2.25.0/frontend-overrides.md new file mode 100644 index 0000000000..032297ac2c --- /dev/null +++ b/website/versioned_docs/version-2.25.0/frontend-overrides.md @@ -0,0 +1,105 @@ +--- +id: frontend-overrides +title: Overriding frontend components +sidebar_label: Frontend overrides +--- + +Once you are able to build the frontend in your project (see previous section), you can override some parts of the frontend with a drop-in replacement you built yourself. + +This enables you to customize Richie to your own needs in the same way you could do it with backend templates by overriding templates or blocks which do not suit your needs. + +## Defining your overrides + +Create a `json` settings files somewhere in your project. You'll use it to declare the overrides for your custom Richie build. + +Currently, it is only possible to override components. Richie's build is only set up to handle them. + +Inside, create an object with only one key: `"overrides"`. This is an object, whose key-value pairs is the name of a component as a key and the path to the drop-in replacement as the value. + +```json +{ + "overrides": { + "CourseGlimpse": "src/richie/components/CustomCourseGlimpse.tsx" + } +} +``` + +## Building a component override + +As overrides are supposed to be drop-in replacements, directly processed by the bundler instead of the original file, they need to expose the same API. + +For example, if our component to override was the following: + +```tsx +export interface CourseGlimpseProps { + course: Course; + context: { someProp: string }; +} + +export const CourseGlimpse: React.FC = ({ course, context }) => { + // Whatever happens in this component + return

The glimpse

; +}; +``` + +Then, your override needs to provide the same exports, explicitly a named `CourseGlimpseProps` interface and a named `CourseGlimpse` component. + +You also need to respect the assumptions made by other components that use your overridden version, if you are not overriding a root component. + +For example returning `null` might break a layout if the original component never returned such a value, etc. You also need to make sure to avoid conflict with the parameters accepted by the original component. + +## Override translation +When you create an application based on richie, you can encounter two cases about translations: +1. You created or overrode a react component and created new translation keys +2. You just want to override a translation in an existing richie component + + + +### Create new translation keys + +Once you created your new component with its translation keys, you have to extract them with the following command: +``` + formatjs extract './**/*.ts*' --ignore ./node_modules --ignore './**/*.d.ts' --out-file './i18n/frontend.json --id-interpolation-pattern '[sha512:contenthash:base64:6]' --format crowdin +``` + +This command extracts all translations defined in your typescript files then generates a `frontend.json` file in `i18n/` directory. This file is like a pot file, this is the base to create your translations in any language you want. + +As `--format` option indicates, this command generates a file compatible with crowdin. If you want to customize this command to fit your needs, read the [formatjs/cli documentation](https://formatjs.io/docs/tooling/cli/). + +Once translations keys are extracted and your local translations are ready, you need to compile these translations. In fact, the compilation process first aggregates all translation files found from provided paths then merges them with richie translations according their filename and finally generates an output formatted for `react-intl`. Below, here is an example of a compilation command: + +``` + node-modules/richie-education/i18n/compile-translations.js ./i18n/locales/*.json +``` + +This command looks for all translation files in `i18n/locales` directory then merges files found with richie translation files. You can pass several path patterns. You can also use an `--ignore` argument to ignore a particular path. + +### Override an existing translation key + +As explain above, the compilation process aggregates translations files then **merges them according their filename**. That means if you want override for example the english translation, you just have to create a `en-US.json` file and redefine translation keys used by Richie. + +Richie uses one file per language. Currently 4 languages supported: + +- English: filename is `en-US.json` +- French: filename is `fr-FR.json` +- Canadian french: filename is `fr-CA.json` +- Spanish: filename is `es-ES.json` + + +For example, richie uses the translation key `components.UserLogin.logIn` for the Log in button. If you want to change this label for the english translation, you just have to create a translation file `en-US.json` which redefines this translation key: + +```json +{ + "components.UserLogin.logIn": { + "description": "Overriden text for the login button.", + "message": "Authentication" + }, +} +``` + +Then, for example if you put your overridden translation in i18n/overrides directory, you have to launch the compilation command below: +``` + node-modules/richie-education/i18n/compile-translations.js ./i18n/overrides/*.json +``` + +In this way, "_Authentication_" will be displayed as label for login button instead of "_Sign in_". diff --git a/website/versioned_docs/version-2.25.0/installation.md b/website/versioned_docs/version-2.25.0/installation.md new file mode 100644 index 0000000000..bb6dc20065 --- /dev/null +++ b/website/versioned_docs/version-2.25.0/installation.md @@ -0,0 +1,96 @@ +--- +id: installation +title: Installing Richie for development +sidebar_label: Installation +--- + +`Richie` is a **container-native application** but can also be installed +[on your machine](native-installation.md). + +For development, the project is defined using a +[docker-compose file](../docker-compose.yml) and consists of: + +- 3 running services: + - **database**: `postgresql` or `mysql` at your preference, + - **elasticsearch**: the search engine, + - **app**: the actual `DjangoCMS` project with all our application code. + +- 2 containers for building purposes: + + - **node**: used for front-end related tasks, _i.e._ transpiling + `TypeScript` sources, bundling them into a JS package, and building the + CSS files from Sass sources, + - **crowdin**: used to upload and retrieve i18n files to and from the + [Crowding](https://crowdin.com/) service that we use to crowd source + translations, + +At "France Université Numérique", we deploy our applications on `Kubernetes` +using [`Arnold`](https://github.com/openfun/arnold). + +## Docker + +First, make sure you have a recent version of Docker and +[Docker Compose](https://docs.docker.com/compose/install) installed on your +laptop: + +```bash +$ docker -v + Docker version 26.0.0, build 2ae903e + +$ docker compose --version + Docker Compose version v2.25.0 +``` + +⚠️ You may need to run the following commands with `sudo` but this can be +avoided by assigning your user to the `docker` group. + +### Project bootstrap + +The easiest way to start working on the project is to use our `Makefile`: + + $ make bootstrap + +This command builds the `app` container, installs front-end and back-end +dependencies, builds the front-end application and styles, and performs +database migrations. It's a good idea to use this command each time you are +pulling code from the project repository to avoid dependency-related or +migration-related issues. + +Now that your `Docker` services are ready to be used, start the full CMS by +running: + + $ make run + +### Adding content + +Once the CMS is up and running, you can create a superuser account: + + $ make superuser + +You can create a basic demo site by running: + + $ make demo-site + +Note that if you don't create the demo site and start from a blank CMS, you +will get some errors requesting you to create some required root pages. So it +is easier as a first approach to test the CMS with the demo site. + +You should be able to view the site at [localhost:8070](http://localhost:8070) + +## Connecting Richie to an LMS + +It is possible to use Richie as a catalogue aggregating courses from one or +more LMS without any specific connection. In this case, each course run in +the catalogue points to a course on the LMS, and the LMS points back to the +catalogue to browse courses. + +This approach is used for example on https://www.fun-campus.fr or +https://catalogue.edulib.org. + +For a seamless user experience, it is possible to connect a Richie instance +to an OpenEdX instance (or some other LMS like Moodle at the cost of minor +adaptations), in several ways that we explain in the +[LMS connection guide](lms-connection). + +This approach is used for example on https://www.fun-mooc.fr or +https://www.nau.edu.pt. diff --git a/website/versioned_docs/version-2.25.0/internationalization.md b/website/versioned_docs/version-2.25.0/internationalization.md new file mode 100644 index 0000000000..b4e791ed54 --- /dev/null +++ b/website/versioned_docs/version-2.25.0/internationalization.md @@ -0,0 +1,48 @@ +--- +id: internationalization +title: Internationalization +sidebar_label: I18n +--- + +`richie` has built-in localization and internationalization: + +- On the backend and CMS, i18n is built on the shoulders of Django and DjangoCMS, +- On the frontend, we use React Intl. + +## Contributing as a translator or proof-reader + +We use the [Crowdin](https://crowdin.com) web platform to translate Richie to different languages. +All translations are hosted at https://i18n.richie.education, which allows translators and +proof-readers to contribute on translations in the languages they master. + +### Sign-up on Crowdin + +If you don't have an account on Crowdin already, go to https://accounts.crowdin.com/register and +fill out the form to create a free account. + +### Join the Richie project + +Now that you have an account on Crowdin, +[look for the project called "Richie"](https://crowdin.com/project/richie), select the language +on which you wish to contribute and click the "Join" button as demonstrated below: + +![How to join Richie on Crowdin](assets/images/crowdin-join-richie.gif) + +We will then review you application and you should soon start translating strings! + +For more information on how Crowdin works, you can refer to +[their documentation](https://support.crowdin.com). + +### Add a new language + +If Richie is not yet translated in the language you want, let us know by clicking the "contact" +link on [Richie's Crowdin profile page](https://i18n.richie.education) and we will consider adding +it. + +If you request a new language, the Richie community will expect you to keep this language +up-to-date each time strings are modified or new strings are added, and this before each +release. + +Before asking for a new language, make sure it does not already exist. If your language already +exists in another variant (e.g. Brazilian portuguese vs Portugal portuguese), you may consider +contributing on the existing language if your resources to contribute are limited. diff --git a/website/versioned_docs/version-2.25.0/joanie-connection.md b/website/versioned_docs/version-2.25.0/joanie-connection.md new file mode 100644 index 0000000000..19cdddea05 --- /dev/null +++ b/website/versioned_docs/version-2.25.0/joanie-connection.md @@ -0,0 +1,132 @@ +--- +id: joanie-connection +title: Joanie Connection +sidebar_label: Joanie Connection +--- + +[Joanie](https://github.com/openfun/joanie) delivers an API able to manage course +enrollment/subscription, payment and certificates delivery. Richie can be configured to display +course runs and micro-credentials managed through Joanie. + +In fact, Richie treats Joanie almost like a [LMS backend](./lms-backends.md) that's why settings +are similars. + +## Configuring Joanie + +All settings related to Joanie have to be declared in the `JOANIE_BACKEND` dictionnary +within `settings.py`. + +```python +JOANIE_BACKEND = { + "BASE_URL": values.Value(environ_name="JOANIE_BASE_URL", environ_prefix=None), + "BACKEND": values.Value("richie.apps.courses.lms.joanie.JoanieBackend", environ_name="JOANIE_BACKEND", environ_prefix=None), + "JS_BACKEND": values.Value("joanie", environ_name="JOANIE_JS_BACKEND", environ_prefix=None), + "COURSE_REGEX": values.Value( + r"^.*/api/v1.0(?P(?:/(?:courses|course-runs|products)/[^/]+)+)/?$", + environ_name="JOANIE_COURSE_REGEX", + environ_prefix=None, + ), + "JS_COURSE_REGEX": values.Value( + r"^.*/api/v1.0((?:/(?:courses|course-runs|products)/[^/]+)+)/?$", + environ_name="JOANIE_JS_COURSE_REGEX", + environ_prefix=None, + ), + # Course runs synchronization + "COURSE_RUN_SYNC_NO_UPDATE_FIELDS": [], + "DEFAULT_COURSE_RUN_SYNC_MODE": "sync_to_public", +} +... +``` + +As mentioned earlier, Joanie is treated as a LMS by Richie, so we have to bind Joanie settings with +LMS backends settings. We achieve this by dynamically appending the `JOANIE_BACKEND` setting value +into the `RICHIE_LMS_BACKENDS` list, if Joanie is enabled. To understand this point, you can take a +look at the `post_setup` method of the Base class configuration into `settings.py`. + +Here they are all settings available into `JOANIE_BACKEND`: + +### BASE_URL + +The base url on which the Joanie instance is hosted. This is used to construct the complete url of +the API endpoint on which requests are made by Richie's frontend application. *Richie checks if this +settings is set to know if Joanie should be enabled or not.* + +- Type: string +- Required: Yes +- Value: for example https://joanie.example.com + +### BACKEND + +The path to a Python class serving as Joanie backend. You should not need to change this setting +until you want to customize the behavior of the python Joanie backend. + +- Type: string +- Required: No +- Value: By default it is `richie.apps.courses.lms.joanie.JoanieBackend` + +### JS_BACKEND + +The name of the ReactJS backend to use Joanie. You should not need to change this setting +until you want to customize the behavior of the js Joanie backend. + +- Type: string +- Required: No +- Value: By default it is `joanie`. + +### COURSE_REGEX + +A python regex that should match the ressource api urls of Joanie and return a +`resource_uri` named group. The `resource_uri` group should contain the url part containing +all resources type and id implied. +e.g: `https://joanie.test/courses/00003/products/000001/` -> `/courses/00003/products/000001` + +- Type: string +- Required: No +- Value: for example `r"^.*/api/v1.0(?P(?:/(?:courses|course-runs|products)/[^/]+)+)/?$"` + + +### JS_COURSE_REGEX + +A Javascript regex that should match the ressource api urls of Joanie and return an unamed group +corresponding to the `resource_uri` named group described in `COURSE_REGEX` section. Extracting +properly this information is mandatory as this group is parsed under the hood +by the frontend application to extract resource types and resource ids. + +- Type: string +- Required: No +- Value: for example `r"^.*/api/v1.0((?:/(?:courses|course-runs|products)/[^/]+)+)/?$"` + +### COURSE_RUN_SYNC_NO_UPDATE_FIELDS + +A list of fields that must only be set the first time a course run is synchronized. During this +first synchronization, a new course run is created in Richie and all fields sent to the API +endpoint via the payload are set on the object. For subsequent synchronization calls, the fields +listed in this setting are ignored and not synchronized. This can be used to allow modifying some +fields manually in Richie regardless of what OpenEdX sends after an initial value is set. + +Read documentation of [the eponym `LMS_BACKENDS` settings](./lms-backends.md#course_run_sync_no_update_fields), +to discover how it can be configured. + +### DEFAULT_COURSE_RUN_SYNC_MODE + +Joanie resources (course runs and products) are all synchronized with Richie as a CourseRun. This +setting is used to set the value of the `sync_mode` field when a course run is created on Richie. +Read documentation of [the eponym `LMS_BACKENDS` settings](./lms-backends.md#default_course_run_sync_mode), +to discover how it can be configured. + +## Access Token +### Lifetime configuration +Access Token is stored within the SessionStorage through [react-query client persister](https://tanstack.com/query/v4/docs/plugins/persistQueryClient). +By default, richie frontend considered access token as stale after 5 minutes. You can change this +value into [`settings.ts`](https://github.com/openfun/richie/blob/643d7bbdb7f9a02a86360607a7b37c587e70be1a/src/frontend/js/settings.ts) +by editing `REACT_QUERY_SETTINGS.staleTimes.session`. + +To always have a valid access token, you have to configure properly its stale time according to the +lifetime of the access token defined by your authentication server. For example, if your +authentication server is using `djangorestframework-simplejwt` to generate the access token, +its lifetime is 5 minutes by default. + +## Technical support + +If you encounter an issue with this documentation, please +[open an issue on our repository](https://github.com/openfun/richie/issues). diff --git a/website/versioned_docs/version-2.25.0/lms-backends.md b/website/versioned_docs/version-2.25.0/lms-backends.md new file mode 100644 index 0000000000..c16848aa6d --- /dev/null +++ b/website/versioned_docs/version-2.25.0/lms-backends.md @@ -0,0 +1,159 @@ +--- +id: lms-backends +title: Configuring LMS Backends +sidebar_label: LMS Backends +--- + +Richie can be connected to one or more OpenEdX Learning Management Systems (LMS) for a seamless +experience between browsing the course catalog on Richie, enrolling to a course and following the +course itself on the LMS. + +It is possible to do the same with Moodle or any other LMS exposing an enrollment API, at the +cost of writing a custom LMS handler backend. + +## Prerequisites + +This connection requires that Richie and OpenEdX be hosted on sibling domains i.e. domains that +are both subdomains of the same root domain, e.g. `richie.example.com` and `lms.example.com`. + +OpenEdX will need to generate a CORS CSRF Cookie and this cookie is flagged as secure, which +implies that we are not able to use it without SSL connections. + +As a consequence, you need to configure your OpenEdX instance as follows: + +```python +FEATURES = { + ... + "ENABLE_CORS_HEADERS": True, + "ENABLE_CROSS_DOMAIN_CSRF_COOKIE": True, +} + +CORS_ALLOW_CREDENTIALS = True +CORS_ALLOW_INSECURE = False +CORS_ORIGIN_WHITELIST: ["richie.example.com"] # The domain on which Richie is hosted + +CROSS_DOMAIN_CSRF_COOKIE_DOMAIN = ".example.com" # The parent domain shared by Richie and OpenEdX +CROSS_DOMAIN_CSRF_COOKIE_NAME: "edx_csrf_token" +SESSION_COOKIE_NAME: "edx_session" +``` + +## Configuring the LMS handler + +The `LMSHandler` utility acts as a proxy that routes queries to the correct LMS backend API, +based on a regex match on the URL of the course. It is configured via the `RICHIE_LMS_BACKENDS` +setting. As an example, here is how it would be configured to connect to an Ironwood OpenEdX +instance hosted on `https://lms.example.com`: + +```python +RICHIE_LMS_BACKENDS=[ + { + "BASE_URL": "https://lms.example.com", + # Django + "BACKEND": "richie.apps.courses.lms.edx.EdXLMSBackend", + "COURSE_REGEX": r"^https://lms\.example\.com/courses/(?P.*)/course/?$", + # ReactJS + "JS_BACKEND": "openedx-hawthorn", + "JS_COURSE_REGEX": r"^https://lms\.example\.com/courses/(.*)/course/?$", + # Course runs synchronization + "COURSE_RUN_SYNC_NO_UPDATE_FIELDS": [], + "DEFAULT_COURSE_RUN_SYNC_MODE": "sync_to_public", + }, +] +``` + +The following should help you understand how to configure this setting: + +### BASE_URL + +The base url on which the OpenEdX instance is hosted. This is used to construct the complete url +of the API endpoint on which the enrollment request is made by Richie's frontend application. + +- Type: string +- Required: Yes +- Value: for example https://lms.example.com + + +### BACKEND + +The path to a Python class serving as LMS backend for the targeted LMS. + +- Type: string +- Required: Yes +- Value: Richie ships with the following Python backends (custom backends can be written to fit + another specific LMS): + + `richie.apps.courses.lms.edx.EdXLMSBackend`: backend for OpenEdX + + `richie.apps.courses.lms.base.BaseLMSBackend`: fake backend for development purposes + + +### COURSE_REGEX + +A Python regex that should match the course syllabus urls of the targeted LMS and return a +`course_id` named group on the id of the course extracted from these urls. + +- Type: string +- Required: Yes +- Value: for example `^.*/courses/(?P.*)/course/?$` + + +### JS_BACKEND + +The name of the ReactJS backend to use for the targeted LMS. + +- Type: string +- Required: Yes +- Value: Richie ships with the following Javascript backends (custom backends can be written to + fit another specific LMS): + + `openedx-dogwood`: backend for OpenEdX versions equal to `dogwood` or `eucalyptus` + + `openedx-hawthorn`: backend for OpenEdX versions equal to `hawthorn` or higher + + `openedx-fonzie`: backend for OpenEdX via [Fonzie](https://github.com/openfun/fonzie) + (extra user info and JWT tokens) + + `dummy`: fake backend for development purposes + +### JS_COURSE_REGEX + +A Javascript regex that should match the course syllabus urls of the targeted LMS and return an +unnamed group on the id of the course extracted from these urls. + +- Type: string +- Required: Yes +- Value: for example `^.*/courses/(.*)/course/?$` + +### DEFAULT_COURSE_RUN_SYNC_MODE + +When a course run is created, this setting is used to set the value of the `sync_mode` field. +This value defines how the course runs synchronization script will impact this course run after +creation. + +- Type: enum(string) +- Required: No +- Value: possible values are `manual`, `sync_to_draft` and `sync_to_public` + + `manual`: this course run is ignored by the course runs synchronization script + + `sync_to_draft`: only the draft version of this course run is synchronized. A manual + publication is necessary for the update to be visible on the public site. + + `sync_to_public`: the public version of this course run is updated by the synchronization + script. As a results, updates are directly visible on the public site without further + publication by a staff user in Richie. + +### COURSE_RUN_SYNC_NO_UPDATE_FIELDS + +A list of fields that must only be set the first time a course run is synchronized. During this +first synchronization, a new course run is created in Richie and all fields sent to the API +endpoint via the payload are set on the object. For subsequent synchronization calls, the fields +listed in this setting are ignored and not synchronized. This can be used to allow modifying some +fields manually in Richie regardless of what OpenEdX sends after an initial value is set. + +Note that this setting is only effective for course runs with the `sync_mode` field set to a +value other then `manual`. + +- Type: enum(string) +- Required: No +- Value: for example ["languages"] + + +## Technical support + +If you encounter an issue with this documentation or the backends included in Richie, please +[open an issue on our repository](https://github.com/openfun/richie/issues). + +If you need a custom backend, you can [submit a PR](https://github.com/openfun/richie/pulls) or +[open an issue](https://github.com/openfun/richie/issues) and we will consider adding it. diff --git a/website/versioned_docs/version-2.25.0/lms-connection.md b/website/versioned_docs/version-2.25.0/lms-connection.md new file mode 100644 index 0000000000..ce91cc165c --- /dev/null +++ b/website/versioned_docs/version-2.25.0/lms-connection.md @@ -0,0 +1,91 @@ +--- +id: lms-connection +title: Connecting Richie with one or more LMS +sidebar_label: LMS connection +--- + +## Connecting Richie to an LMS + +Richie can be connected to an LMS in several ways, ranging from SSO to a fully integrated +seamless experience. + +As of today, each approach has been implemented for OpenEdX but the same could be done for +other LMSes like Moodle, at the cost of minor adaptations. + + +### 1. Displaying connection status + +OpenEdX can be configured to allow CORS requests. Doing so allows Richie to retrieve a user's +connection status from OpenEdx and display the user's profile information directly on the Richie +site: username, dashboard url, etc. + +In this approach, a user visiting your Richie site and trying to signup or login, is sent to the +OpenEdX site for authentication and is redirected back to the Richie site upon successful login. + +You can see this in action on https://www.fun-mooc.fr. + +We provide detailed instructions on +[how to configure displaying OpenEdX connection status in Richie](displaying-connection-status.md). + + +### 2. Seamless enrollment + +Thanks to OpenEdX's enrollment API, it is possible to let users enroll on course runs without +leaving Richie. + +You can see this in action on https://www.fun-mooc.fr. + +> This feature requires that Richie and OpenEdX be hosted on sibling domains i.e. domains that +> are both subdomains of the same root domain, e.g. `richie.example.com` and `lms.example.com`. + +You should read our guide on [how to use OpenEdX as LMS backend for Richie](lms-backends). + + +### 3. Synchronizing course runs details + +Course runs in Richie can be handled manually, filling all fields via the DjangoCMS front-end +editing interface. But a better way to handle course runs is to synchronize them automatically +from your LMS using the course run synchronization API. + +Please refer to our guide on [how to synchronize course runs between Richie and OpenEdx][sync] + +### 4. Joanie, the enrollment manager + +For more advanced use cases, we have started a new project called [Joanie] which acts as an +enrollment manager for Richie. + +Authentication in Joanie is done via JWT Tokens for maximum flexibility and decoupling in +identity management. + +The project started early 2021, but over time, Joanie will handle: + +- paid enrollments / certification +- micro-credentials +- user dashboard +- cohorts management (academic or B2B) +- multi-LMS catalogs +- time based enrollment + + +## Development + +For development purposes, the docker compose project provided on +[Richie's code repository](https://github.com/openfun/richie) is pre-configured to connect +with an OpenEdx instance started with +[OpenEdx Docker](https://github.com/openfun/openedx-docker), which provides a ready-to-use +docker compose stack of OpenEdx in several flavors. Head over to +[OpenEdx Docker README](https://github.com/openfun/openedx-docker#readme) for instructions on how to bootstrap an OpenEdX instance. + +Now, start both the OpenEdX and Richie projects separately with `make run`. + +Richie should respond on `http://localhost:8070`, OpenEdx on `http://localhost:8073` and both +apps should be able to communicate with each other via the network bridge defined in +docker compose. + +If you want to activate [seamless enrollment](#2-seamless-enrollment) locally for development, +you will need to set up TLS domains for both Richie and OpenEdX. To do this, head over to our +guide on [setting-up TLS connections for Richie and OpenEdX](tls-connection). + + +[Joanie]: https://github.com/openfun/joanie +[sync]: synchronizing-course-runs diff --git a/website/versioned_docs/version-2.25.0/native-installation.md b/website/versioned_docs/version-2.25.0/native-installation.md new file mode 100644 index 0000000000..0573a8d8e1 --- /dev/null +++ b/website/versioned_docs/version-2.25.0/native-installation.md @@ -0,0 +1,190 @@ +--- +id: native-installation +title: Installing Richie on your machine +sidebar_label: Native installation +--- + +This document aims to list all needed steps to have a working `Richie` +installation on your laptop. + +A better approach is to use [`Docker`](https://docs.docker.com) as explained in +our guide for [container-native installation](installation.md) instructions. + +## Installing a fresh server + +### Version + +You need a `Ubuntu 18.04 Bionic Beaver` (the latest LTS version) fresh +installation. + +If you are using another operating system or distribution, you can use +[`Vagrant`](https://docs.vagrantup.com/v2/getting-started/index.html) to get a +running Ubuntu 18.04 server in seconds. + +### System update + +Be sure to have fresh packages on the server (kernel, libc, ssl patches...): +post + +```sh +sudo apt-get -y update +sudo apt-get -y dist-upgrade +``` + +## Database part + +You must first install `postgresql`. + +```sh +// On Linux +sudo apt-get -y install postgresql + +// On OS X +brew install postgresql@10 +brew services start postgresql@10 +// don't forget to add your new postgres install to the $PATH +``` + +`Postgresql` is now running. + +Then you can create the database owner and the database itself, using the +`postgres` user: + +```sh +sudo -u postgres -i // skip this on OS X as the default install will use your local user +createuser fun -sP +``` + +Note: we created the user as a superuser. This should only be done in dev/test +environments. + +Now, create the database with this user: + +```sh +createdb richie -O fun -W +exit +``` + +## Elasticsearch + +### Ubuntu + +Download and install the Public Signing Key + + $ wget -qO - https://artifacts.elastic.co/GPG-KEY-elasticsearch | sudo apt-key add - + +You may need to install the apt-transport-https package on Debian before +proceeding: + + $ sudo apt-get install apt-transport-https + +Save the repository definition to /etc/apt/sources.list.d/elastic-6.3.1.list: + + $ echo "deb https://artifacts.elastic.co/packages/6.3.1/apt stable main" | sudo tee -a /etc/apt/sources.list.d/elastic-6.3.1.list + +Update repository and install + + $ sudo apt-get update + $ sudo apt-get install elasticsearch + $ sudo /etc/init.d/elasticsearch start + +### OS X + + $ brew install elasticsearch + +## Application part + +### Python and other requirements + +We use `Python 3.6` which is the one installed by default in `Ubuntu 18.04`. + +You can install it on OS X using the following commands. Make sure to always run +`python3` instead of `python` and `pip3` instead of `pip` to ensure the correct +version of Python (your homebrew install of 3) is used. + +``` +brew install python3 +brew postinstall python3 +``` + +### The virtualenv + +Place yourself in the application directory `app`: + + cd app + +We choose to run our application in a virtual environment. + +For this, we'll install `virtualenvwrapper` and add an environment: + + pip install virtualenvwrapper + +You can open a new shell to activate the virtualenvwrapper commands, or simply +do: + + source $(which virtualenvwrapper.sh) + +Then create the virtual environment for `richie`: + + mkvirtualenv richie --no-site-packages --python=python3 + +The virtualenv should now be activated and you can install the Python +dependencies for development: + + pip install -e .[dev] + +The "dev.txt" requirement file installs packages specific to a dev environment +and should not be used in production. + +### Frontend build + +This project is a hybrid that uses both Django generated pages and frontend JS +code. As such, it includes a frontend build process that comes in two parts: JS +& CSS. + +We need NPM to install the dependencies and run the build, which depends on a +version of Nodejs specified in `.nvmrc`. See [the +repo](https://github.com/creationix/nvm) for instructions on how to install NVM. +To take advantage of `.nvmrc`, run this in the context of the repository: + + nvm install + nvm use + +As a prerequisite to running the frontend build for either JS or CSS, you'll +need to [install yarn](https://yarnpkg.com/lang/en/docs/install/) and download +dependencies _via_: + + yarn install + +- JS build + +```bash +npm run build +``` + +- CSS build + +This will compile all our SCSS files into one bundle and put it in the static +folder we're serving. + + npm run sass + +### Run server + +Make sure your database is up-to-date before running the application the first +time and after each modification to your models: + + python sandbox/manage.py migrate + +You can create a superuser account: + + python sandbox/manage.py createsuperuser + +Run the tests + + python sandbox/manage.py test + +You should now be able to start Django and view the site at +[localhost:8000](http://localhost:8000) + + python sandbox/manage.py runserver diff --git a/website/versioned_docs/version-2.25.0/synchronizing-course-runs.md b/website/versioned_docs/version-2.25.0/synchronizing-course-runs.md new file mode 100644 index 0000000000..0848d0be20 --- /dev/null +++ b/website/versioned_docs/version-2.25.0/synchronizing-course-runs.md @@ -0,0 +1,124 @@ +--- +id: synchronizing-course-runs +title: Synchronizing course runs between Richie and OpenEdX +sidebar_label: Synchronizing course runs +--- + +Richie can receive automatic course runs updates on a dedicated API endpoint. + +## Configure a shared secret + +In order to activate the course run synchronization API endpoint, you first need to configure the +`RICHIE_COURSE_RUN_SYNC_SECRETS` setting with one or more secrets: + +```python +RICHIE_COURSE_RUN_SYNC_SECRETS = ["SharedSecret", "OtherSharedSecret"] +``` + +This setting collects several secrets in order to allow rotating them without any downtime. Any +of the secrets listed in this setting can be used to sign your queries. + +Your secret should be shared with the LMS or distant system that needs to synchronize its course +runs with the Richie instance. Richie will try the declared secrets one by one until it finds +one that matches the signature sent by the remote system. + +## Configure LMS backends + +You then need to configure the LMS handler via the `RICHIE_LMS_BACKENDS` setting as explained +in our [guide on configuring LMS backends](lms-backends#configuring-the-lms-handler). This is +required if you want Richie to create a new course run automatically and associate it with the +right course when the resource link submitted to the course run synchronization API endpoint is +unknown to Richie. + +Each course run can be set to react differently to a synchronization request, thanks to the +`sync_mode` field. This field can be set to one of the following values: + ++ `manual`: this course run is ignored by the course runs synchronization script. In this case, + the course run can only be edited manually using the DjangoCMS frontend editing. ++ `sync_to_draft`: only the draft version of this course run is synchronized. A manual + publication is necessary for the update to be visible on the public site. ++ `sync_to_public`: the public version of this course run is updated by the synchronization + script. As a results, updates are directly visible on the public site without further + publication by a staff user in Richie. + +A [DEFAULT_COURSE_RUN_SYNC_MODE parameter](lms-backends#default_course_run_sync_mode) in the +`RICHIE_LMS_BACKENDS` setting, defines what default value is used for new course runs. + +## Make a synchronization query + +You can refer to the [documentation of the course run synchronization API][sync-api] for details +on the query expected by this endpoint. + +We also share here our sample code to call this synchronization endpoint from OpenEdX. This code +should run on the `post_publish` signal emitted by the OpenEdX `cms` application each time a +course run is modified and published. + +Or you can use the [Richie Open edX Synchronization](https://github.com/fccn/richie-openedx-sync) +which is based on the following code sample and also includes the enrollment count. + +Given a `COURSE_HOOK` setting defined as follows in your OpenEdX instance: + +```python +COURSE_HOOK = { + "secret": "SharedSecret", + "url": "https://richie.example.com/api/v1.0/course-runs-sync/", +} +``` + +The code for the synchronization function in OpenEdX could look like this: + +```python +import hashlib +import hmac +import json + +from django.conf import settings + +from microsite_configuration import microsite +import requests +from xmodule.modulestore.django import modulestore + + +def update_course(course_key, *args, **kwargs): + """Synchronize an OpenEdX course, identified by its course key, with a Richie instance.""" + course = modulestore().get_course(course_key) + edxapp_domain = microsite.get_value("site_domain", settings.LMS_BASE) + + data = { + "resource_link": "https://{:s}/courses/{!s}/info".format( + edxapp_domain, course_key + ), + "start": course.start and course.start.isoformat(), + "end": course.end and course.end.isoformat(), + "enrollment_start": course.enrollment_start and course.enrollment_start.isoformat(), + "enrollment_end": course.enrollment_end and course.enrollment_end.isoformat(), + "languages": [course.language or settings.LANGUAGE_CODE], + } + + signature = hmac.new( + setting.COURSE_HOOK["secret"].encode("utf-8"), + msg=json.dumps(data).encode("utf-8"), + digestmod=hashlib.sha256, + ).hexdigest() + + response = requests.post( + setting.COURSE_HOOK["url"], + json=data, + headers={"Authorization": "SIG-HMAC-SHA256 {:s}".format(signature)}, + ) +``` + +Thanks to the signal emitted in OpenEdX, this function can then be triggered each time a course +is modified and published: + +```python +from django.dispatch import receiver +from xmodule.modulestore.django import SignalHandler + + +@receiver(SignalHandler.course_published, dispatch_uid='update_course_on_publish') +def update_course_on_publish(sender, course_key, **kwargs): + update_course(course_key) +``` + +[sync-api]: api/course-run-synchronization-api diff --git a/website/versioned_docs/version-2.25.0/tls-connection.md b/website/versioned_docs/version-2.25.0/tls-connection.md new file mode 100644 index 0000000000..728b52741c --- /dev/null +++ b/website/versioned_docs/version-2.25.0/tls-connection.md @@ -0,0 +1,106 @@ +--- +id: tls-connection +title: Connecting Richie and OpenEdX over TLS for development +sidebar_label: TLS connection for development +--- + +## Purpose + +By default in the docker compose environment for development, Richie is hosted on `localhost:8070` +and uses a fake LMS backend (`base.BaseLMSBackend`) as you can see if you check the +`RICHIE_LMS_BACKENDS` setting in `env.d/development`. + +This base backend uses session storage to fake enrollments to course runs. + +If you want to test real enrollments to an OpenEdX instance hosted on an external domain, OpenEdX +will need to generate a CORS CSRF Cookie. This cookie is flagged as secure, which implies that +we are not able to use it without SSL connections. + +So if you need to use the OpenEdx API to Create, Update or Delete data from Richie, you have to +enable SSL on Richie and OpenEdx on your development environment, which requires a little bit more +configuration. Below, we explain how to serve OpenEdx and Richie over SSL. + +## Run OpenEdx and Richie on sibling domains + +Richie and OpenEdx must be on sibling domains ie domains that both are subdomains of the same +parent domain, because sharing secure Cookies on `localhost` or unrelated domains is blocked. +To do that, you have to edit your hosts file (_.e.g_ `/etc/hosts` on a \*NIX system) to alias a +domain `local.dev` with two subdomains `richie` and `edx` pointing to `localhost`: + +``` +# /etc/hosts +127.0.0.1 richie.local.dev +127.0.0.1 edx.local.dev +``` + +Once this has been done, the OpenEdx app should respond on http://edx.local.dev:8073 +and Richie should respond on http://richie.local.dev:8070. The Richie application should now be +able to make CORS XHR requests to the OpenEdX application. + +## Enable TLS + +If you want to develop with OpenEdx as LMS backend of the Richie application (see the +`RICHIE_LMS_BACKENDS` setting), you need to enable TLS for your development servers. +Both Richie and OpenEdx use Nginx as reverse proxy which eases the SSL setup. + +### 1. Install mkcert and its Certificate Authority + +First you will need to install mkcert and its Certificate Authority. +[mkcert](https://mkcert.org/) is a little util to ease local certificate generation. + +#### a. Install `mkcert` on your local machine + +- [Read the doc](https://github.com/FiloSottile/mkcert) +- Linux users who do not want to use linuxbrew : [read this article](https://www.prado.lt/how-to-create-locally-trusted-ssl-certificates-in-local-development-environment-on-linux-with-mkcert). + +#### b. Install Mkcert Certificate Authority + +`mkcert -install` + +> If you do not want to use mkcert, you can generate [CA and certificate with openssl](https://www.freecodecamp.org/news/how-to-get-https-working-on-your-local-development-environment-in-5-minutes-7af615770eec/). +> You will have to put your certificate and its key in the `docker/files/etc/nginx/ssl` directory +> and respectively name them `richie.local.dev.pem` and `richie.local.dev.key`. + +### 2. On Richie + +Then, to setup the SSL configuration with mkcert, run our helper script: + +```bash +$ bin/setup-ssl +``` + +> If you do not want to use mkcert, read the instructions above to generate a Richie certificate, +> and run the helper script with the `--no-cert` option: + +```bash +bin/setup-ssl --no-cert +``` + +### 3. On OpenEdx + +In the same way, you also have to enable SSL in OpenEdx, by updating the Nginx configuration. +Read how to [enable SSL on OpenEdx][ssl]. + +Once this has been done, the OpenEdx app should respond on https://edx.local.dev:8073 +and Richie should respond on https://richie.local.dev:8070. The richie application should be able +to share cookies with the OpenEdx application to allow CORS CSRF Protected XHR requests. + +### 4. Start Richie and OpenEdx over SSL + +Now, the OpenEdx application should respond on https://edx.local.dev:8073, and Richie +on https://richie.local.dev:8070 without browser warning about the certificate validity. + +You need to follow these steps once. The next time you want to use SSL, you can run the following +command on both the Richie and OpenEdX projects: + +```bash +$ make run-ssl +``` + +Of course, you can still run apps without ssl by using: + +```bash +$ make run +``` + +[ssl]: https://github.com/openfun/openedx-docker/blob/master/docs/richie-configuration.md#richie-configuration diff --git a/website/versioned_docs/version-2.25.0/web-analytics.md b/website/versioned_docs/version-2.25.0/web-analytics.md new file mode 100644 index 0000000000..794f495ae9 --- /dev/null +++ b/website/versioned_docs/version-2.25.0/web-analytics.md @@ -0,0 +1,179 @@ +--- +id: web-analytics +title: Add web analytics to your site +sidebar_label: Web Analytics +--- + +Richie has native support to [Google Universal Analytics](#google-analytics) and [Google Tag Manager](#google-tag-manager) Web Analytics solutions. +The purpose of this file is to explain how you can enable one of the supported Web Analytics providers +and how you can extend Richie with an alternative solution. + +## Google Universal Analytics +Next, it is described how you can configure the **Google Universal Analytics** on your Richie site. + +Add the `WEB_ANALYTICS` setting, with the Google Universal Analytics configuration. From the next example replace `TRACKING_ID` with your tracking id code. + +```python +{ + 'google_universal_analytics': { + 'tracking_id': 'TRACKING_ID', + } +} +``` + +The current Google Universal Analytics implementation also includes custom dimensions. Those dimensions permit you to create further analyses on Google Universal Analytics or even use them to create custom reports. +Custom dimensions with a value as example: +* Organizations codes - `UNIV_LISBON | UNIV_PORTO` +* Course code - `COURSE_XPTO` +* Course runs titles - `Summer edition | Winter edition` +* Course runs resource links - `http://example.edx:8073/courses/course-v1:edX+DemoX+Demo_Course/info` +* Page title - `Introduction to Programming` + +## Google Tag + +It is possible to configure the **Google Tag**, `gtag.js`, on your Richie site. + +Add the `WEB_ANALYTICS` setting, with the Google Tag configuration like for example: + +```python +{ + 'google_tag': { + 'tracking_id': 'TRACKING_ID', + } +} +``` +And don't forget to replace the `TRACKING_ID` with your tracking id/code from Google Ads, Google Analytics, or other Google product compatible with the `gtag.js`. + +The Google Tag is initialized with custom dimensions like the [Google Universal Analytics](#google-analytics). + +## Google Tag Manager +Next, it is described how you can configure the **Google Tag Manager**, `gtm.js`, on your Richie site. + +Add the `WEB_ANALYTICS` setting, with the Google Tag Manager configuration, for example: + +```python +{ + 'google_tag_manager': { + 'tracking_id': 'TRACKING_ID', + } +} +``` + +And don't forget to replace the `TRACKING_ID` with your `GTM` tracking id/code. + +The current Google Tag Manager implementation also defines a custom dimensions like the [Google Universal Analytics](#google-analytics). + +If you want to use the Environments feature of the Google Tag Manager, you need to include the `environment` key with its value on `google_tag_manager` dict inside the `WEB_ANALYTICS` setting. + +_The environments feature in Google Tag Manager is ideal for organizations that want to preview their container changes in a test environment before those changes are published_. + +```python +{ + 'google_tag_manager': { + 'tracking_id': 'TRACKING_ID', + 'environment': '>m_auth=aaaaaaaaaaaaaaaa>m_preview=env-99>m_cookies_win=x'; + } +} +``` + +## Multiple Web Analytics at the same time + +It is possible to configure several web analytics solutions at the same time or the same solution with different tracking identifications. + + +`WEB_ANALYTICS` setting example to have both Google Universal Analytics and Google Tag Manager: + +```python +{ + 'google_universal_analytics': { + 'tracking_id': 'UA-TRACKING_ID', + }, + 'google_tag_manager': { + 'tracking_id': 'GTM-TRACKING_ID', + } +} +``` + +## Location of the web analytics javascript +Each web analytics js code can be put on the `footer` (**default** value), to put the Javascript on HTML body footer, or `header`, to put the Javascript code at the end of the HTML `head`. + +Update the `WEB_ANALYTICS` setting, like: + +```python +{ + 'google_universal_analytics': { + 'tracking_id': 'UA-TRACKING_ID', + 'location': 'footer, + }, +} +``` + +## Add a new Web Analytics solution + +In this section it's described how you can add support to a different Web Analytics solution. + +* override the `richie/web_analytics.html` template +* define the `WEB_ANALYTICS` setting with a value that represents your solution, eg. `my-custom-web-analytics-software` +* define the `WEB_ANALYTICS` setting with your tracking identification +* optionally change `location` with `footer` (default) or `head` value + +```python +{ + 'my-custom-web-analytics-software': { + 'tracking_id': 'MY_CUSTOM_TRACKING_ID', + 'location': 'footer, + }, +} +``` + +- Example of a `richie/web_analytics.html` file customization that prints to the browser console log the dimension keys and values: +```javascript + +``` + +Output: +``` +dimension: index '1' with key 'organizations_codes' with value 'COMPATIBLE-EVEN-KEELED-UTILIZATION-19 | FOCUSED-NEXT-GENERATION-FUNCTIONALITIES-22 | UNIVERSAL-MODULAR-LOCAL-AREA-NETWORK-23' +dimension: index '2' with key 'course_code' with value '00017' +dimension: index '3' with key 'course_runs_titles' with value 'Run 0' +dimension: index '4' with key 'course_runs_resource_links' with value '' +dimension: index '5' with key 'page_title' with value 'Business-focused zero-defect application' +``` + +But you can also contribute to Richie by creating a pull request to add support for a different web analytics solution. In this last case, you have to edit directly the `richie/web_analytics.html` template. + +Example of an override of the `richie/web_analytics.html` file: +```html +{% extends "richie/web_analytics.html" %} +{% block web_analytics_additional_providers %} + {% if provider == "my_custom_web_analytics_software_provider" %} + + {% endif %} +{% endblock web_analytics_additional_providers %} +``` + +The web analytics dimensions are being added to the django context using the `WEB_ANALYTICS.DIMENSIONS` dictionary. Because each dimension value could have multiple values, then each dictionary value is a list. Web analytics dimensions dictionary keys: +* `organizations_codes` +* `course_code` +* `course_runs_titles` +* `course_runs_resource_links` +* `page_title` + +Example, if you only need the organization codes on your custom `richie/web_analytics.html` file: +```javascript + +``` + +The frontend code also sends **events** to the web analytics provider. +Richie sends events when the user is enrolled on a course run. +To support different providers, you need to create a similar file +of `src/frontend/js/utils/api/web-analytics/google_universal_analytics.ts` and change the `src/frontend/js/utils/api/web-analytics/index.ts` file to include that newer provider. diff --git a/website/versioned_sidebars/version-2.25.0-sidebars.json b/website/versioned_sidebars/version-2.25.0-sidebars.json new file mode 100644 index 0000000000..ff166e7a38 --- /dev/null +++ b/website/versioned_sidebars/version-2.25.0-sidebars.json @@ -0,0 +1,22 @@ +{ + "docs": { + "Getting started": ["discover", "cookiecutter"], + "Recipes": [ + "filters-customization", + "django-react-interop", + "building-the-frontend", + "frontend-overrides", + "internationalization", + "lms-connection", + "web-analytics" + ], + "Contributing": [ + "installation", + "docker-development", + "native-installation", + "contributing-guide", + "accessibility-testing", + "css-guidelines" + ] + } +} diff --git a/website/versions.json b/website/versions.json index 607e2056c3..1befe358ea 100644 --- a/website/versions.json +++ b/website/versions.json @@ -1,4 +1,5 @@ [ + "2.25.0", "2.25.0-beta.1", "2.25.0-beta.0", "2.24.1",