From 355d5331e957a3dc9d98146421ceb21cadee9f4c Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sat, 23 Nov 2024 15:50:22 +0900 Subject: [PATCH] Add docs/just.md as dedicated documentation of "just" commands This is partially based on fb60ba67f646288b40818a555bb716405e144956 (announcement of adoption of "just" program). It also refers descriptions on installing.md. Signed-off-by: Suguru Hirahara --- docs/just.md | 35 +++++++++++++++++++++++++++++++++++ docs/playbook-tags.md | 4 +++- 2 files changed, 38 insertions(+), 1 deletion(-) create mode 100644 docs/just.md diff --git a/docs/just.md b/docs/just.md new file mode 100644 index 000000000..29af49d5a --- /dev/null +++ b/docs/just.md @@ -0,0 +1,35 @@ +# Running `just` commands + +We have previously used [make](https://www.gnu.org/software/make/) for easily running some playbook commands (e.g. `make roles` which triggers [`ansible-galaxy`](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html)). Our [`Makefile`](../Makefile) is still around, and you can still run these commands. + +In addition, we have added support for running commands via [`just`](https://github.com/casey/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`](../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](https://github.com/etkecc/agru#where-to-get) 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`](../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](prerequisites.md) 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](playbook-tags.md) 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](installing.md#installing-a-server-into-which-youll-import-old-data)), 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. diff --git a/docs/playbook-tags.md b/docs/playbook-tags.md index 0699164d0..ea54aa7a9 100644 --- a/docs/playbook-tags.md +++ b/docs/playbook-tags.md @@ -20,4 +20,6 @@ Here are some playbook tags that you should be familiar with: - `ensure-matrix-users-created` - a special tag which ensures that all special users needed by the playbook (for bots, etc.) are created -`setup-*` tags and `install-*` tags **do not start services** automatically, because you may wish to do things before starting services, such as importing a database dump, restoring data from another server, etc. +**Notes**: +- `setup-*` tags and `install-*` tags **do not start services** automatically, because you may wish to do things before starting services, such as importing a database dump, restoring data from another server, etc. +- Please be careful not to confuse the playbook tags with the `just` shortcut commands ("recipes"). For details on `just` commands, see: [Running `just` commands](just.md)