matrix-docker-ansible-deploy/docs/just.md

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 ultimately run ansible-galaxy. The targets of the recipes are defined in justfile. It defines commands, most of which are not available on our Makefile.

For some recipes such as just update, our justfile recommends to install agru to speed up the process.

Here are some examples of shortcuts:

• just roles - trigger make roles to install the necessary Ansible roles pinned in requirements.yml
• just update - run git pull to update the playbook and just roles
• just install-all - run ansible-playbook -i inventory/hosts setup.yml --tags=install-all,ensure-matrix-users-created,start
  • just install-all --ask-vault-pass - commands also support additional arguments (--ask-vault-pass will be appended to the above installation command)
• just setup-all - run ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start
• just run-tags install-mautrix-slack,start - run specific playbook tags
• just start-all - (re-)starts all services
• just stop-group postgres - stop only the Postgres service
• just register-user john secret-password yes - registers a john 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 themselves. 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-all
• ansible-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 soon after installing components, and will affect your data which will be manually imported later.