From ea48e5e9ebb0ae09996e6471390f8abeb0ce44fc Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sat, 9 Nov 2024 00:40:19 +0900 Subject: [PATCH] Create docs/playbook-tags.md: move explanation about playbook tags The playbook tags are not limited to installation, and the explanation's detail makes the section worth being split to a dedicated individual page. Signed-off-by: Suguru Hirahara --- docs/README.md | 2 ++ docs/installing.md | 29 +++-------------------------- docs/playbook-tags.md | 23 +++++++++++++++++++++++ 3 files changed, 28 insertions(+), 26 deletions(-) create mode 100644 docs/playbook-tags.md diff --git a/docs/README.md b/docs/README.md index 77c5099df..3fdf8bd6a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -12,6 +12,8 @@ - [Installing](installing.md) +- [Playbook tags](playbook-tags.md) + - **Importing data from another server installation** - [Importing an existing SQLite database (from another Synapse installation)](importing-synapse-sqlite.md) (optional) diff --git a/docs/installing.md b/docs/installing.md index 50926fca8..64f256025 100644 --- a/docs/installing.md +++ b/docs/installing.md @@ -8,33 +8,11 @@ If you've [configured your DNS](configuring-dns.md) and have [configured the pla There's another shortcut (`just update`) which updates the playbook (`git pull`) and updates roles (`just roles`) at the same time. - -## Playbook tags introduction +## Install Matrix The Ansible playbook's tasks are tagged, so that certain parts of the Ansible playbook can be run without running all other tasks. -The general command syntax is: `ansible-playbook -i inventory/hosts setup.yml --tags=COMMA_SEPARATED_TAGS_GO_HERE` - -Here are some playbook tags that you should be familiar with: - -- `setup-all` - runs all setup tasks (installation and uninstallation) for all components, but does not start/restart services - -- `install-all` - like `setup-all`, but skips uninstallation tasks. Useful for maintaining your setup quickly when its components remain unchanged. If you adjust your `vars.yml` to remove components, you'd need to run `setup-all` though, or these components will still remain installed - -- `setup-SERVICE` (e.g. `setup-postmoogle`) - runs the setup tasks only for a given role, but does not start/restart services. You can discover these additional tags in each role (`roles/**/tasks/main.yml`). Running per-component setup tasks is **not recommended**, as components sometimes depend on each other and running just the setup tasks for a given component may not be enough. For example, setting up the [mautrix-telegram bridge](configuring-playbook-bridge-mautrix-telegram.md), in addition to the `setup-mautrix-telegram` tag, requires database changes (the `setup-postgres` tag) as well as reverse-proxy changes (the `setup-nginx-proxy` tag). - -- `install-SERVICE` (e.g. `install-postmoogle`) - like `setup-SERVICE`, but skips uninstallation tasks. See `install-all` above for additional information. - -- `start` - starts all systemd services and makes them start automatically in the future - -- `stop` - stops all systemd services - -- `ensure-matrix-users-created` - a special tag which ensures that all special users needed by the playbook (for bots, etc.) are created - -`setup-*` tags and `install-*` tags **do not start services** automatically, because you may wish to do things before starting services, such as importing a database dump, restoring data from another server, etc. - - -## Install Matrix +The general command syntax for installation (and also maintenance) is: `ansible-playbook -i inventory/hosts setup.yml --tags=COMMA_SEPARATED_TAGS_GO_HERE`. It is recommended to get yourself familiar with the [playbook tags](playbook-tags.md) before proceeding. If you **don't** use SSH keys for authentication, but rather a regular password, you may need to add `--ask-pass` to the all Ansible commands @@ -42,7 +20,6 @@ If you **do** use SSH keys for authentication, **and** use a non-root user to *b There 2 ways to start the installation process - depending on whether you're [Installing a brand new server (without importing data)](#installing-a-brand-new-server-without-importing-data) or [Installing a server into which you'll import old data](#installing-a-server-into-which-youll-import-old-data). - ### Installing a brand new server (without importing data) If this is **a brand new** Matrix server and you **won't be importing old data into it**, run all these tags: @@ -115,6 +92,6 @@ After finilizing the installation, you can: 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. -Note that 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 [Playbook tags introduction](#playbook-tags-introduction) +Note that 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. A way to invoke these `ansible-playbook` commands with less typing in the future is to use [just](https://github.com/casey/just) to run them: `just install-all` or `just setup-all`. See [our `justfile`](../justfile) for more information. diff --git a/docs/playbook-tags.md b/docs/playbook-tags.md new file mode 100644 index 000000000..0699164d0 --- /dev/null +++ b/docs/playbook-tags.md @@ -0,0 +1,23 @@ +# Playbook tags + +The Ansible playbook's tasks are tagged, so that certain parts of the Ansible playbook can be run without running all other tasks. + +The general command syntax is: `ansible-playbook -i inventory/hosts setup.yml --tags=COMMA_SEPARATED_TAGS_GO_HERE` + +Here are some playbook tags that you should be familiar with: + +- `setup-all` - runs all setup tasks (installation and uninstallation) for all components, but does not start/restart services + +- `install-all` - like `setup-all`, but skips uninstallation tasks. Useful for maintaining your setup quickly when its components remain unchanged. If you adjust your `vars.yml` to remove components, you'd need to run `setup-all` though, or these components will still remain installed + +- `setup-SERVICE` (e.g. `setup-postmoogle`) - runs the setup tasks only for a given role, but does not start/restart services. You can discover these additional tags in each role (`roles/**/tasks/main.yml`). Running per-component setup tasks is **not recommended**, as components sometimes depend on each other and running just the setup tasks for a given component may not be enough. For example, setting up the [mautrix-telegram bridge](configuring-playbook-bridge-mautrix-telegram.md), in addition to the `setup-mautrix-telegram` tag, requires database changes (the `setup-postgres` tag) as well as reverse-proxy changes (the `setup-nginx-proxy` tag). + +- `install-SERVICE` (e.g. `install-postmoogle`) - like `setup-SERVICE`, but skips uninstallation tasks. See `install-all` above for additional information. + +- `start` - starts all systemd services and makes them start automatically in the future + +- `stop` - stops all systemd services + +- `ensure-matrix-users-created` - a special tag which ensures that all special users needed by the playbook (for bots, etc.) are created + +`setup-*` tags and `install-*` tags **do not start services** automatically, because you may wish to do things before starting services, such as importing a database dump, restoring data from another server, etc.