Merge pull request #1413 from plone/install-reorg-1

Port Volto installation docs into the main Plone 6 Installation docs.

docs/conf.py

@@ -83,6 +83,7 @@
  r"https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors#Identifying_the_issue",
  r"https://github.com/browserslist/browserslist#queries",
  r"https://github.com/nodejs/release#release-schedule",
+ r"https://github.com/nvm-sh/nvm#install--update-script",
  r"https://github.com/plone/cookiecutter-zope-instance#options",
  r"https://github.com/plone/plone.app.contenttypes#migration",
  r"https://github.com/plone/plone.docker#for-basic-usage",
@@ -318,6 +319,7 @@ def source_replace(app, docname, source):
 source_replacements = {
  "{PLONE_BACKEND_MINOR_VERSION}": "6.0",
  "{PLONE_BACKEND_PATCH_VERSION}": "6.0.0.2",
+ "{NVM_VERSION}": "0.39.3",
 }
 
 

docs/glossary.md

@@ -254,8 +254,7 @@ Asynchronous JavaScript and XML
  The server will send a response back to the client, which is then rendered on the client side.
 
 Yeoman
- A popular scaffolding tool similar to Plone's `mr.bob` or `ZopeSkel`.
- https://yeoman.io/
+ [Yeoman](https://yeoman.io/) is a popular scaffolding tool similar to Plone's `mr.bob` or `ZopeSkel`.
 
 CommonJS
  A JavaScript package standard, the equivalent of a Python wheel or egg.
@@ -501,6 +500,7 @@ Zope
 
 Make
 make
+GNU make
  [GNU Make](https://www.gnu.org/software/make/) is a tool which controls the generation of executables and other non-source files of a program from the program's source files.
 
  Make gets its knowledge of how to build your program from a file called the _makefile_, which lists each of the non-source files and how to compute it from other files.
@@ -576,4 +576,11 @@ Factory Type Information
  ```{seealso}
  [`FactoryTypeInformation` class source code](https://github.com/zopefoundation/Products.CMFCore/blob/361a30e0c72a15a21f88433b8d5fc49331f36728/src/Products/CMFCore/TypesTool.py#L431)
  ```
+
+`nvm`
+Node Version Manager
+ [`nvm`](https://github.com/nvm-sh/nvm/blob/master/README.md) allows you to quickly install and use different versions of node via the command line.
+
+Node.js
+ [Node.js®](https://nodejs.org/en/) is an open-source, cross-platform JavaScript runtime environment.
 ```

docs/install/install-from-packages.md

@@ -37,33 +37,142 @@ You may host multiple Plone sites on the same server.
 
 ### Pre-requisites for installation
 
-- Python 3.8, 3.9, or 3.10.
-- Cookiecutter
-- Node.JS
-- nvm
-- Yeoman
-- Yarn
-- GNU make
+- [Python](https://www.python.org/downloads/) 3.8, 3.9, or 3.10.
+- {term}`Cookiecutter`
+- {term}`nvm`
+- {term}`Node.js` LTS 16.x (see "Update" note)
+- {term}`Yeoman`
+- {term}`Yarn`
+- {term}`GNU make`
+
+````{note}
+Update
+: [Node.js 18 is in LTS state as of 2022-10-25](https://github.com/nodejs/release#release-schedule), and Node.js 16 is now in maintenance mode.
+ However, due to changes in internal SSL libraries, some Volto dependencies have been deprecated and need to be updated in order to continue working in Node.js 18, mainly [Webpack 4](https://github.com/webpack/webpack/issues/14532#issuecomment-947525539).
+ You can still use it, but Node.js should be run under a special flag: `NODE_OPTIONS=--openssl-legacy-provider`.
+
+ ```{seealso}
+ Volto's pull request, [Support Node 18](https://github.com/plone/volto/pull/3699).
+ ```
+````
+
+
+(install-prerequisites-python-label)=
+
+#### Python
 
 Installing Python is beyond the scope of this documentation.
 However, it is recommended to use a Python version manager, [`pyenv`](https://github.com/pyenv/pyenv) that allows you to install multiple versions of Python on your development environment without destroying your system's Python.
 
+
+(install-prerequisites-cookiecutter-label)=
+
+#### Cookiecutter
+
 Install or upgrade {term}`Cookiecutter` in your user's Python:
 
 ```shell
 pip install --user --upgrade cookiecutter
 ```
 
-{ref}`Install nvm and Node.js documentation <frontend-getting-started-install-nvm-label>`.
 
-{ref}`Install Yeoman documentation <frontend-getting-started-yeoman-label>`.
+(install-prerequisites-nvm-label)=
+
+#### nvm
+
+The following terminal session commands use `bash` for the shell.
+Adapt them for your flavor of shell.
+
+```{seealso}
+See the [`nvm` install and update script documentation](https://github.com/nvm-sh/nvm#install--update-script).
+For the `fish` shell, see [`nvm.fish`](https://github.com/jorgebucaran/nvm.fish).
+```
+
+1. Create your shell profile, if it does not exist.
+
+ ```shell
+ touch ~/.bash_profile
+ ```
+
+2. Download and run the `nvm` install and update script, and pipe it into `bash`.
+
+ ```shell
+ curl -o- https://raw.githubusercontent.com/creationix/nvm/v{NVM_VERSION}/install.sh | bash
+ ```
+
+3. Source your profile.
+ Alternatively close the session and open a new one.
+
+ ```shell
+ source ~/.bash_profile
+ ```
+
+4. Verify that the `nvm` version is that which you just installed or updated:
+
+ ```shell
+ nvm --version
+ ```
+
+
+(install-prerequisites-nodejs-label)=
+
+#### Node.js
 
-{ref}`Install Yarn documentation <frontend-getting-started-yarn-label>`.
+1. Install or update the supported LTS version of Node.js.
+ This command also activates that version.
+
+ ```shell
+ nvm install 16
+ ```
+
+2. Verify that the supported version of Node.js is activated.
+
+ ```shell
+ node -v
+ ```
+
+
+(install-prerequisites-yeoman-label)=
+
+#### Yeoman
+
+Install {term}`Yeoman`.
+
+```shell
+npm install -g yo
+```
+
+
+(install-prerequisites-yarn-label)=
+
+#### Yarn
+
+Install the Yarn Classic version (not the latest 2.x one) using `npm`.
+
+1. Open a terminal and type:
+
+ ```shell
+ npm install yarn@1
+ ```
+
+2. Verify that Yarn v1.x.x is installed and activated.
+
+ ```shell
+ yarn -v
+ ```
+
+
+(install-prerequisites-make-label)=
+
+#### Make
 
 {term}`Make` comes installed on most Linux distributions.
 On macOS, you must first [install Xcode](https://developer.apple.com/xcode/resources/), then install its command line tools.
 On Windows, it is strongly recommended to [Install Linux on Windows with WSL](https://learn.microsoft.com/en-us/windows/wsl/install), which will include `make`.
 
+Finally, it is a good idea to update your system's version of `make`, because some distributions, especially macOS, have an outdated version.
+Use your favorite search engine or trusted online resource for how to update `make`.
+
 
 (install-packages-install-label)=