.. Document meta
:orphan:
.. |antsibull-internal-nbsp| unicode:: 0xA0
:trim:
.. meta::
:antsibull-docs: 2.24.0
.. Anchors
.. _ansible_collections.princeton_cdh.cdh.nodejs_role:
.. Title
nodejs
======
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__entrypoint-main:
.. version_added
.. Deprecated
Synopsis
--------
.. Description
- Installs a pinned Node.js release from a prebuilt tarball served by the PUL mirror, optionally enables Corepack\-managed Yarn, runs npm dependency installs, and executes Webpack builds with configurable per\-environment scripts.
- The distro\-packaged :literal:`nodejs` is removed by default to avoid PATH shadowing (see :ansopt:`princeton\_cdh.cdh.nodejs#role:main:nodejs\_remove\_apt\_node`\ ).
.. Requirements
.. Options
Parameters
----------
.. tabularcolumns:: \X{1}{3}\X{2}{3}
.. list-table::
:width: 100%
:widths: auto
:header-rows: 1
:class: longtable ansible-option-table
* - Parameter
- Comments
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__deploy:
.. rst-class:: ansible-option-title
**deploy**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`string`
.. raw:: html
- .. raw:: html
Deploy directory path set by the :literal:`deploy` role. Used as the ultimate fallback for :ansopt:`princeton\_cdh.cdh.nodejs#role:main:nodejs\_npm\_install\_path`.
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__deploy_user:
.. rst-class:: ansible-option-title
**deploy_user**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`string`
.. raw:: html
- .. raw:: html
Deployment user name set by the :literal:`deploy\_user` role. Used as the first fallback for :ansopt:`princeton\_cdh.cdh.nodejs#role:main:nodejs\_build\_user`.
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__desired_nodejs_version:
.. rst-class:: ansible-option-title
**desired_nodejs_version**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`string`
.. raw:: html
- .. raw:: html
Legacy variable name that :ansopt:`princeton\_cdh.cdh.nodejs#role:main:nodejs\_version` falls back to. Set this during migration; prefer :ansopt:`princeton\_cdh.cdh.nodejs#role:main:nodejs\_version` for new work.
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__django_user:
.. rst-class:: ansible-option-title
**django_user**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`string`
.. raw:: html
- .. raw:: html
Legacy application user name. Used as the second fallback for :ansopt:`princeton\_cdh.cdh.nodejs#role:main:nodejs\_build\_user` when :ansopt:`princeton\_cdh.cdh.nodejs#role:main:deploy\_user` is not set.
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__nodejs_build_user:
.. rst-class:: ansible-option-title
**nodejs_build_user**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`string`
.. raw:: html
- .. raw:: html
Unix user that owns the npm/webpack build steps. Falls back to :ansopt:`princeton\_cdh.cdh.nodejs#role:main:deploy\_user`\ , then :ansopt:`princeton\_cdh.cdh.nodejs#role:main:django\_user`\ , then :ansval:`root`.
.. rst-class:: ansible-option-line
:ansible-option-default-bold:`Default:` :ansible-option-default:`""`
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__nodejs_download_delay:
.. rst-class:: ansible-option-title
**nodejs_download_delay**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`integer`
.. raw:: html
- .. raw:: html
Delay in seconds between download retries.
.. rst-class:: ansible-option-line
:ansible-option-default-bold:`Default:` :ansible-option-default:`10`
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__nodejs_download_retries:
.. rst-class:: ansible-option-title
**nodejs_download_retries**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`integer`
.. raw:: html
- .. raw:: html
Number of retries for the Node.js tarball download.
.. rst-class:: ansible-option-line
:ansible-option-default-bold:`Default:` :ansible-option-default:`6`
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__nodejs_download_timeout:
.. rst-class:: ansible-option-title
**nodejs_download_timeout**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`integer`
.. raw:: html
- .. raw:: html
Timeout in seconds for the Node.js tarball download.
.. rst-class:: ansible-option-line
:ansible-option-default-bold:`Default:` :ansible-option-default:`600`
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__nodejs_install_method:
.. rst-class:: ansible-option-title
**nodejs_install_method**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`string`
.. raw:: html
- .. raw:: html
Installation method. Currently only :ansval:`prebuilt` (download a tarball from the PUL mirror) is supported.
.. rst-class:: ansible-option-line
:ansible-option-default-bold:`Default:` :ansible-option-default:`"prebuilt"`
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__nodejs_npm_enabled:
.. rst-class:: ansible-option-title
**nodejs_npm_enabled**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`boolean`
.. raw:: html
- .. raw:: html
Run an npm dependency install step (used by the :literal:`build\_npm` workflow).
.. rst-class:: ansible-option-line
:ansible-option-choices:`Choices:`
- :ansible-option-choices-entry-default:`false` :ansible-option-choices-default-mark:`← (default)`
- :ansible-option-choices-entry:`true`
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__nodejs_npm_install_mode:
.. rst-class:: ansible-option-title
**nodejs_npm_install_mode**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`string`
.. raw:: html
- .. raw:: html
npm install strategy. :ansval:`production` runs :literal:`npm install \-\-production`\ , :ansval:`ci` runs :literal:`npm ci`\ , :ansval:`dev` runs :literal:`npm install` including devDependencies.
.. rst-class:: ansible-option-line
:ansible-option-default-bold:`Default:` :ansible-option-default:`"production"`
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__nodejs_npm_install_path:
.. rst-class:: ansible-option-title
**nodejs_npm_install_path**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`string`
.. raw:: html
- .. raw:: html
Target directory for :literal:`npm install`. Falls back to :ansopt:`princeton\_cdh.cdh.nodejs#role:main:npm\_install\_path` then :ansopt:`princeton\_cdh.cdh.nodejs#role:main:deploy`.
.. rst-class:: ansible-option-line
:ansible-option-default-bold:`Default:` :ansible-option-default:`""`
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__nodejs_prefix_root:
.. rst-class:: ansible-option-title
**nodejs_prefix_root**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`string`
.. raw:: html
- .. raw:: html
Installation prefix. Node.js binaries are placed under :literal:`{{ nodejs\_prefix\_root }}/bin`.
.. rst-class:: ansible-option-line
:ansible-option-default-bold:`Default:` :ansible-option-default:`"/usr/local"`
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__nodejs_release_base_url:
.. rst-class:: ansible-option-title
**nodejs_release_base_url**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`string`
.. raw:: html
- .. raw:: html
Base URL for the Node.js tarball mirror. Override only when using a local or alternative mirror.
.. rst-class:: ansible-option-line
:ansible-option-default-bold:`Default:` :ansible-option-default:`"https://pulmirror.princeton.edu/mirror/nodejs"`
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__nodejs_remove_apt_node:
.. rst-class:: ansible-option-title
**nodejs_remove_apt_node**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`boolean`
.. raw:: html
- .. raw:: html
When :ansval:`true`\ , remove the distro\-packaged :literal:`nodejs` apt package before installing the prebuilt release to prevent PATH conflicts.
.. rst-class:: ansible-option-line
:ansible-option-choices:`Choices:`
- :ansible-option-choices-entry:`false`
- :ansible-option-choices-entry-default:`true` :ansible-option-choices-default-mark:`← (default)`
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__nodejs_version:
.. rst-class:: ansible-option-title
**nodejs_version**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`string`
.. raw:: html
- .. raw:: html
Node.js release to install. Accepts both :literal:`"22.4.0"` and :literal:`"v22.4.0"` formats. Falls back to :ansopt:`princeton\_cdh.cdh.nodejs#role:main:desired\_nodejs\_version` when set (legacy group\_vars migration path).
.. rst-class:: ansible-option-line
:ansible-option-default-bold:`Default:` :ansible-option-default:`"22.4.0"`
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__nodejs_webpack_build_commands:
.. rst-class:: ansible-option-title
**nodejs_webpack_build_commands**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`dictionary`
.. raw:: html
- .. raw:: html
Mapping of :literal:`runtime\_env` name to the npm script invoked by Webpack. Extend per\-app in :literal:`group\_vars`. Defaults map :ansval:`staging` to :literal:`build:qa` and :ansval:`production`\ /\ :ansval:`preproduction` to :literal:`build:prod`.
.. rst-class:: ansible-option-line
:ansible-option-default-bold:`Default:` :ansible-option-default:`{"preproduction": "build:prod", "production": "build:prod", "staging": "build:qa"}`
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__nodejs_webpack_debug:
.. rst-class:: ansible-option-title
**nodejs_webpack_debug**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`boolean`
.. raw:: html
- .. raw:: html
Enable verbose Webpack build output for troubleshooting.
.. rst-class:: ansible-option-line
:ansible-option-choices:`Choices:`
- :ansible-option-choices-entry-default:`false` :ansible-option-choices-default-mark:`← (default)`
- :ansible-option-choices-entry:`true`
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__nodejs_webpack_enabled:
.. rst-class:: ansible-option-title
**nodejs_webpack_enabled**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`boolean`
.. raw:: html
- .. raw:: html
Run a Webpack build step after npm install.
.. rst-class:: ansible-option-line
:ansible-option-choices:`Choices:`
- :ansible-option-choices-entry-default:`false` :ansible-option-choices-default-mark:`← (default)`
- :ansible-option-choices-entry:`true`
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__nodejs_webpack_stats_check:
.. rst-class:: ansible-option-title
**nodejs_webpack_stats_check**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`boolean`
.. raw:: html
- .. raw:: html
When :ansval:`true`\ , verify that :literal:`webpack\-stats.json` exists after the build. Set to :ansval:`false` if the app does not use :literal:`webpack\-bundle\-tracker`.
.. rst-class:: ansible-option-line
:ansible-option-choices:`Choices:`
- :ansible-option-choices-entry:`false`
- :ansible-option-choices-entry-default:`true` :ansible-option-choices-default-mark:`← (default)`
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__nodejs_webpack_stats_default:
.. rst-class:: ansible-option-title
**nodejs_webpack_stats_default**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`string`
.. raw:: html
- .. raw:: html
Computed default path for :literal:`webpack\-stats.json`\ , typically :literal:`{{ nodejs\_npm\_install\_path }}/sitemedia/webpack\-stats.json`.
.. rst-class:: ansible-option-line
:ansible-option-default-bold:`Default:` :ansible-option-default:`""`
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__nodejs_webpack_stats_file:
.. rst-class:: ansible-option-title
**nodejs_webpack_stats_file**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`string`
.. raw:: html
- .. raw:: html
Explicit path to :literal:`webpack\-stats.json`. When empty, the role uses :ansopt:`princeton\_cdh.cdh.nodejs#role:main:nodejs\_webpack\_stats\_default`.
.. rst-class:: ansible-option-line
:ansible-option-default-bold:`Default:` :ansible-option-default:`""`
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__nodejs_yarn_enabled:
.. rst-class:: ansible-option-title
**nodejs_yarn_enabled**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`boolean`
.. raw:: html
- .. raw:: html
Enable Corepack\-managed Yarn (Berry). Classic Yarn via apt is not supported by this role.
.. rst-class:: ansible-option-line
:ansible-option-choices:`Choices:`
- :ansible-option-choices-entry-default:`false` :ansible-option-choices-default-mark:`← (default)`
- :ansible-option-choices-entry:`true`
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__nodejs_yarn_version:
.. rst-class:: ansible-option-title
**nodejs_yarn_version**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`string`
.. raw:: html
- .. raw:: html
Yarn release version to activate via Corepack.
.. rst-class:: ansible-option-line
:ansible-option-default-bold:`Default:` :ansible-option-default:`"4.15.0"`
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__npm_install_path:
.. rst-class:: ansible-option-title
**npm_install_path**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`string`
.. raw:: html
- .. raw:: html
Alternate name for :ansopt:`princeton\_cdh.cdh.nodejs#role:main:nodejs\_npm\_install\_path` used by legacy group\_vars. :ansopt:`princeton\_cdh.cdh.nodejs#role:main:nodejs\_npm\_install\_path` falls back to this when not set directly.
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__webpack_build_prod:
.. rst-class:: ansible-option-title
**webpack_build_prod**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`string`
.. raw:: html
- .. raw:: html
Legacy override for the :ansval:`production` and :ansval:`preproduction` entries in :ansopt:`princeton\_cdh.cdh.nodejs#role:main:nodejs\_webpack\_build\_commands`. Prefer setting :ansopt:`princeton\_cdh.cdh.nodejs#role:main:nodejs\_webpack\_build\_commands` directly.
.. raw:: html
* - .. raw:: html
.. _ansible_collections.princeton_cdh.cdh.nodejs_role__parameter-main__webpack_build_qa:
.. rst-class:: ansible-option-title
**webpack_build_qa**
.. raw:: html
.. ansible-option-type-line::
:ansible-option-type:`string`
.. raw:: html
- .. raw:: html
Legacy override for the :ansval:`staging` entry in :ansopt:`princeton\_cdh.cdh.nodejs#role:main:nodejs\_webpack\_build\_commands`. Prefer setting :ansopt:`princeton\_cdh.cdh.nodejs#role:main:nodejs\_webpack\_build\_commands` directly.
.. raw:: html
.. Attributes
.. Notes
.. Seealso
Authors
-------
- Center for Digital Humanities @ Princeton
.. Extra links
Collection links
----------------
.. ansible-links::
- title: "Repository (Sources)"
url: "https://github.com/Princeton-CDH/cdh-ansible"
external: true
.. Parsing errors