Install Node.js

When to use it

Before running a Node.js application, building front-end assets, or installing a process manager such as PM2. It installs the same official build on every distribution, so every server in a fleet runs exactly the same Node.js.

Choosing the options

Node.js version

• Node.js 24 (LTS) — the current long-term support release. Choose it for new applications.
• Node.js 22 (LTS, maintenance) — still receives security fixes. Choose it when your application or its dependencies do not support 24 yet.

Every server in a cluster or a deployment pipeline should run the same version.

Global npm packages — optional command-line tools installed with npm install -g for the chosen version, one per line or separated by commas, such as pm2 or yarn. Use package names as npm knows them; a version can be pinned with @, for example pm2@6.

What it does on the server

1. Checks that the server's glibc is 2.28 or newer, which the official builds need.
2. Downloads the chosen release from nodejs.org and checks it against the SHA-256 checksum published with that release. A mismatch stops the run before anything is installed.
3. Unpacks it into a folder named after the major version, /opt/iap/node/24 for Node.js 24.
4. Points node, npm, npx and corepack in /usr/local/bin at that version, so every account runs it.
5. Installs the global packages you named, and links their commands into /usr/local/bin.

A Node.js installed from the distribution's packages stays in place at /usr/bin/node; /usr/local/bin comes first on the PATH, so node runs the version this playbook installed. Another version installed by this playbook stays in /opt/iap/node and can be chosen again by running the playbook with that version.

After the run

The result shows the Node.js and npm versions. Run your application under a process manager such as PM2 (pm2 start app.js, then pm2 startup to keep it running after a reboot), or as a systemd service.

Common problems

"Node.js … needs glibc 2.28 or newer" — The server's distribution is too old for current Node.js builds. Upgrade the distribution or use a newer server.

"… already exists and was not put there by this playbook" — Something else installed node, npm or a global command in /usr/local/bin. The playbook never overwrites it. Remove the existing file if you want this playbook to manage it, or run the version it installed directly, for Node.js 24 from /opt/iap/node/24/bin.

"… is not a package name this playbook accepts." — Global package names are npm package names: lowercase letters, digits, -, ., _, an optional @scope/ and an optional @version.

"The Node.js … download did not match the checksum nodejs.org publishes for it." — The download was corrupted or altered on the way. Nothing was installed. Run the playbook again; if it fails again, check the server's network path to nodejs.org.