From c8ec351fdfbb6bc1fdbcd3f5829664c288d540c0 Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 1 Dec 2024 23:29:41 +0900 Subject: [PATCH] Update descriptions about installation - Introduce the most conservative and stable raw ansible-playbook command. - Introduce the just commands on installing.md and maintenance-upgrading-services.md, not on quick-start.md, since it is too early for quick start guide readers who are just starting to climb learning curve to use the shortcuts. Signed-off-by: Suguru Hirahara --- docs/installing.md | 16 +++++++++++++++- docs/maintenance-upgrading-services.md | 16 +++++++++++++--- docs/quick-start.md | 8 +++++++- 3 files changed, 35 insertions(+), 5 deletions(-) diff --git a/docs/installing.md b/docs/installing.md index f6c83bd66..0abfe0682 100644 --- a/docs/installing.md +++ b/docs/installing.md @@ -142,4 +142,18 @@ Since it is unsafe to keep outdated services running on the server connected to For more information about upgrading or maintaining services with the playbook, take at look at this page: [Upgrading the Matrix services](maintenance-upgrading-services.md) -Feel free to **re-run the setup command any time** you think something is off with the server configuration. Ansible will take your configuration and update your server to match. +Feel free to **re-run the setup command any time** you think something is wrong with the server configuration. Ansible will take your configuration and update your server to match. + +```sh +ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start +``` + +**Note**: see [this page on the playbook tags](playbook-tags.md) for more information about those tags. + +### Make full use of `just` shortcut commands + +After you get familiar with reconfiguring and re-running the playbook to maintain the server, upgrade its services, etc., you probably would like to make use of `just` shortcut commands for faster input. + +For example, `just install-all` is useful for maintaining your setup quickly when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. + +You can learn about the shortcut commands on this page: [Running `just` commands](just.md) diff --git a/docs/maintenance-upgrading-services.md b/docs/maintenance-upgrading-services.md index 57aa80dda..a59bf5940 100644 --- a/docs/maintenance-upgrading-services.md +++ b/docs/maintenance-upgrading-services.md @@ -37,11 +37,21 @@ After updating the Ansible roles, then re-run the [playbook setup](installing.md ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start ``` -If you remove components from `vars.yml`, or if we switch some component from being installed by default to not being installed by default anymore, you'd need to run the setup command with `--tags=setup-all` instead of `--tags=install-all`. See [this page on the playbook tags](playbook-tags.md) for more information. +If you remove components from `vars.yml`, or if we switch some component from being installed by default to not being installed by default anymore, you'd need to run the setup command with the `setup-all` tag as below: -#### Run `just` to execute shortcut command +```sh +ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start +``` -If you want to invoke the `ansible-playbook` command with less typing, you can run `just` to execute the shortcut command: `just install-all` (or `just setup-all`). Note that it restarts all services automatically. +**Notes**: + +- The `ensure-matrix-users-created` playbook tag makes the playbook automatically create the bot's user account, if any. + +- The shortcut commands with the [`just` program](just.md) are also available: `just install-all` or `just setup-all` + + `just install-all` is useful for maintaining your setup quickly when its components remain unchanged. If you adjust your `vars.yml` to remove other components, you'd need to run `just setup-all`, or these components will still remain installed. Note these shortcuts run the `ensure-matrix-users-created` tag too. + +- See [this page on the playbook tags](playbook-tags.md) for more information about those tags. ## PostgreSQL major version upgrade diff --git a/docs/quick-start.md b/docs/quick-start.md index b08af6514..11d8cb7d4 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -177,7 +177,13 @@ ansible-playbook -i inventory/hosts setup.yml --tags=install-matrix-static-files After the command finishes, you can also check whether your server federates with the Matrix network by using the [Federation Tester](https://federationtester.matrix.org/) against your base domain (`example.com`), not the `matrix.example.com` subdomain. -If you think something is off with the server configuration, feel free to [re-run the full setup command](#run-the-installation-command) any time. +### Re-run the full setup command any time + +If you think something is wrong with the server configuration, feel free to re-run the setup command any time: + +```sh +ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,ensure-matrix-users-created,start +``` ## Log in to your user account