From 27ede17d3a5a4741b1b8ebe70d442c6abc8462ce Mon Sep 17 00:00:00 2001 From: Suguru Hirahara Date: Sun, 17 Nov 2024 16:47:32 +0900 Subject: [PATCH] Add description about keeping the playbook and services up-to-date Also: move descriptions about difference between the playbook tags (setup-all and install-all) and about the just "recipe" from installing.md to maintenance-upgrading-services.md Signed-off-by: Suguru Hirahara --- docs/installing.md | 10 +++++++--- docs/maintenance-upgrading-services.md | 22 ++++++++++++++++++++-- docs/quick-start.md | 18 ++++++++++++++++++ 3 files changed, 45 insertions(+), 5 deletions(-) diff --git a/docs/installing.md b/docs/installing.md index f6b61d5ef..d517bf342 100644 --- a/docs/installing.md +++ b/docs/installing.md @@ -125,8 +125,12 @@ After finilizing the installation, you can: ### Maintaining your setup in the future -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. To update the playbook and the Ansible roles in the playbook, simply run `just roles`. +While this playbook helps you to set up Matrix services and maintain them, it will **not** automatically run the maintenance task for you. You will need to update the playbook and re-run it **manually**. -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. +The upstream projects, which this playbook makes use of, occasionally if not often suffer from security vulnerabilities. -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 the "recipe": `just install-all` or `just setup-all`. See [our `justfile`](../justfile) for more information. +Since it is unsafe to keep outdated services running on the server connected to the internet, please consider to update the playbook and re-run it periodically, in order to keep the services up-to-date. + +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. diff --git a/docs/maintenance-upgrading-services.md b/docs/maintenance-upgrading-services.md index ea7ffb4d7..8b11c891e 100644 --- a/docs/maintenance-upgrading-services.md +++ b/docs/maintenance-upgrading-services.md @@ -2,9 +2,19 @@ This playbook not only installs the various Matrix services for you, but can also upgrade them as new versions are made available. +While this playbook helps you to set up Matrix services and maintain them, it will **not** automatically run the maintenance task for you. You will need to update the playbook and re-run it **manually**. + +The upstream projects, which this playbook makes use of, occasionally if not often suffer from security vulnerabilities (for example, see [here](https://github.com/element-hq/element-web/security) for known ones on Element Web). + +Since it is unsafe to keep outdated services running on the server connected to the internet, please consider to update the playbook and re-run it periodically, in order to keep the services up-to-date. + +The developers of this playbook strive to maintain the playbook updated, so that you can re-run the playbook to address such vulnerabilities. It is **your responsibility** to keep your server and the services on it up-to-date. + If you want to be notified when new versions of Synapse are released, you should join the Synapse Homeowners room: [#homeowners:matrix.org](https://matrix.to/#/#homeowners:matrix.org). -To upgrade services: +## Steps to upgrade the Matrix services + +To upgrade the services: - update your playbook directory and all upstream Ansible roles (defined in the `requirements.yml` file) using: @@ -13,6 +23,14 @@ To upgrade services: - 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 -- re-run the [playbook setup](installing.md) and restart all services: `just install-all` or `just setup-all` +- re-run the [playbook setup](installing.md#maintaining-your-setup-in-the-future) and restart all services: + + ```sh + ansible-playbook -i inventory/hosts setup.yml --tags=install-all,start + ``` + +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 is to use [just](https://github.com/casey/just) to run the "recipe": `just install-all` or `just setup-all`. See [our `justfile`](../justfile) for more information. **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). diff --git a/docs/quick-start.md b/docs/quick-start.md index 83f15c9cd..7e6041741 100644 --- a/docs/quick-start.md +++ b/docs/quick-start.md @@ -158,3 +158,21 @@ Come say Hi👋 in our support room - [#matrix-docker-ansible-deploy:devture.com Once you get familiar with the playbook, you might probably want to set up additional services such as a bridge on your server. As this page intends to be a quick start guide which explains how to start the core Matrix services, it does not cover a topic like how to set them up. Take a look at the list of [things to do next](installing.md#things-to-do-next) to learn more. + +### ⚠️Keep the playbook and services up-to-date + +This section is optimized for this quick-start guide and is derived from the following full-documentation page: [Upgrading the Matrix services](maintenance-upgrading-services.md) + +While this playbook helps you to set up Matrix services and maintain them, it will **not** automatically run the maintenance task for you. You will need to update the playbook and re-run it **manually**. + +Since it is unsafe to keep outdated services running on the server connected to the internet, please consider to update the playbook and re-run it periodically, in order to keep the services up-to-date. + +Before updating the playbook and the Ansible roles in the playbook, 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. + +If it looks good to you, go to the `matrix-docker-ansible-deploy` directory and run `just update`. + +Then, re-run the setup command as below: + +```sh +ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start +```