Elastic Docs ›Kibana Guide ›Developer guide ›Advanced
« Considerations for basepath Sharing saved objects »

Upgrading Node.jsedit

Kibana requires a specific Node.js version to run. When running Kibana from source, you must have this version installed locally.

The required version of Node.js is listed in several different files throughout the Kibana source code. These files must be updated when upgrading Node.js:

  • .ci/Dockerfile - The version is specified in the NODE_VERSION constant. This is used to pull the relevant image from 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.
  • .node-version
  • .nvmrc
  • package.json - The version is specified in the engines.node field (if possible, also upgrade @types/node to match the new version, both under devDependencies and resolutions).
  • 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 nodejs.org website. Example for Node.js v18.17.1: https://nodejs.org/dist/v18.17.1/SHASUMS256.txt.asc

See PR #128123 for an example of how the Node.js version has been upgraded previously.

Considerations with major Node.js upgradesedit

When upgrading to a new major version of Node.js, the following extra steps must be performed:

  • Compare the new Node.js versions list of supported platforms with the Kibana Support Matrix. As an example, here’s the Node.js 18 supported platform list. You can change which Node.js major version to view, by changing the selected branch. If Node.js has dropped support for platform still supported by Kibana, appropriate steps must be taken as soon as possible to deprecate support for this platform. This way support for it can be dropped before the currently used major version of Node.js reaches End-of-Life.

Custom builds of Node.jsedit

Due to Node.js 16 coming to an early End-of-Life and Node.js 18 no longer supporting the same platforms that Kibana supports (most notably CentOS7/RHEL7), we cannot bundle the official Node.js binaries with the Linux distributable of Kibana. To keep support for these older platforms, we’re bundling the Linux distributable of Kibana with a custom build of Node.js with extended backwards compatibility. The only difference between the offical Node.js build and our custom build, is the version of glibc that it’s compiled against.

Backportingedit

The following rules are not set in stone. Use best judgement when backporting.

Node.js patch upgradesedit

Typically, you want to backport Node.js patch upgrades to all supported release branches that run the same major Node.js version (which currently is all of them, but this might change in the future):

  • If the current release is 8.1.x, the main PR should target main and be backported to 7.17 and 8.1 (GitHub tag example: backport:all-open).

Node.js minor upgradesedit

Typically, you want to backport Node.js minor upgrades to the previous major Kibana release branch (if it runs the same major Node.js version):

  • If the current release is 8.1.x, the main PR should target main and be backported to 7.17, while leaving the 8.1 branch as-is (GitHub tag example: auto-backport + v7.17.13).

Node.js major upgradesedit

Typically, you want to backport Node.js major upgrades to the previous major Kibana release branch:

  • If the current release is 8.1.x, the main PR should target main and be backported to 7.17, while leaving the 8.1 branch as-is (GitHub tag example: auto-backport + v7.17.13).

Upgrading installed Node.js versionedit

The following instructions expect that 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:

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 16 with the desired source version):

nvm install <version> --reinstall-packages-from=16

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:

nvm uninstall <old-version>

Optionally, tell nvm to always use the "highest" installed Node.js 16 version. Replace 16 if a different major version is desired:

nvm alias default 16

Alternatively, include the full version number at the end to specify a specific default version.

« Considerations for basepath Sharing saved objects »