From d39bd32768c432f0ab144416dd8662d5560303ed Mon Sep 17 00:00:00 2001 From: Kyle McCormick Date: Thu, 2 May 2024 10:10:52 -0400 Subject: [PATCH] docs: improve 'bare metal' docs and add static assets reference (#34678) --- README.rst | 104 ++++++++++++++++--- docs/references/static-assets.rst | 160 ++++++++++++++++++++++++++++++ 2 files changed, 251 insertions(+), 13 deletions(-) create mode 100644 docs/references/static-assets.rst diff --git a/README.rst b/README.rst index 96e5044140a1..fa1b797b6576 100644 --- a/README.rst +++ b/README.rst @@ -33,42 +33,120 @@ Documentation can be found at https://docs.openedx.org/projects/edx-platform. Getting Started *************** +For Production +============== + Installing and running an Open edX instance is not simple. We strongly recommend that you use a service provider to run the software for you. They have free trials that make it easy to get started: https://openedx.org/get-started/ -If you will be modifying edx-platform code, `Tutor`_ is -the community-supported Docker-based Open edX distribution, both for production and -local development. The goal of Tutor is to make it easy to deploy, customise, -upgrade and scale your Open edX installation. +However, if you have the time and expertise, then it is is possible to +self-manage a production Open edX instance. To help you build, customize, +upgrade, and scale your instance, we recommend using `Tutor`_, the +community-supported, Docker-based Open edX distribution. You can read more about getting up and running with a Tutor deployment at the `Site Ops home on docs.openedx.org`_. -.. _Tutor: https://github.com/overhangio/tutor -.. _Site Ops home on docs.openedx.org: https://docs.openedx.org/en/latest/site_ops/index.html +For Development +=============== + +Tutor also features a `development mode`_ which will also help you modify, +test, and extend edx-platform. We recommend this method for all Open edX +developers. -Dependencies -============ +Bare Metal (Advanced) +===================== -In order to build and run this code you'll need the following available on your -system: +It is also possible to spin up an Open edX platform directly on a Linux host. +This method is less common and mostly undocumented. The Open edX community will +only be able to provided limited support for it. + +Running "bare metal" is only advisable for (a) developers seeking an +adventure and (b) experienced system administrators who are willing to take the +complexity of Open edX configuration and deployment into their own hands. + +System Dependencies +------------------- Interperters/Tools: -* Python 3.8 +* Python 3.11 (preferred) or 3.8 (compatible, for now) -* Node 16 +* Node 18 Services: -* MySQL 5.7 +* MySQL 8.0 * Mongo 7.x * Memcached +Language Packages: + +* Frontend: + + - ``npm clean-install`` (production) + - ``npm clean-install --dev`` (development) + +* Backend build: + + - ``pip install -r requirements/edx/assets.txt`` + +* Backend application: + + - ``pip install -r requirements/edx/base.txt`` (production) + - ``pip install -r requirements/edx/dev.txt`` (development) + +Build Steps +----------- + +Create a MySQL database and a MySQL user with write permissions, and configure +Django to use them. Then, run migrations:: + + ./manage.py lms migrate + ./manage.py cms migrate + +Build static assets (for more details, see `building static +assets`_):: + + npm run build # or, 'build-dev' + +Download locales and collect static assets (can be skipped for development +sites):: + + make pull_translations + ./manage.py lms collectstatic + ./manage.py cms collectstatic + +Run the Platform +---------------- + +First, ensure MySQL, Mongo, and Memcached are running. + +Start the LMS:: + + ./manage.py lms runserver + +Start the CMS:: + + ./manage.py cms runserver + +This will give you a mostly-headless Open edX platform. Most frontends have +been migrated to "Micro-Frontends (MFEs)" which need to be installed and run +separately. At a bare minimum, you will need to run the `Authentication MFE`_, +`Learner Home MFE`_, and `Learning MFE`_ in order meaningfully navigate the UI. + +.. _Tutor: https://github.com/overhangio/tutor +.. _Site Ops home on docs.openedx.org: https://docs.openedx.org/en/latest/site_ops/index.html +.. _development mode: https://docs.tutor.edly.io/dev.html +.. _building static assets: ./docs/references/static-assets.rst +.. _Authentication MFE: https://github.com/openedx/frontend-app-authn/ +.. _Learner Home MFE: https://github.com/openedx/frontend-app-learner-dashboard +.. _Learning MFE: https://github.com/openedx/frontend-app-learning/ + License ******* diff --git a/docs/references/static-assets.rst b/docs/references/static-assets.rst new file mode 100644 index 000000000000..59fae1d65a8f --- /dev/null +++ b/docs/references/static-assets.rst @@ -0,0 +1,160 @@ +Preparing static assets for edx-platform +######################################## + +To run a production or development edx-platform site, you will need to `build +assets`_ assets using ``npm run ...`` commands. Furthermore, for a production +site, you will also need to `collect assets`_. + +*Please note that developing new frontend pages for edx-platform is highly +discouraged. New frontend pages should be built as micro-frontends (MFEs), +which communicate with edx-platform over AJAX, but are built and deployed +independently. Eventually, we expect that MFEs will replace all edx-platform +frontend pages, except perhaps XBlock views.* + +Configuraiton +************* + +To customize the static assets build, set some or all of these variable in your +shell environment before building or collecting static assets. As noted below, +some of these values will automatically become available as Django settings in +LMS or CMS (unless you separately override them in a private Django settings +file or ``LMS_CFG``/``CMS_CFG`` yaml file). + +.. list-table:: + :header-rows: 1 + + * - Environment Variable + - Default + - Description + - LMS Django Setting + - CMS Django Setting + + * - ``COMPREHENSIVE_THEME_DIRS`` + - (empty) + - Directories that will be searched when compiling themes. + Separate multiple paths with colons (``:``). + - ``COMPREHENSIVE_THEME_DIRS`` + - ``COMPREHENSIVE_THEME_DIRS`` + + * - ``WEBPACK_CONFIG_PATH`` + - ``webpack.prod.config.js`` + - Path to Webpack config file + - N/A + - N/A + + * - ``STATIC_ROOT_LMS`` + - ``test_root/staticfiles`` + - Path to which LMS's static assets will be collected + - ``STATIC_ROOT`` + - N/A + + * - ``STATIC_ROOT_CMS`` + - ``$STATIC_ROOT_LMS/studio``. + - Path to which CMS's static assets will be collected + - N/A + - ``STATIC_ROOT`` + + * - ``JS_ENV_EXTRA_CONFIG`` + - ``{}`` + - Global configuration object available to edx-platform JS modules. Specified as a JSON string. + Known keys: + + * ``TINYMCE_ADDITIONAL_PLUGINS`` + * ``TINYMCE_CONFIG_OVERRIDES`` + + - N/A + - N/A + +Build assets +************ + +Building frontend assets requires an active Node and Python environment with +dependencies installed:: + + npm clean-install + pip install -r requirements/edx/assets.txt + + +Once your environment variables are set and build dependencies are installed, +the one-sized-fits-all command to build assets is ``npm run build``. If +your needs are more advanced, though, you can use some combination of the +commands below: + +.. list-table:: + :header-rows: 1 + + * - Command + - Meaning + - Options + * - ``npm run build`` + - Combines ``npm run webpack`` and ``npm run compile-sass`` + - None + * - ``npm run build-dev`` + - Combines ``npm run webpack-dev`` and ``npm run compile-sass-dev`` + - None + * - ``npm run webpack`` + - Build JS bundles with Webpack + - Options are passed through to the `webpack CLI`_ + * - ``npm run webpack-dev`` + - Build JS bundles with Webpack for a development environment + - Options are passed through to the `webpack CLI`_ + * - ``npm run compile-sass`` + - Compile default and/or themed Sass + - Use ``--help`` to see available options + * - ``npm run compile-sass-dev`` + - Compile default and/or themed Sass, uncompressed with source comments + - Use ``--help`` to see available options + * - ``npm run watch`` + - Dev-only. Combine ``npm run watch-webpack`` and ``npm run watch-sass`` + - None. + * - ``npm run watch-webpack`` + - Dev-only. Wait for JS changes and re-run Webpack + - Options are passed through to the `webpack CLI`_ + * - ``npm run watch-sass`` + - Dev-only. Wait for Sass changes and re-compile + - None. + +When supplying options to these commands, separate the command from the options +with a double-hyphen (``--``), like this:: + + npm run compile-sass -- --themes-dir /my/custom/themes/dir + +Omitting the double-hyphen will pass the option to ``npm run`` itself, which +probably isn't what you want to do. + +If you would like to understand these more deeply, they are defined in +`package.json`_. Please note: the ``npm run`` command interfaces are stable and +supported, but their underlying implementations may change without notice. + +.. _webpack CLI: https://webpack.js.org/api/cli/ +.. _package.json: ../package.json + +Collect assets +************** + +Once assets are built, they can be *collected* into another directory for +efficient serving. This is only necessary on production sites; developers can +skip this section. + +First, ensure you have a Python enironment with all edx-platform dependencies +installed:: + + pip install -r requirements/edx/base.txt + +Next, download localized versions of edx-platform assets. Under the hood, this +command uses the `Open edX Atlas`_ tool, which manages aggregated translations +from edx-platform and its various plugins:: + + make pull_translations + +Finally, invoke `Django's collectstatic command`_, once for the Learning +Management System, and once for the Content Management Studio:: + + ./manage.py lms collectstatic --noinput + ./manage.py cms collectstatic --noinput + +The ``--noinput`` option lets you avoid having to type "yes" when overwriting +existing collected assets. + +.. _Open edX Atlas: https://github.com/openedx/openedx-atlas +.. _Django's collectstatic command: https://docs.djangoproject.com/en/dev/ref/contrib/staticfiles/#collectstatic