From 8a83b11eced096b51a29bdf650c673c53a279ff0 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Fri, 22 Nov 2024 22:18:08 +0900 Subject: [PATCH] Update docs/installing.md and docs/quick-start.md: mention "make roles" This commit adds mentions to "make roles" and a note about the preference of ansible-playbook commands over the just "recipes". quick-start.md intends to be referred by those who have never used the playbook to set up a server, so it is safer to regard that it is not clear to them what exactly the just "recipes" are made of, ie. it takes some time and experience until someone understands simplicity of them. For beginners, I believe that we should prefer the basics over simplicity, from the educational point of view. If someone feels tired of using the same command repetitively, then the person will have been already well accustomed to the way how the playbook works and how the server is supposed to be maintained, and the person is "qualified" to use the just "recipes", and should be able to use them with confidence, distinguishing the playbook tags from the "recipes", for example, from "just install-all" and "ansible-playbook -i inventory/hosts setup.yml --tags=install-all". Such level of familiarity and experience should not be expected on the quick start guide. Signed-off-by: Suguru Hirahara --- docs/installing.md | 8 ++++++-- docs/quick-start.md | 11 +++++++++-- 2 files changed, 15 insertions(+), 4 deletions(-) diff --git a/docs/installing.md b/docs/installing.md index 9928c4c61..38f14eec3 100644 --- a/docs/installing.md +++ b/docs/installing.md @@ -6,11 +6,15 @@ If you've configured your DNS records and the playbook, you can start the instal ## Update Ansible roles -Before installing, you need to update the Ansible roles in this playbook by running `just roles`. +Before installing, you need to update the Ansible roles that this playbook uses and fetches from outside. + +To update them, run `just roles` (or `make roles` if you have `make` program on your computer instead of `just`). `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://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. 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 roles`) at the same time. +**Note**: there's another shortcut (`just update`) which updates the playbook (`git pull`) and updates roles (`just roles`) at the same time. + +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` ## Install Matrix server and services diff --git a/docs/quick-start.md b/docs/quick-start.md index 405842808..7a861be3b 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -1,5 +1,10 @@ # Quick start + + This page explains how to use this Ansible playbook to install Matrix services on your server with a minimal set of core services. We will be using `example.com` as the "base domain" in the following instruction. @@ -95,9 +100,11 @@ After editing `vars.yml` and `hosts` files, let's start the **installation** pro ### Update Ansible roles -Before installing, you need to update the Ansible roles that this playbook uses and fetches from outside. To update them, run `just roles` on your local computer. +Before installing, you need to update the Ansible roles that this playbook uses and fetches from outside. -If you don't have the `just` tool, you can use the `ansible-galaxy` tool directly: `rm -rf roles/galaxy; ansible-galaxy install -r requirements.yml -p roles/galaxy/ --force` +To update them, run `just roles` (or `make roles` if you have `make` program on your computer instead of `just`). + +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` ### Run installation command