mirror/matrix-docker-ansible-deploy
1
0
Fork 0
mirror of https://github.com/spantaleev/matrix-docker-ansible-deploy.git synced 2025-01-13 19:57:17 +01:00
Code Issues Packages Projects Releases Wiki Activity

Add docs/just.md (#3811)

Browse Source 
* Add docs/just.md as dedicated documentation of "just" commands

This is partially based on fb60ba67f6 (announcement of adoption of "just" program). It also refers descriptions on installing.md.

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Create a table for examples

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Fix entries on the table

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Move the anchor link to "agru"

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Edit docs/faq.md: add an entry for the just

It is based on the existing explanation of the just on docs/maintenance-upgrading-services.md.

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Add links to docs/just.md

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Update docs/just.md: add a common note

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

* Clarify "What is just" section on FAQ

* Update just.md

* Mention install-service

---------

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
Co-authored-by: Suguru Hirahara <acioustick@noreply.codeberg.org>
Co-authored-by: Slavi Pantaleev <slavi@devture.com>
This commit is contained in:
Suguru Hirahara 2024-11-23 18:52:48 +09:00 committed by GitHub
parent 194a3ca461
commit e36115a5b9
No known key found for this signature in database
GPG Key ID: B5690EEEBB952194
6 changed files with 58 additions and 6 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
docs/faq.md
View File

@ -80,6 +80,16 @@ Alternatively, you can download Ansible and the playbook itself directly on the
To learn more, see our [dedicated Ansible documentation page](ansible.md).
### What is `just`?
[`just`](https://github.com/casey/just) is a modern command-runner alternative to [make](https://www.gnu.org/software/make/). It can be used to invoke commands with less typing.
The `just` utility executes shortcut commands (called "recipes"), which invoke `ansible-playbook`, `ansible-galaxy` or [`agru`](https://github.com/etkecc/agru) (depending on what is available in your system). The targets of the recipes are defined in [`justfile`](../justfile).
For details about `just` commands, take a look at: [Running `just` commands](just.md).
The playbook also contains a `Makefile` for the `make` tool, but most of the just recipes are not available as targets in the `Makefile`.
### Why use this playbook and not install Synapse and other things manually?
There are various guides telling you how easy it is to install [Synapse](https://github.com/element-hq/synapse).

4
docs/installing.md
View File

@ -15,6 +15,8 @@ To update your playbook directory and all upstream Ansible roles (defined in the
If you don't have either `just` tool or `make` program, you can run the `ansible-galaxy` tool directly: `rm -rf roles/galaxy; ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force`
For details about `just` commands, take a look at: [Running `just` commands](just.md).
## Install Matrix server and services
The Ansible playbook's tasks are tagged, so that certain parts of the Ansible playbook can be run without running all other tasks.
@ -51,7 +53,7 @@ To do the installation **without** starting services, run `ansible-playbook` wit
ansible-playbook -i inventory/hosts setup.yml --tags=install-all
```
**Note**: do not run the just "recipe" `just install-all` instead, because it automatically starts services at the end of execution.
**Note**: do not run the just "recipe" `just install-all` instead, because it automatically starts services at the end of execution. See: [Difference between playbook tags and shortcuts](just.md#difference-between-playbook-tags-and-shortcuts)
When this command completes, services won't be running yet.

38
docs/just.md Normal file
View File

@ -0,0 +1,38 @@
# 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 invoke `ansible-playbook`, `ansible-galaxy` or [`agru`](https://github.com/etkecc/agru) (depending on what is available in your system). The targets of the recipes are defined in [`justfile`](../justfile). Most of the just recipes have no corresponding `Makefile` targets.
For some recipes such as `just update`, our `justfile` recommends installing [`agru`](https://github.com/etkecc/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`](../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` with even less typing |
| `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). 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 immediately after installing components which may prevent your from importing old data.

6
docs/maintenance-upgrading-services.md
View File

@ -23,10 +23,10 @@ If it looks good to you, go to the `matrix-docker-ansible-deploy` directory, the
- either: `just update`
- or: a combination of `git pull` and `just roles` (or `make roles` if you have `make` program on your computer instead of `just`)
`just update` and `just roles` are shortcuts (their targets are defined in [`justfile`](../justfile) and executed by the [`just`](https://github.com/casey/just) utility) which ultimately run [agru](https://github.com/etkecc/agru) or [ansible-galaxy](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html) (depending on what is available in your system) to download Ansible roles, after upgrading the playbook (in case of `just update`).
If you don't have either `just` tool or `make` program, you can run the `ansible-galaxy` tool directly: `rm -rf roles/galaxy; ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force`
For details about `just` commands, take a look at: [Running `just` commands](just.md).
- re-run the [playbook setup](installing.md#maintaining-your-setup-in-the-future) and restart all services:
```sh
@ -35,6 +35,6 @@ If it looks good to you, go to the `matrix-docker-ansible-deploy` directory, the
Note that if you remove components from `vars.yml`, or if we switch some component from being installed by default to not being installed by default anymore, you'd need to run the setup command with `--tags=setup-all` instead of `--tags=install-all`. See [this page on the playbook tags](playbook-tags.md) for more information.
A way to invoke these `ansible-playbook` commands with less typing is to use [just](https://github.com/casey/just) to run the "recipe": `just install-all` or `just setup-all`. See [our `justfile`](../justfile) for more information. If you don't have `just`, you can also manually run the commands seen in the `justfile`.
A way to invoke these `ansible-playbook` commands with less typing is to run the `just` "recipe": `just install-all` or `just setup-all`.
**Note**: major version upgrades to the internal PostgreSQL database are not done automatically. To upgrade it, refer to the [upgrading PostgreSQL guide](maintenance-postgres.md#upgrading-postgresql).

4
docs/playbook-tags.md
View File

@ -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 about `just` commands, see: [Running `just` commands](just.md)

2
docs/prerequisites.md
View File

@ -14,7 +14,7 @@ We will be using `example.com` as the domain in the following instruction. Pleas
- [`git`](https://git-scm.com/) as the recommended way to download the playbook. `git` may also be required on the server if you will be [self-building](self-building.md) components.
- [`just`](https://github.com/casey/just) for running `just roles`, `just update`, etc. (see [`justfile`](../justfile)), although you can also run these commands manually
- [`just`](https://github.com/casey/just) for running `just roles`, `just update`, etc. (see [`justfile`](../justfile)), although you can also run these commands manually. Take at look at this documentation for more information: [Running `just` commands](just.md).
- Strong password (random strings) generator. The playbook often requires you to create a strong password and use it for settings on `vars.yml`, components, etc. As any tools should be fine, this playbook has adopted [`pwgen`](https://linux.die.net/man/1/pwgen) (running `pwgen -s 64 1`). [Password Tech](https://pwgen-win.sourceforge.io/), formerly known as "PWGen for Windows", is available as free and open source password generator for Windows. Generally, using a random generator available on the internet is not recommended.