QEDeDandSlavi Pantaleev
d69bf26d67
Conditional restart is enabled whenever no setup-* tag is selected, so it also applies to runs with only start or restart tags. These runs skip the install tasks that set each role's *_restart_necessary, so every service whose value is false is only started. When the rule was added, only Traefik tracked its changes this way; now most roles do, so `just start-all` and `just start-group` restart almost nothing, contrary to docs/just.md. Enable conditional restart only when an install-* tag is selected and no setup-* tag. install-* runs keep conditional restart and setup-* runs are unchanged; runs with only start or restart tags restart their targeted services unconditionally again. Show the restart behavior of each standard recipe in docs/just.md and announce the change in CHANGELOG.md.
6.5 KiB
Running just commands
We have previously used make for easily running some playbook commands (e.g. make roles which triggers ansible-galaxy). Our Makefile is still around, and you can still run these commands.
In addition, we have added support for running commands via just — a more modern command-runner alternative to make. It can be used to invoke ansible-playbook commands with less typing.
The just utility executes shortcut commands (called as "recipes"), which invoke ansible-playbook, ansible-galaxy or agru (depending on what is available in your system). The targets of the recipes are defined in justfile. Most of the just recipes have no corresponding Makefile targets.
For some recipes such as just update, our justfile recommends installing agru (a faster alternative to ansible-galaxy) to speed up the process.
Here are some examples of shortcuts:
| Shortcut | Result |
|---|---|
just roles |
Install the necessary Ansible roles pinned in requirements.yml |
just update |
Run git pull (to update the playbook) and install the Ansible roles |
just install-all |
Run ansible-playbook -i inventory/hosts setup.yml --tags=install-all,ensure-matrix-users-created,start |
just setup-all |
Run ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start |
just install-all --ask-vault-pass |
Run commands with additional arguments (--ask-vault-pass will be appended to the above installation command) |
just run-tags install-mautrix-slack,start |
Run specific playbook tags (here install-mautrix-slack and start) |
just install-service mautrix-slack |
Run just run --tags=install-mautrix-slack,start-group --extra-vars=group=mautrix-slack with even less typing |
just start-all |
(Re-)starts all services |
just stop-group postgres |
Stop only the Postgres service |
just register-user alice secret-password yes |
Registers an alice user with the secret-password password and admin access (admin = yes) |
While our documentation on prerequisites lists just as one of the requirements for installation, using just is optional. If you find it difficult to install it, do not find it useful, or want to prefer raw ansible-playbook commands for some reason, feel free to run all commands manually. For example, you can run ansible-galaxy directly to install the Ansible roles: rm -rf roles/galaxy; ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force.
Difference between playbook tags and shortcuts
It is worth noting that just "recipes" are different from playbook tags. The recipes are shortcuts of commands defined in justfile and can be executed by the just program only, while the playbook tags are available for the raw ansible-playbook commands as well. Please be careful not to confuse them.
For example, these two commands are different:
just install-allansible-playbook -i inventory/hosts setup.yml --tags=install-all
The just recipe runs ensure-matrix-users-created and start tags after install-all, while the latter runs only install-all tag. The correct shortcut of the latter is just run-tags install-all.
Such kind of difference sometimes matters. For example, when you install a Matrix server into which you will import old data (see here), you are not supposed to run just install-all or just setup-all, because these commands start services immediately after installing components, which may prevent you from importing the data.
Conditional service restart
With conditional restart, a service whose role tracks its changes is restarted only when its configuration or container image changed during the run. An unchanged service is left running, or started if it was stopped. Whether conditional restart applies depends on the playbook tags. The standard just recipes add these tags:
| Command | Tags added by the recipe | Restart behavior |
|---|---|---|
just install-all |
install-all,ensure-matrix-users-created,start |
Conditional |
just install-service SERVICE |
install-SERVICE,start-group |
Conditional, within the service's group |
just setup-all |
setup-all,ensure-matrix-users-created,start |
Unconditional: all targeted services restart |
just start-all |
start-all |
Unconditional: all services restart |
just start-group GROUP |
start-group |
Unconditional, within the group |
For raw ansible-playbook or just run-tags runs, conditional restart applies only when the selected tags include an install-* tag and no setup-* tag. Any other run with a start or restart tag restarts its targeted services unconditionally.
This behavior can be overridden with the devture_systemd_service_manager_conditional_restart_enabled variable. For example, to force unconditional restarts during installation: just install-all --extra-vars='devture_systemd_service_manager_conditional_restart_enabled=false'