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

Update docs/installing.md and docs/quick-start.md: mention "make roles"

Browse Source 
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 <acioustick@noreply.codeberg.org>
This commit is contained in:
Suguru Hirahara 2024-11-22 22:18:08 +09:00
parent e76033e645
commit 8a83b11ece
No known key found for this signature in database
GPG Key ID: E4F9743DAB4B7B75
2 changed files with 15 additions and 4 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
docs/installing.md
View File

@ -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

11
docs/quick-start.md
View File

@ -1,5 +1,10 @@
# Quick start
<!--
NOTE:
- Because this documentation is intended to be referred by those who have not configured a Matrix server and services by using the playbook, from the educational point of view it intentionally avoids instructions based on just program's "recipes" in favor of ansible-playbook commands in most cases.
-->
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