From b03a0ac453ddc3a8281d30f892d3a92f273e4ac4 Mon Sep 17 00:00:00 2001 From: Slavi Pantaleev Date: Mon, 15 Jul 2024 07:55:01 +0300 Subject: [PATCH] Justfile and documentation updates to make things clearer --- docs/faq.md | 4 ++-- docs/installing.md | 4 +++- docs/maintenance-upgrading-services.md | 9 +++++---- justfile | 16 ++++++++-------- 4 files changed, 18 insertions(+), 15 deletions(-) diff --git a/docs/faq.md b/docs/faq.md index 5f4593922..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 `just update` (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 `just update` (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 b7210175d..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` or `just update`. `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`. `just update` is a shortcut which updates the playbook itself and the roles at the same time. +**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 494c62ab4..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 using `just update` or`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: -- 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 +- either: `just update` +- or: a combination of `git pull` and `just role` (or `make roles`) -- download the upstream Ansible roles used by the playbook by running `just update` or `just 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 -- 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/justfile b/justfile index a20fabaac..72609d572 100644 --- a/justfile +++ b/justfile @@ -13,22 +13,22 @@ roles: ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force fi -# Updates requirements.yml if there are any new tags available. Supported flags: -u (update roles, if any new tags are available) -update *flags: update-self +# 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..." } else if flags == "-u" { "updating roles..." } else { "unknown flag passed" } }} + 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 standard ansible-galaxy to install roles, it's slow and cannot update roles if there are newer tags available. We recommend to install 'agru' tool to speed up the process: https://gitlab.com/etke.cc/tools/agru#where-to-get" - echo "installing roles..." + 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 -# update playbook -update-self: - @echo "updating playbook..." +# Updates the playbook without installing/updating Ansible roles +update-playbook-only: + @echo "Updating playbook..." @git stash -q @git pull -q @-git stash pop -q