Edit docs/maintenance-migrating.md: replace the numbering list with sections for each item

Also: add an ansible-playbook command with the stop tag as the main command to stop the Matrix services.

Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org>

docs/maintenance-migrating.md

@@ -4,11 +4,58 @@
 
 # Migrating to new server
 
-1. Prepare by lowering DNS TTL for your domains (`matrix.example.com`, etc.), so that DNS record changes (step 4 below) would happen faster, leading to less downtime
-2. Stop all services on the old server and make sure they won't be starting again. Execute this on the old server: `systemctl disable --now matrix*` (you might have to cd to /etc/systemd/system/ first)
-3. Copy directory `/matrix` from the old server to the new server. Make sure to preserve ownership and permissions (use `cp -p` or `rsync -ar`)!
-4. Make sure your DNS records are adjusted to point to the new server's IP address
-5. Remove old server from the `inventory/hosts` file and add new server.
-6. Run `ansible-playbook -i inventory/hosts setup.yml --tags=setup-system-user`. This will create the `matrix` user and group on the new server
-7. Because the `matrix` user and group are created dynamically on each server, the user/group ID may differ between the old and new server. We suggest that you adjust ownership of `/matrix` files manually by running this on the new server: `chown -R matrix:matrix /matrix`.
-8. Run `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start` to finish the installation and start all services
+This documentation explains how to migrate your Matrix services (server, client, bridges, etc.) from an old server to a new server.
+
+## Lower DNS TTL
+
+Prepare by lowering DNS TTL for your domains (`matrix.example.com`, etc.), so that DNS record changes would happen faster, leading to less downtime.
+
+## Stop services on the old server
+
+Before migrating, you need to stop all services on the old server and make sure they won't be starting again.
+
+To stop the services, go to the `matrix-docker-ansible-deploy` directory on your local computer, and run the command:
+
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=stop
+```
+
+Alternatively, you can log in to the old server and run the command (you might have to `cd` to `/etc/systemd/system/` first):
+
+```sh
+systemctl disable --now matrix*
+```
+
+## Copy data directory from the old to the new server
+
+Then, copy directory `/matrix` from the old server to the new server. When copying, make sure to preserve ownership and permissions (use `cp -p` or `rsync -ar`)!
+
+## Adjust DNS records
+
+Make sure your DNS records are adjusted to point to the new server's IP address.
+
+## Update `hosts` file
+
+Having adjusted DNS records, remove old server from the `inventory/hosts` file, and add new server to it.
+
+## Create `matrix` user and group on the new server
+
+After updating `inventory/hosts` file, run the command below to create the `matrix` user and group on the new server:
+
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-system-user
+```
+
+**Note**: because the `matrix` user and group are created dynamically on each server, the user/group ID may differ between the old and new server. We suggest that you adjust ownership of `/matrix` files. To adjust the ownership, log in to the new server and run the command:
+
+```sh
+chown -R matrix:matrix /matrix
+```
+
+## Start all services on the new server
+
+Finally, run the command below to finish the installation and start all services:
+
+```sh
+ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start
+```