-
Notifications
You must be signed in to change notification settings - Fork 3.9k
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
docs: improve 'bare metal' docs and add static assets reference (#34678)
- Loading branch information
1 parent
8f4cbea
commit d39bd32
Showing
2 changed files
with
251 additions
and
13 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -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 |