80 lines
3.9 KiB
Text
80 lines
3.9 KiB
Text
[[upgrading-nodejs]]
|
|
== Upgrading Node.js
|
|
|
|
{kib} requires a specific Node.js version to run.
|
|
When running {kib} from source, you must have this version installed locally.
|
|
|
|
The required version of Node.js is listed in several different files throughout the {kib} source code.
|
|
These files must be updated when upgrading Node.js:
|
|
|
|
- {kib-repo}blob/{branch}/.ci/Dockerfile[`.ci/Dockerfile`] - The version is specified in the `NODE_VERSION` constant.
|
|
This is used to pull the relevant image from https://hub.docker.com/_/node[Docker Hub].
|
|
Note that Docker Hub can take 24+ hours to be updated with the new images after a new release of Node.js, so if you're upgrading Node.js in Kibana just after the official Node.js release, you have to check if the new images are present on Docker Hub.
|
|
If they are not, and the update is urgent, you can skip this file and update it later once Docker Hub has been updated.
|
|
- {kib-repo}blob/{branch}/.node-version[`.node-version`]
|
|
- {kib-repo}blob/{branch}/.nvmrc[`.nvmrc`]
|
|
- {kib-repo}blob/{branch}/package.json[`package.json`] - The version is specified in the `engines.node` field.
|
|
- {kib-repo}blob/{branch}/WORKSPACE.bazel[`WORKSPACE.bazel`] - The version is specified in the `node_version` property.
|
|
Besides this property, the list of files under `node_repositories` must be updated along with their respective SHA256 hashes.
|
|
These can be found on the https://nodejs.org[nodejs.org] website.
|
|
Example for Node.js v14.16.1: https://nodejs.org/dist/v14.16.1/SHASUMS256.txt.asc
|
|
|
|
See PR {kib-repo}pull/96382[#96382] for an example of how the Node.js version has been upgraded previously.
|
|
|
|
In the 6.8 branch, neither the `.ci/Dockerfile` file nor the `WORKSPACE.bazel` file exists, so when upgrading Node.js in that branch, just skip those files.
|
|
|
|
=== Backporting
|
|
|
|
The following rules are not set in stone.
|
|
Use best judgement when backporting.
|
|
|
|
Currently version 7.11 and newer run Node.js 14, while 7.10 and older run Node.js 10.
|
|
Hence, upgrades to either Node.js 14 or Node.js 10 should be done as separate PRs.
|
|
|
|
==== Node.js patch upgrades
|
|
|
|
Typically, you want to backport Node.js *patch* upgrades to all supported release branches that run the same *major* Node.js version:
|
|
|
|
- If upgrading Node.js 14, and the current release is 7.11.1, the main PR should target `master` and be backported to `7.x` and `7.11`.
|
|
- If upgrading Node.js 10, the main PR should target `6.8` only.
|
|
|
|
==== Node.js minor upgrades
|
|
|
|
Typically, you want to backport Node.js *minor* upgrades to the next minor {kib} release branch that runs the same *major* Node.js version:
|
|
|
|
- If upgrading Node.js 14, and the current release is 7.11.1, the main PR should target `master` and be backported to `7.x`, while leaving the `7.11` branch as-is.
|
|
- If upgrading Node.js 10, the main PR should target `6.8` only.
|
|
|
|
=== Upgrading installed Node.js version
|
|
|
|
The following instructions expect that https://github.com/nvm-sh/nvm[nvm] is used to manage locally installed Node.js versions.
|
|
|
|
Run the following to install the new Node.js version. Replace `<version>` with the desired Node.js version:
|
|
|
|
[source,bash]
|
|
----
|
|
nvm install <version>
|
|
----
|
|
|
|
To get the same global npm modules installed with the new version of Node.js as is currently installed, use the `--reinstall-packages-from` command-line argument (optionally replace `14` with the desired source version):
|
|
|
|
[source,bash]
|
|
----
|
|
nvm install <version> --reinstall-packages-from=14
|
|
----
|
|
|
|
If needed, uninstall the old version of Node.js by running the following. Replace `<old-version>` with the full version number of the version that should be uninstalled:
|
|
|
|
[source,bash]
|
|
----
|
|
nvm uninstall <old-version>
|
|
----
|
|
|
|
Optionally, tell nvm to always use the "highest" installed Node.js 14 version. Replace `14` if a different major version is desired:
|
|
|
|
[source,bash]
|
|
----
|
|
nvm alias default 14
|
|
----
|
|
|
|
Alternatively, include the full version number at the end to specify a specific default version.
|