Skip to content

Commit

Permalink
[docs] add info on how to generate custom Node.js builds (elastic#168919
Browse files Browse the repository at this point in the history
)

Co-authored-by: amyjtechwriter <[email protected]>
  • Loading branch information
Thomas Watson and amyjtechwriter authored Oct 17, 2023
1 parent a304007 commit 916ecf6
Showing 1 changed file with 15 additions and 2 deletions.
17 changes: 15 additions & 2 deletions docs/developer/advanced/upgrading-nodejs.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,12 @@
{kib} requires a specific Node.js version to run.
When running {kib} from source, you must have this version installed locally.

=== Step 1: Generate custom Node.js builds

Before making a PR to upgrade Node.js, we must first <<start-new-nodejs-build,generate the required custom Node.js builds>> matching the desired Node.js version.

=== Step 2: Create PR to upgrade Node.js

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:

Expand All @@ -16,8 +22,8 @@ These files must be updated when upgrading Node.js:
- {kib-repo}blob/{branch}/package.json[`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`).
- {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 v18.18.2: https://nodejs.org/dist/v18.18.2/SHASUMS256.txt.asc
These can be found in the `SHASUMS256.txt` file inside the public `kibana-custom-node-artifacts` GCP bucket.
Example for Node.js v18.18.2: https://storage.googleapis.com/kibana-custom-node-artifacts/node-glibc-217/dist/v18.18.2/SHASUMS256.txt[kibana-custom-node-artifacts/node-glibc-217/dist/v18.18.2/SHASUMS256.txt]

See PR {kib-repo}pull/128123[#128123] for an example of how the Node.js version has been upgraded previously.

Expand All @@ -37,6 +43,13 @@ Due to Node.js 16 coming to an https://nodejs.org/en/blog/announcements/nodejs16
To keep support for these older platforms, we're bundling the Linux distributable of {kib} with a https://github.com/elastic/kibana-custom-nodejs-builds[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.

[[start-new-nodejs-build]]
==== How to start a new build

To generate a new custom Node.js build, https://buildkite.com/elastic/kibana-custom-node-dot-js-builds#new[start a new build] on our dedicated Buildkite pipeline (requires Elastic employee permissions).
Give it a clear name (e.g. `Node 18.18.2`) and remember so set the custom `OVERRIDE_TARGET_VERSION` environment variable to the desired Node.js version - e.g. `OVERRIDE_TARGET_VERSION=18.18.2`.
You find the "Environment Variables" field by expanding "Options >" in the "New Build" dialog.

=== Backporting

The following rules are not set in stone.
Expand Down

0 comments on commit 916ecf6

Please sign in to comment.