MMX documentation
Each page answers one question. Start with Get started if you have not run MMX yet.
Start here
- Get started: install
mmx, create a project for one server, preview a change, and make it. - How MMX works: what happens on your computer and on each server during a run, the two connections, and what MMX protects.
- When something fails: an error message or a surprise, what it means, and what to do.
- Examples: whole example projects.
Write and run playbooks
- Write a playbook: install a package, write files, and reload a service only when its configuration changed.
- Preview and run changes: what a dryrun shows, each result and exit code, and running on one server first.
- Change a configuration and reload its service: check a new configuration before it goes live, reload only when needed, and put the old files back when a change fails.
Describe and reach your servers
- Describe your servers: nodes, groups, variables, and a second inventory for staging.
- Connect to your servers: host keys, passwords, jump hosts, port 7443, and a replaced server.
Choose servers and roll out
- Choose which servers a run touches:
--limit,except_nodes, groups that may be empty, and running only some fleet stages. - Roll out a change gradually: a few servers at a time, what a failed server stops, and one server at a time behind a load balancer.
Values, results, and reuse
- Use variables and templates: values for each server, facts such as memory and CPU count, template files, and values given on the command line.
- Use a result from one server on another: pass an address, a key, or a list of servers from one fleet stage to the next, and save results on your controller machine.
- Reuse work with roles: package node tasks with inputs, and one role for several distributions.
Secrets
- Keep secrets: the encrypted vault, unlocking it for automation, secrets from environment variables, and a vault for each inventory.
- Secrets reference: which secrets a run needs and each server receives, and where secrets can appear.
Control runs and servers
- Stop, resume, and read a run: stop a run, finish it later, read its results, and how long runs are kept.
- Run a command on servers now: a one-off command on some servers, without a playbook.
- Make a one-time change: work that happens once on each server, such as moving data, and marking it done.
- Keep MMX off a server: keep runs off while you work on a server, or remove MMX from it.
- Manage the controller machine itself:
let MMX set up the computer that runs
mmx, and patch it safely.
Modules, software, and data
- Find the module for a job: look up modules, and what to do when none fits.
- Write your own module: a module for your project, in Starlark or as a program.
- Write a package module: support another distribution's package manager.
- Install languages: language runtimes, an application's dependencies from its lock file, and version managers.
- Run containers: Docker, Compose projects, new image versions, and private registries.
- Manage a database: PostgreSQL and MariaDB accounts and databases, also on another machine.
- Module interface reference: what a module's description, Starlark primitives, and program protocol hold.
Work as a team
- Move or share a project: another controller machine, a teammate, or CI.
Change risky settings, move in, and upgrade
- Change SSH or network settings safely: network files that a server puts back by itself, sshd's port and login rules, and how to get back in.
- Move from Ansible or Salt: each Ansible and Salt idea in MMX, and a playbook converted step by step.
- Upgrade MMX: a new release on your computer and your servers, and going back to an earlier one.
Look things up
- Commands: every
mmxcommand and flag, exit codes, output, and the JSON of a run. - Project settings: every field of
mmx_project_settings.yml, and what the.mmx/directory holds. - Inventory file: every field of an inventory: nodes, groups, variables, and connection settings.
- Playbook file: every field of a playbook, retries and time limits, templates, and node facts.
- Shared module behavior: file modes and owners, file previews, package versions, service recovery, conditions, and the environment of a command.
- Module pages: one page for each module.
mmx describe-module NAMEprints the same page. - Limits on each distribution: what is limited on each tested distribution, and why.
- Performance: the measurements, including the comparison with Ansible.
Changing MMX itself
- Changing MMX: the design, the acceptance contracts, testing, and the rules for MMX's own code.
This page is docs/README.md in the MMX repository.