diff --git a/docs/faq.md b/docs/faq.md index 82e2f3a17..427d2d25c 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -342,7 +342,7 @@ As described in [How is the effective configuration determined?](#how-is-the-eff Refer to both of these for inspiration. Still, as mentioned in [Configuring the playbook](configuring-playbook.md), you're only ever supposed to edit your own `inventory/host_vars/matrix.DOMAIN/vars.yml` file and nothing else inside the playbook (unless you're meaning to contribute new features). -**Note**: some of the roles (`roles/galaxy/*`) live in separate repositories and are only installed after your run `just roles` (or `make roles`). +**Note**: some of the roles (`roles/galaxy/*`) live in separate repositories and are only installed after your run `just roles` (or `make roles`) or `just update` (which automatically does `git pull` and `just roles`). ### I'd like to adjust some configuration which doesn't have a corresponding variable. How do I do it? @@ -356,7 +356,7 @@ Besides that, each role (component) aims to provide a `matrix_SOME_COMPONENT_con Check each role's `roles/*/*/defaults/main.yml` for the corresponding variable and an example for how use it. -**Note**: some of the roles (`roles/galaxy/*`) live in separate repositories and are only installed after your run `just roles` (or `make roles`). +**Note**: some of the roles (`roles/galaxy/*`) live in separate repositories and are only installed after your run `just roles` (or `make roles`) or `just update` (which automatically does `git pull` and `just roles`). ## Installation diff --git a/docs/installing.md b/docs/installing.md index c85ce1e63..01cf20e84 100644 --- a/docs/installing.md +++ b/docs/installing.md @@ -2,7 +2,9 @@ If you've [configured your DNS](configuring-dns.md) and have [configured the playbook](configuring-playbook.md), you can start the installation procedure. -**Before installing** and each time you update the playbook in the future, you will need to update the Ansible roles in this playbook by running `just roles`. `just roles` is a shortcut (a `roles` target defined in [`justfile`](../justfile) and executed by the [`just`](https://github.com/casey/just) utility) which ultimately runs [ansible-galaxy](https://docs.ansible.com/ansible/latest/cli/ansible-galaxy.html) to download Ansible roles. If you don't have `just`, you can also manually run the `roles` commands seen in the `justfile`. +**Before installing** and each time you update the playbook in the future, you will need to update the Ansible roles in this playbook by running `just roles`. `just roles` is a shortcut (a `roles` target defined in [`justfile`](../justfile) and executed by the [`just`](https://github.com/casey/just) utility) which ultimately runs [agru](https://gitlab.com/etke.cc/tools/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. If you don't have `just`, you can also manually run the `roles` commands seen in the `justfile`. + +There's another shortcut (`just update`) which updates the playbook (`git pull`) and updates roles (`just update`) at the same time. ## Playbook tags introduction diff --git a/docs/maintenance-upgrading-services.md b/docs/maintenance-upgrading-services.md index b65eadd77..8b903fbb4 100644 --- a/docs/maintenance-upgrading-services.md +++ b/docs/maintenance-upgrading-services.md @@ -6,12 +6,13 @@ If you want to be notified when new versions of Synapse are released, you should To upgrade services: -- update your playbook directory (`git pull`), so you'd obtain everything new we've done +- update your playbook directory and all upstream Ansible roles (defined in the `requirements.yml` file) using: + +- either: `just update` +- or: a combination of `git pull` and `just role` (or `make roles`) - take a look at [the changelog](../CHANGELOG.md) to see if there have been any backward-incompatible changes that you need to take care of -- download the upstream Ansible roles used by the playbook by running `just roles` - -- re-run the [playbook setup](installing.md) and restart all services: `just setup-all` +- re-run the [playbook setup](installing.md) and restart all services: `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). diff --git a/docs/prerequisites.md b/docs/prerequisites.md index d1259e6fc..9fcadd275 100644 --- a/docs/prerequisites.md +++ b/docs/prerequisites.md @@ -26,7 +26,7 @@ If your distro runs within an [LXC container](https://linuxcontainers.org/), you - [`git`](https://git-scm.com/) is the recommended way to download the playbook to your computer. `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`, 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 - An HTTPS-capable web server at the base domain name (``) which is capable of serving static files. Unless you decide to [Serve the base domain from the Matrix server](configuring-playbook-base-domain-serving.md) or alternatively, to use DNS SRV records for [Server Delegation](howto-server-delegation.md). diff --git a/justfile b/justfile index b7ca7d2c4..72609d572 100644 --- a/justfile +++ b/justfile @@ -5,6 +5,7 @@ default: # Pulls external Ansible roles roles: #!/usr/bin/env sh + echo "[NOTE] This command just updates the roles, but if you want to update everything at once (playbook, roles, etc.) - use 'just update'" if [ -x "$(command -v agru)" ]; then agru else @@ -12,9 +13,25 @@ roles: ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force fi -# Updates requirements.yml if there are any new tags available. Requires agru -update: - @agru -u +# Updates the playbook and installs the necessary Ansible roles pinned in requirements.yml. If a -u flag is passed, also updates the requirements.yml file with new role versions (if available) +update *flags: update-playbook-only + #!/usr/bin/env sh + if [ -x "$(command -v agru)" ]; then + echo {{ if flags == "" { "Installing roles pinned in requirements.yml..." } else if flags == "-u" { "Updating roles and pinning new versions in requirements.yml..." } else { "Unknown flags passed" } }} + agru {{ flags }} + else + echo "[NOTE] You are using the standard ansible-galaxy tool to install roles, which is slow and lacks other features. We recommend installing the 'agru' tool to speed up the process: https://gitlab.com/etke.cc/tools/agru#where-to-get" + echo "Installing roles..." + rm -rf roles/galaxy + ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force + fi + +# Updates the playbook without installing/updating Ansible roles +update-playbook-only: + @echo "Updating playbook..." + @git stash -q + @git pull -q + @-git stash pop -q # Runs ansible-lint against all roles in the playbook lint: