Justfile and documentation updates to make things clearer

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

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

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:
+
+- 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 update` or `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).

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

requirements.yml

@@ -4,7 +4,7 @@
   version: v1.0.0-3
   name: auxiliary
 - src: git+https://gitlab.com/etke.cc/roles/backup_borg.git
-  version: v1.2.8-1.8.13-0
+  version: v1.2.8-1.8.11-1
   name: backup_borg
 - src: git+https://github.com/devture/com.devture.ansible.role.container_socket_proxy.git
   version: v0.2.0-0
@@ -58,7 +58,7 @@
   version: v0.14.0-5
   name: prometheus_postgres_exporter
 - src: git+https://gitlab.com/etke.cc/roles/redis.git
-  version: v7.2.4-2
+  version: v7.2.4-1
   name: redis
 - src: git+https://github.com/devture/com.devture.ansible.role.systemd_docker_base.git
   version: v1.2.0-0