Install languages and application dependencies
Who acts: you, or your coding agent, in your MMX project on your
controller machine: the computer where you run mmx.
When to use this page: an application on your servers needs a
language, such as Node.js, Python, or Ruby, and the packages that the
application lists in its own files, such as package-lock.json or
requirements.txt.
What this page does: you install Node.js and a small Node.js
application, shop-api, with the packages that its lock file lists, and
restart the application when the installed packages change. Later parts install Python
packages into a virtual environment, and install a language version that
no distribution package offers, with a version manager such as nvm,
rbenv, or uv.
Terms:
- A node is a server that MMX manages. A playbook in
playbooks/lists fleet stages. Each fleet stage picks nodes, and each of those nodes runs the fleet stage's node tasks, in order. A node task names one module, the code that does the work, such asapt_package. - A node task block groups a change with what follows it:
changesmakes the change,activateputs the change into use, andverifychecks it. Asystemd_servicenode task inactivaterestarts its service when something inchangeschanged. - A lock file lists the exact version of each package that an
application uses, such as
package-lock.jsonfor npm orGemfile.lockfor Bundler. The developer creates the lock file on their own computer, and the lock file goes into the application's repository. - A version manager is a tool that installs several versions of one language side by side, such as nvm for Node.js or rbenv for Ruby.
| What the application needs | Where |
|---|---|
| The packages that its lock file lists, with the language from the distribution's packages | Steps |
The packages of a requirements.txt, in a Python virtual environment |
Python packages in a virtual environment |
| A language version that no package offers | A language version that no package offers |
| One named package, such as a command-line tool from pip, RubyGems, npm, or the Snap Store | One named package |
Before you start
- You have an MMX project, as in Get started, with
the group
web_serversininventories/example.yml: the serversweb01at203.0.113.11, which runs Debian 13, andweb02at203.0.113.12, which runs Ubuntu 26.04. - The examples install with
apt_package, for Debian and Ubuntu. On Fedora, Rocky Linux, or AlmaLinux, usednf_package, and check the package names there. Reuse work with roles shows one role that works with apt and with dnf. - The application's lock file is in the application's files. Without a lock file, the module refuses to install, as If something is different shows.
Steps
-
Put the application into the project. Create
files/shop-api/in the project, with three files.server.jsanswers on port 3000 and says which Node.js version runsserver.js:// files/shop-api/server.js const express = require("express"); const app = express(); app.get("/", (request, response) => { response.send(`Shop API on Node.js ${process.version}\n`); }); app.listen(3000, "127.0.0.1");package.jsonlists the one package thatserver.jsuses:{ "name": "shop-api", "version": "1.0.0", "private": true, "main": "server.js", "dependencies": { "express": "^5.1.0" } }On your computer, with Node.js and npm installed, create
package-lock.jsonbesidepackage.json:cd files/shop-api npm install --package-lock-onlyReason: this page copies the application from the project, so the example needs no Git server. An application in a Git repository arrives with a
gitnode task instead. The exampledeploy-from-git-with-release-directoriesshows that way.Check:
ls files/shop-apilistspackage-lock.json,package.json, andserver.js. -
Install Node.js, and add an account for the application. Create
playbooks/set_up_shop_api.yml:# playbooks/set_up_shop_api.yml fleet_stages: - id: set_up_shop_api nodes: web_servers node_tasks: - id: install_nodejs apt_package: packages: - {name: nodejs, version: newest_when_first_installed} - {name: npm, version: newest_when_first_installed} - id: create_shop_group group: name: shop system: true - id: create_shop_account user: name: shop primary_group: shop system: true home: /srv/shop-api create_home_directory: false shell: /usr/sbin/nologinReason: npm can run code from the packages that npm installs. So the application's own account runs npm, not root, and the account cannot log in.
Check:
mmx validate set_up_shop_apiprintsValid: mmx_example. -
Add the application as a node task block. Add this node task block below
create_shop_account, at the same indent:- task_block: id: shop_api changes: - id: copy_application directory: path: /srv/shop-api source: files/shop-api # a directory in the project owner: shop group: shop - id: install_dependencies npm_project_dependencies: lock_file_dir: /srv/shop-api run_as_user_account: shop include_development_dependencies: false - id: write_service_unit systemd_unit: name: shop-api.service content: | [Unit] Description=Shop API [Service] User=shop WorkingDirectory=/srv/shop-api ExecStart=/usr/bin/node /srv/shop-api/server.js [Install] WantedBy=multi-user.target activate: - id: restart_shop_api systemd_service: name: shop-api start_at_boot: true state: running verify: - id: check_shop_api wait_for: url_responds: http://127.0.0.1:3000/ response_body_contains: Shop APInpm_project_dependenciesrunsnpm ciinlock_file_diras the accountshop.npm ciinstalls exactly whatpackage-lock.jsonlists into/srv/shop-api/node_modules, and never changes the lock file.include_development_dependencies: falseleaves out the packages underdevDependenciesinpackage.json. Because each node task inchangescounts,restart_shop_apirestarts the application when the files, the installed packages, or the unit changed.Check:
mmx validate set_up_shop_apiprintsValid: mmx_example. The whole file now reads:# playbooks/set_up_shop_api.yml fleet_stages: - id: set_up_shop_api nodes: web_servers node_tasks: - id: install_nodejs apt_package: packages: - {name: nodejs, version: newest_when_first_installed} - {name: npm, version: newest_when_first_installed} - id: create_shop_group group: name: shop system: true - id: create_shop_account user: name: shop primary_group: shop system: true home: /srv/shop-api create_home_directory: false shell: /usr/sbin/nologin - task_block: id: shop_api changes: - id: copy_application directory: path: /srv/shop-api source: files/shop-api owner: shop group: shop - id: install_dependencies npm_project_dependencies: lock_file_dir: /srv/shop-api run_as_user_account: shop include_development_dependencies: false - id: write_service_unit systemd_unit: name: shop-api.service content: | [Unit] Description=Shop API [Service] User=shop WorkingDirectory=/srv/shop-api ExecStart=/usr/bin/node /srv/shop-api/server.js [Install] WantedBy=multi-user.target activate: - id: restart_shop_api systemd_service: name: shop-api start_at_boot: true state: running verify: - id: check_shop_api wait_for: url_responds: http://127.0.0.1:3000/ response_body_contains: Shop API -
Preview the playbook.
mmx dryrun set_up_shop_api echo "exit code $?"Check: the exit code is 3, and the lines for the installation say
not_checked, because Node.js, the account, and the application's directory do not exist yet. Part of the output forweb01:set_up_shop_api / web01 / create_shop_account: not_checked, unknown — group shop does not exist yet. The earlier node task install_nodejs would change this node first and may provide what is missing; if the run then succeeds, change nothing. ... set_up_shop_api / web01 / shop_api/changes/install_dependencies: not_checked, unknown — the lock file directory /srv/shop-api does not exist yet; an earlier task, such as a git checkout, may create it. The earlier node task install_nodejs would change this node first and may provide what is missing; if the run then succeeds, change nothing.A dryrun installs nothing, so the dryrun cannot check what depends on an earlier node task. Preview and run changes explains
not_checked. -
Run the playbook.
mmx run set_up_shop_apiCheck: each node task says
succeeded, and the run ends withRun ...: succeededand exit code 0. On a first run, the lines for the installation and the restart read:set_up_shop_api / web01 / shop_api/changes/install_dependencies: succeeded, changed — installed: there is no record of an earlier installation {"lock_file":"package-lock.json"} ... set_up_shop_api / web01 / shop_api/activate/restart_shop_api: succeeded, changed — service is not running set_up_shop_api / web01 / shop_api/verify/check_shop_api: succeeded, unchangedservice is not runningmeans that MMX started the application for the first time. On Debian 13, installingnpmbrings several hundred small packages, so the first run took about twelve minutes. Ask each server for the page:mmx run-command --nodes web_servers -- curl -s http://127.0.0.1:3000/run-command / web01 / command: succeeded, changed Shop API on Node.js v20.19.2 run-command / web02 / command: succeeded, changed Shop API on Node.js v22.22.1Each server runs the Node.js of its own distribution: version 20 on Debian 13, and version 22 on Ubuntu 26.04.
-
Run the playbook again.
mmx run set_up_shop_apiCheck: each node task says
unchanged, andrestart_shop_apirestarts nothing. The installation is unchanged because nothing that the installation depends on changed, as When a lock file module installs again explains. -
Change the application, and run once more. A new release of the application brings a new
package.jsonorpackage-lock.json. For this example, change"version": "1.0.0"to"version": "1.0.1"infiles/shop-api/package.json, then run:mmx run set_up_shop_apiCheck: npm installs again, and the application restarts once:
set_up_shop_api / web01 / shop_api/changes/install_dependencies: succeeded, changed — installed: package.json changed since the last installation ... set_up_shop_api / web01 / shop_api/activate/restart_shop_api: succeeded, changed — installed software version changedIf the run stops between the installation and the restart, the next run still restarts the application, as A run that stopped before the reload explains.
Module pages that rely on this section: bundler_project_dependencies, composer_project_dependencies, npm_project_dependencies, uv_project_dependencies, yarn_project_dependencies.
What the installer modules share
Nine modules install software with a language's or a tool's own
installer. Each runs that installer program on the node, so the program
must be on the node: an earlier node task installs the program when the
distribution does not, as install_nodejs does above.
- Modules that install what a lock file lists:
npm_project_dependencies(package-lock.json),yarn_project_dependencies(yarn.lock),bundler_project_dependencies(Gemfile.lock),composer_project_dependencies(composer.lock), anduv_project_dependencies(uv.lock). The node task names the application's directory, and the lock file in that directory says what to install. - Modules that install named packages:
pip_package,gem_package,npm_global_package, andsnap_package. The node task names what to install.pip_packagealso takes arequirements.txt.
They share these settings and rules:
| Setting or rule | What it does |
|---|---|
run_as_user_account: shop |
The account that runs the installer, started directly as that account. The setting is required in every installer module except snap_package, because installers can run code from the packages they install. Write run_as_user_account: root to run the installer as root, so the choice is visible in review. snap_package has no such setting: root installs snaps. |
npm_program_path: /opt/nvm/versions/node/v24.22.0/bin/npm |
The installer program, when it is not the one on the standard path, such as Node.js from nvm. The other modules name theirs python_program_path, gem_program_path, yarn_program_path, bundle_program_path, composer_program_path, and uv_program_path. The path must be absolute. Its directory comes first in PATH, so npm finds the node beside it. |
env: {NPM_CONFIG_REGISTRY: https://npm.example.com/} |
Environment variables for the installer, such as a token for a private package server. The values may be secrets. snap_package has no env. |
| Nothing to do | The node task is unchanged when the installer has nothing to do. The modules for named packages report each change in the result as {name, from, to}. |
| Restarts | In a node task block's changes, what a node task installed counts as a change: a systemd_service in activate restarts when the installed software changed. A lock file module counts its record, as When a lock file module installs again explains. A module for named packages asks the installer what is installed, with the node task's env and account, so software installed under GEM_HOME or NPM_CONFIG_PREFIX counts too. |
| A missing installer | A run fails the node task without another try, and names the package that provides the program. A dryrun reports the node task not_checked, because an earlier node task may install the program. |
mmx describe-module npm_project_dependencies prints each module's own
inputs.
When a lock file module installs again
After a successful installation, the module writes a record into the
lock file's directory, such as /srv/shop-api/.mmx-npm-project-dependencies.
The record holds:
- the SHA-256 of the lock file, and of the manifest beside it: the file
that lists the application's requirements, such as
package.json,Gemfile,composer.json, orpyproject.toml - the node task's settings
- the versions of the installer and of the language runtime
The node task stays unchanged while the record matches and the
installed packages still exist, such as node_modules, Bundler's gems
directory, Composer's vendor, or uv's .venv. These install again:
- a changed lock file or manifest, as in step 7
- a changed setting of the node task
- a new version of the installer or the runtime, such as
installed: the installer or language runtime version changed since the last installation: now npm 11.19.1, v24.22.0; previously npm 9.2.0, v20.19.2 - an installation that was interrupted
Each lock file module runs its installer in the mode that installs exactly
what the lock file lists and never rewrites the lock file. A missing lock
file fails the node task. A dryrun names which of the reinstall causes above applies. When an earlier node task of the
dryrun would change the lock file or the manifest, such as a git
checkout, the dryrun reports the node task not_checked, because the
files that a run would read are not there yet. A git task leaves the
record alone, because the record is not in the repository and a checkout
keeps files that Git does not track.
Each release in its own directory. When each release of an
application has its own directory, each release also has its own installed
packages, so installing the next release cannot break the one that runs.
bundler_project_dependencies can put the gems outside the lock file
directory with
gems_dir, so that
releases share the gems. The installation for the next release then changes
the gems that the running release reads.
Python packages in a virtual environment
A virtual environment is a directory with its own Python packages, so
each application's packages stay apart from the system's. pip_package
creates the virtual environment, as the application's account, and
installs a requirements.txt into the virtual environment:
# playbooks/set_up_shop_reports.yml
fleet_stages:
- id: set_up_shop_reports
nodes: web_servers
node_tasks:
- id: install_python_venv
apt_package:
packages:
- {name: python3-venv, version: newest_when_first_installed}
- id: create_reports_group
group:
name: reports
system: true
- id: create_reports_account
user:
name: reports
primary_group: reports
system: true
home: /srv/shop-reports
create_home_directory: false
shell: /usr/sbin/nologin
- id: copy_reports
directory:
path: /srv/shop-reports
source: files/shop-reports # holds requirements.txt
owner: reports
group: reports
- id: install_reports_requirements
pip_package:
requirements_file_on_node: /srv/shop-reports/requirements.txt
virtual_environment: /srv/shop-reports/venv
run_as_user_account: reports
On Debian and Ubuntu, Python makes a virtual environment only with the
package python3-venv. With requirements.txt holding
requests==2.32.5, the first run reports each package that pip installed:
set_up_shop_reports / web01 / install_reports_requirements: succeeded, changed
[{"from":null,"name":"certifi","to":"2026.10.23"},{"from":null,"name":"charset-normalizer","to":"3.5.2"},{"from":null,"name":"idna","to":"3.20"},{"from":null,"name":"requests","to":"2.32.5"},{"from":null,"name":"urllib3","to":"2.8.0"}]
The next run reports unchanged with []. A program of the application
then runs with /srv/shop-reports/venv/bin/python. For an application
with a uv.lock, use
uv_project_dependencies
instead.
To pin a version in the playbook, not in a requirements.txt, name the
package in packages and write the version as a pip specifier in quotes:
- id: install_requests
pip_package:
packages:
- {name: requests, version: "==2.32.3"}
virtual_environment: /opt/shop/venv
run_as_user_account: root
Another specifier, such as ">=2.32,<3", works too. pip_package
lists the forms.
A language version that no package offers
Install a language from the distribution's packages when the packaged
version suits the application, as in the steps. The vendor's own package
repository is the next choice, added with
apt_repository or
dnf_repository, and installed with a
package node task. Packages get security updates with the rest of the
server.
When the application needs a version that no package offers, use a version manager. The usual first choice for each language, and the version managers:
| Language | First choice | When no package fits |
|---|---|---|
| Python | The distribution's python3; on Ubuntu, the deadsnakes PPA for other versions |
uv or pyenv; conda environments with Miniforge |
| Node.js | NodeSource's package repository | nvm, fnm, or Volta |
| Ruby | The distribution's ruby |
rbenv with ruby-build, or rvm |
| Java | The distribution's OpenJDK, or Adoptium's package repository for Eclipse Temurin | SDKMAN! |
| Go | Go's official archive, unpacked with unpack_archive. A Go program is usually built elsewhere and copied as one file. |
No version manager needed |
| PHP | The distribution's packages, or the package repositories of Ondřej Surý (Debian, Ubuntu) and Remi (Rocky Linux, AlmaLinux) | No common version manager |
| Rust | rustup, only on a server that builds Rust code | |
| Several languages | mise, from its package repository | asdf |
MMX has no module for a version manager. Version managers run as shell functions, read profile files, and each keeps its versions in its own place, so two plain node tasks show exactly what happens on the server. Each version manager comes in one of three forms, and each form takes the same two node tasks, whatever the language:
| Form | Examples | The two node tasks |
|---|---|---|
| A Git checkout and an install command | rbenv, pyenv, nvm, asdf | A git node task checks out the version manager at a fixed tag, and a shell node task installs the language version. |
| One program from a release | uv, mise, fnm, Volta | An unpack_archive or download node task installs the program with its SHA-256, and a shell node task installs the language version. |
| An installer script from the vendor | rvm, Miniforge, SDKMAN!, rustup | A download node task fetches the installer with its SHA-256, and a shell node task runs the installer. |
In each form, skip_if_this_path_exists skips the shell node task once
the version's program exists, so the next run changes nothing. A new
version is a new path, so the next run installs the new version and
leaves the old version in place until a node task deletes the old version.
Pin each version manager to a tag or a release with its SHA-256. A checkout of the default branch, or an installer fetched without its SHA-256, changes the version manager whenever the vendor publishes. A pin changes the version manager only when the playbook changes.
A dryrun reports each of these shell node tasks as skipped, unknown — the shell node task has no dryrun command; set dryrun to a read-only command, or run_script_in_dryrun: true for a script that changes nothing, to check the task, because MMX cannot know what a command would change.
A dryrun setting with a read-only command, such as
test -x /opt/nvm/versions/node/v24.22.0/bin/node, lets a dryrun check
the node task. The run then installs the version.
Node.js with nvm
nvm downloads the official build of Node.js and checks its SHA-256. To
move shop-api from the steps to Node.js 24, replace install_nodejs
with these three node tasks:
- id: install_nvm_packages
apt_package:
packages:
- {name: git, version: newest_when_first_installed}
- {name: curl, version: newest_when_first_installed}
- id: check_out_nvm
git:
repo: https://github.com/nvm-sh/nvm.git
check_out_tag: v0.40.8
path: /opt/nvm
- id: install_nodejs
shell:
script: . /opt/nvm/nvm.sh && nvm install 24.22.0
env:
NVM_DIR: /opt/nvm
skip_if_this_path_exists: /opt/nvm/versions/node/v24.22.0/bin/node
Then name the new npm in install_dependencies, and the new node in
the unit, by absolute path:
- id: install_dependencies
npm_project_dependencies:
lock_file_dir: /srv/shop-api
run_as_user_account: shop
include_development_dependencies: false
npm_program_path: /opt/nvm/versions/node/v24.22.0/bin/npm
ExecStart=/opt/nvm/versions/node/v24.22.0/bin/node /srv/shop-api/server.js
The next run installs Node.js 24, installs the packages again for the new runtime, and restarts the application:
set_up_shop_api / web01 / install_nodejs: succeeded, changed
...
set_up_shop_api / web01 / shop_api/changes/install_dependencies: succeeded, changed — installed: the installer or language runtime version changed since the last installation: now npm 11.19.1, v24.22.0; previously npm 9.2.0, v20.19.2
...
set_up_shop_api / web01 / shop_api/activate/restart_shop_api: succeeded, changed — service definition changed
mmx run-command --nodes web_servers -- curl -s http://127.0.0.1:3000/
then prints Shop API on Node.js v24.22.0 for both servers. The next run
reports install_nodejs: skipped, unchanged — node task skipped by a path condition for: /opt/nvm/versions/node/v24.22.0/bin/node.
Ruby with rbenv
rbenv with its plugin ruby-build installs Ruby under /opt/rbenv, for
each account on the server:
# playbooks/install_ruby_with_rbenv.yml
fleet_stages:
- id: install_ruby
nodes: web_servers
node_tasks:
# ruby-build downloads and compiles Ruby, so it needs a compiler and
# these libraries. ruby-build's wiki lists the packages for each distribution.
- id: install_ruby_build_packages
apt_package:
packages:
- {name: git, version: newest_when_first_installed}
- {name: curl, version: newest_when_first_installed}
- {name: build-essential, version: newest_when_first_installed}
- {name: libssl-dev, version: newest_when_first_installed}
- {name: libyaml-dev, version: newest_when_first_installed}
- {name: libreadline-dev, version: newest_when_first_installed}
- {name: zlib1g-dev, version: newest_when_first_installed}
- {name: libffi-dev, version: newest_when_first_installed}
- {name: libgmp-dev, version: newest_when_first_installed}
- id: check_out_rbenv
git:
repo: https://github.com/rbenv/rbenv.git
check_out_tag: v1.3.2
path: /opt/rbenv
# ruby-build goes into rbenv's plugins directory, which the rbenv
# checkout does not have.
- id: create_rbenv_plugins_directory
directory:
path: /opt/rbenv/plugins
# A newer ruby-build knows newer Ruby versions.
- id: check_out_ruby_build
git:
repo: https://github.com/rbenv/ruby-build.git
check_out_tag: v20261013
path: /opt/rbenv/plugins/ruby-build
- id: install_ruby
shell:
script: /opt/rbenv/bin/rbenv install 3.4.11
env:
RBENV_ROOT: /opt/rbenv
skip_if_this_path_exists: /opt/rbenv/versions/3.4.11/bin/ruby
ruby-build compiles Ruby, so install_ruby took about three minutes on
these servers. mmx run-command --nodes web_servers -- /opt/rbenv/versions/3.4.11/bin/ruby --version
then prints ruby 3.4.11 (2026-09-23 revision 592f1ffdb3) +PRISM [x86_64-linux].
The next run reports install_ruby: skipped, unchanged — node task skipped by a path condition for: /opt/rbenv/versions/3.4.11/bin/ruby.
pyenv takes the same node tasks as rbenv: pyenv install 3.14.8 with
PYENV_ROOT in env, skipped once versions/3.14.8/bin/python3 exists
under PYENV_ROOT. Like ruby-build, pyenv compiles the version, which
takes minutes.
Python with uv
uv installs a prebuilt Python in seconds:
# playbooks/install_python_with_uv.yml
fleet_stages:
- id: install_python
nodes: web_servers
node_tasks:
- id: unpack_uv
unpack_archive:
url: https://github.com/astral-sh/uv/releases/download/0.13.0/uv-x86_64-unknown-linux-gnu.tar.gz
sha256: 1468ebd5a5541121837c5a2817b9972ba6090fa6caa3d142620850a47fb75154
path: /opt/uv-0.13.0
unpack_without_wrapping_folder: true
# --no-bin leaves root's home directory alone.
- id: install_python
shell:
script: /opt/uv-0.13.0/uv python install --no-bin 3.14.8
env:
UV_PYTHON_INSTALL_DIR: /opt/uv-python
skip_if_this_path_exists: /opt/uv-python/cpython-3.14.8-linux-x86_64-gnu/bin/python3
The controller machine downloads the archive, checks its SHA-256, and
sends the archive to each server. On an arm64 server, the archive is
uv-aarch64-unknown-linux-gnu.tar.gz, as the page of
uv_project_dependencies
shows, and the Python's directory ends in linux-aarch64-gnu.
pip_package then makes a virtual environment with that Python, named in
its python_program_path:
- id: install_reports_requirements_with_python_3_14
pip_package:
requirements_file_on_node: /srv/shop-reports/requirements.txt
virtual_environment: /srv/shop-reports/venv-3.14
python_program_path: /opt/uv-python/cpython-3.14.8-linux-x86_64-gnu/bin/python3
run_as_user_account: reports
The first run of these three node tasks took about nine seconds on each
server. mmx run-command --nodes web_servers -- /srv/shop-reports/venv-3.14/bin/python --version
then prints Python 3.14.8. uv_project_dependencies takes the same
python_program_path for an application with a uv.lock.
Conda environments with Miniforge
# playbooks/install_miniforge.yml
fleet_stages:
- id: install_miniforge
nodes: web_servers
node_tasks:
- id: download_miniforge_installer
download:
permissions_mode: "0644"
url: https://github.com/conda-forge/miniforge/releases/download/26.7.2-0/Miniforge3-26.7.2-0-Linux-x86_64.sh
sha256: 281b0ac7d550802efc81af633225a5e6116d29ae72f3ab4eae7168c3931a4c05
path: /opt/Miniforge3-26.7.2-0-Linux-x86_64.sh
- id: install_miniforge
shell:
script: bash /opt/Miniforge3-26.7.2-0-Linux-x86_64.sh -b -p /opt/miniforge3
skip_if_this_path_exists: /opt/miniforge3/bin/conda
- id: copy_analysis
directory:
path: /srv/analysis
source: files/analysis # holds environment.yml
# The environment file comes with the application.
- id: create_analysis_environment
shell:
script: /opt/miniforge3/bin/conda env create --prefix /srv/analysis/env --file /srv/analysis/environment.yml
skip_if_this_path_exists: /srv/analysis/env/bin/python
With environment.yml listing python=3.13 and pandas from the
conda-forge channel, the first run downloaded the 124 MB installer,
installed Miniforge, and created the environment in about 17 seconds on
each server. The next run reports download_miniforge_installer: succeeded, unchanged and skips the other two shell node tasks.
mmx run-command --nodes web_servers -- "/srv/analysis/env/bin/python -c 'import pandas; print(pandas.__version__)'"
then prints 3.1.1 for each server.
The last node task creates the environment once. A changed
environment.yml changes nothing on a later run, because the
environment's python already exists. rvm, SDKMAN!, and rustup take the
same node tasks: the installer script with its SHA-256, then the version
manager's own command for the version, each in a shell node task with
skip_if_this_path_exists.
Use the installed version
Name the version's program by its absolute path wherever something runs the program:
-
An installer module: its program path setting, such as
npm_program_pathabove, orbundle_program_pathfor Bundler:- id: install_shop_web_gems bundler_project_dependencies: lock_file_dir: /srv/shop-web run_as_user_account: shop without_gemfile_groups: [development, test] bundle_program_path: /opt/rbenv/versions/3.4.11/bin/bundleHere
/srv/shop-webholds the application'sGemfileandGemfile.lock, copied with adirectorynode task as in the steps. The second run may install the gems once more, withinstalled: the installer or language runtime version changed since the last installation: now bundle Bundler version 2.6.7, ...; previously bundle Bundler version 2.6.9, .... That happens whenBUNDLED WITHinGemfile.locknames another Bundler version than the one that comes with the Ruby: Bundler installs and switches to that version during the first installation. The runs after the second run are unchanged. -
A systemd unit:
ExecStart=/opt/rbenv/versions/3.4.11/bin/bundle exec puma. -
A
shellnode task: the command's path, because ashellnode task runs without the profile files that would set up the version manager.
One named package
To install a tool, not an application's dependencies, name the package:
- id: install_pgcli
pip_package:
packages:
- {name: pgcli, version: newest_when_first_installed}
virtual_environment: /opt/pgcli
run_as_user_account: root
pip_package creates the virtual environment /opt/pgcli and installs
pgcli with what it needs. The first run lists each package, such as
{"from":null,"name":"pgcli","to":"4.7.1"}, and the next run reports
unchanged with []. newest_when_first_installed installs the newest
version once and then leaves the installed version alone.
Each of these modules has its own page with its inputs:
pip_package,
gem_package,
npm_global_package, and
snap_package.
If something is different
| What you see | What it means and what to do |
|---|---|
run_as_user_account is required: ..., such as run_as_user_account is required: the installer runs code from the packages it installs, which should not run as root unless the task says root (lock file modules), or ... name the account that runs pip, including root (named packages) |
mmx validate refuses a node task without run_as_user_account. Add the application's account, or run_as_user_account: root. |
npm_program_path): path must be absolute without null bytes |
A program path starts with /, such as /opt/nvm/versions/node/v24.22.0/bin/npm. |
npm_project_dependencies installs only what a lock file lists, and /tmp has no package-lock.json or npm-shrinkwrap.json; commit the lock file with the application |
lock_file_dir names a directory without a lock file. Check the path, and create the lock file as step 1 shows. |
npm_project_dependencies: npm is not installed; install the package npm in an earlier node task, or name the program in npm_program_path |
The server has no npm. Install it in an earlier node task, as install_nodejs does, or name a version manager's npm in npm_program_path. A dryrun reports the same node task not_checked. |
npm_program_path /opt/nvm/versions/node/v24.22.0/bin/npm is not an executable program; an earlier node task may install the program. in a dryrun |
The version is not installed yet. The shell node task before it installs the version in the run. |
A dryrun reports not_checked with an earlier node task would change the dependency file |
An earlier node task, such as the copy or a git checkout, changes the lock file or the manifest in this run. The run installs what the new files list. |
check_out_ruby_build: the parent directory /opt/rbenv/plugins does not exist; create it with an earlier directory node task |
The rbenv checkout has no plugins directory. Add the directory node task create_rbenv_plugins_directory before the checkout of ruby-build, as Ruby with rbenv shows. |
| The application still runs the old Node.js after a new version was installed | The unit's ExecStart names the old node. Name the new version's path in the unit, as Node.js with nvm shows. |
Where to go next
- Change a configuration and reload its service: node task blocks in full.
- The example
deploy-from-git-with-release-directories: a Python application checked out from Git into one directory for each release, with its own virtual environment. - Reuse work with roles: the installation of an application as a role that several playbooks call.
- Find the module for a job: every module, with its inputs.
This page is docs/how-to/install-languages.md in the MMX repository.