matrix-docker-ansible-deploy/docs/maintenance-migrating.md

> **Note**: This migration guide is applicable if you migrate from one server to another server having the same CPU architecture (e.g. both servers being `amd64`).
>
> If you're trying to migrate between different architectures (e.g. `amd64` --> `arm64`), simply copying the complete `/matrix` directory is not possible as it would move the raw PostgreSQL data (`/matrix/postgres/data`) between different architectures. In this specific case, you can use the guide below as a reference, but you would also need to avoid syncing `/matrix/postgres/data` to the new host, and also dump the database on your current server and import it properly on the new server. See our [Backing up PostgreSQL](maintenance-postgres.md#backing-up-postgresql) docs for help with PostgreSQL backup/restore.

# Migrating to new server

1. Prepare by lowering DNS TTL for your domains (`matrix.DOMAIN`, 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
Update migrating guide to make it clear that switching CPU architecture requires skipping /matrix/postgres/data 2024-07-08 12:33:50 +08:00			> Note: This migration guide is applicable if you migrate from one server to another server having the same CPU architecture (e.g. both servers being `amd64`).
			`>`
			> If you're trying to migrate between different architectures (e.g. `amd64` --> `arm64`), simply copying the complete `/matrix` directory is not possible as it would move the raw PostgreSQL data (`/matrix/postgres/data`) between different architectures. In this specific case, you can use the guide below as a reference, but you would also need to avoid syncing `/matrix/postgres/data` to the new host, and also dump the database on your current server and import it properly on the new server. See our [Backing up PostgreSQL](maintenance-postgres.md#backing-up-postgresql) docs for help with PostgreSQL backup/restore.
Annotate server migration Annotate server migration with a note in regard to migration between different architectures and the need to dump/restore the database. 2021-05-26 22:30:08 +08:00
Added a basic guide on migrating to another server 2019-06-12 04:06:25 +08:00			`# Migrating to new server`

fix typo ot -> to 2021-03-18 03:29:17 +08:00			1. Prepare by lowering DNS TTL for your domains (`matrix.DOMAIN`, etc.), so that DNS record changes (step 4 below) would happen faster, leading to less downtime
Add a small tip to maintenance-migrating.md 2023-08-30 16:00:32 +08:00			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)
Make instructions simpler and safer Changes to the original are: - it tells people to stop and disable services, so that: - services won't be running while you are copying files - services won't accidentally start again later - it does the file-copying in 1 step - it does copying before running `--tags=setup-all`, so that existing files (SSL certificates, etc.) can be reused. Otherwise, the playbook starts from a blank slate, retrieves them anew, generates new signing keys anew, etc. Only to have those replaced by your own old backup later. - it mentions DNS changes - combines `--tags=setup-all,start` into a single step, thanks to the files being already copied 2019-06-12 14:36:19 +08:00			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.
Fix "Migrating to a new server" flow due to dynamic user/group creation 2020-05-06 14:55:40 +08:00			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
Fix capitalization: id → ID Signed-off-by: Suguru Hirahara <acioustick@noreply.codeberg.org> 2024-10-16 01:24:34 +08:00			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`.
Fix "Migrating to a new server" flow due to dynamic user/group creation 2020-05-06 14:55:40 +08:00			8. Run `ansible-playbook -i inventory/hosts setup.yml --tags=setup-all,start` to finish the installation and start all services