|
| 1 | +# How to back up and restore Synapse |
| 2 | + |
| 3 | +This document shows how to back up and restore Synapse. |
| 4 | + |
| 5 | +The process of backing up and restoring depends on whether an external database |
| 6 | +is used, so the step to run the backup for PostgreSQL must be done only if PostgreSQL |
| 7 | +is used in the original Synapse application. |
| 8 | + |
| 9 | +It is important to note that data inside the s3 bucket for media storage is essential |
| 10 | +to be included as part of the backup/restore. |
| 11 | + |
| 12 | +## Back up Synapse |
| 13 | + |
| 14 | +### Deploy s3-integrator charm |
| 15 | + |
| 16 | +Synapse gets backed up to a S3 compatible object storage. The bucket for the backup should be provisioned before the backup is performed. |
| 17 | + |
| 18 | +For Synapse to get the credentials, the `s3-integrator` is used. Refer to [s3-integrator](https://charmhub.io/s3-integrator/) for specific configuration options. |
| 19 | + |
| 20 | +``` |
| 21 | +juju deploy s3-integrator --channel edge |
| 22 | +juju config s3-integrator endpoint=<s3 endpoint> bucket=<bucket name> path=<optional-path> region=<region> s3-uri-style=<path or host> |
| 23 | +juju run s3-integrator/leader sync-s3-credentials access-key=<access-key> secret-key=<secret-key> |
| 24 | +``` |
| 25 | + |
| 26 | +Integrate with Synapse with: |
| 27 | + |
| 28 | +`juju integrate synapse:backup s3-integrator` |
| 29 | + |
| 30 | +### Configure the passphrase |
| 31 | + |
| 32 | +The backup will be encrypted before being sent using symmetric encryption. You need |
| 33 | +to set the desired password with: |
| 34 | +``` |
| 35 | +juju config synapse backup_passphrase=<secret passphase> |
| 36 | +``` |
| 37 | + |
| 38 | +### Create the backup |
| 39 | + |
| 40 | +Create the backup with the next command: |
| 41 | +``` |
| 42 | +juju run synapse/leader create-backup |
| 43 | +``` |
| 44 | + |
| 45 | +A new object should be placed in the S3 compatible object storage, a tar file encrypted with the `gpg` command. |
| 46 | + |
| 47 | + |
| 48 | +You can list the available backups with the `list-backups` command: |
| 49 | +``` |
| 50 | +juju run synapse/leader list-backups |
| 51 | +``` |
| 52 | + |
| 53 | +### Back up PostgreSQL |
| 54 | + |
| 55 | +Follow the instructions of the PostgreSQL charm: |
| 56 | + - For [postgresql-k8s](https://charmhub.io/postgresql-k8s/docs/h-create-and-list-backups). |
| 57 | + - For [postgresql](https://charmhub.io/postgresql/docs/h-create-and-list-backups). |
| 58 | + |
| 59 | +If you plan to restore PostgreSQL in a different model or cluster, you will need |
| 60 | +to also back up the cluster passwords. See: |
| 61 | + - For [postgresql-k8s](https://charmhub.io/postgresql-k8s/docs/h-migrate-cluster-via-restore). |
| 62 | + - For [postgresql](https://charmhub.io/postgresql/docs/h-migrate-cluster-via-restore). |
| 63 | + |
| 64 | + |
| 65 | +## Restore |
| 66 | + |
| 67 | +The recommendation is to first restore PostgreSQL if necessary. Then deploying, |
| 68 | +configuring and integrating Synapse with other charms as done in a normal deployment |
| 69 | +and finally restoring Synapse. |
| 70 | + |
| 71 | +The PostgreSQL and Synapse charm revisions should be the same ones as the ones used |
| 72 | +for the backup. The configuration for Synapse before restoring the backup should also |
| 73 | +match the configuration in the original application. This is specially important for |
| 74 | +the configuration option `server_name` and any other configuration related to the filesystem. |
| 75 | + |
| 76 | + |
| 77 | +### Restore PostgreSQL |
| 78 | + |
| 79 | + |
| 80 | +If you use the PostgreSQL integration, follow the instructions given by PostgreSQL: |
| 81 | + - For postgresql-k8s: [local restore](https://charmhub.io/postgresql/docs/h-restore-backup), [foreign backup](https://charmhub.io/postgresql/docs/h-migrate-cluster-via-restore). |
| 82 | + - for postgresql: [local restore](https://charmhub.io/postgresql/docs/h-restore-backup), [foreign backup](https://charmhub.io/postgresql/docs/h-migrate-cluster-via-restore). |
| 83 | + |
| 84 | +If you used the foreign backup, once the backup for PostgreSQL is restored, you should remove the S3 integration, |
| 85 | +as it was created in a different cluster, by running: |
| 86 | + |
| 87 | +``` |
| 88 | +juju remove-relation s3-integrator postgresql |
| 89 | +``` |
| 90 | + |
| 91 | +### Deploy Synapse |
| 92 | + |
| 93 | +Synapse should be deployed, integrated with all necessary charms and configured. If necessary, Synapse should be integrated with the PostgreSQL charm that |
| 94 | +has already being restored. |
| 95 | + |
| 96 | +### Restore Synapse |
| 97 | + |
| 98 | + |
| 99 | +Set the `backup_passphrase` to the passphrase used for the backup. |
| 100 | +``` |
| 101 | +juju config synapse backup_passphrase=<secret passphase> |
| 102 | +``` |
| 103 | + |
| 104 | +Integrate with S3, following the same instructions as in the backup procedure, that is, similar to: |
| 105 | + |
| 106 | +``` |
| 107 | +juju deploy s3-integrator --channel edge |
| 108 | +juju config s3-integrator endpoint=<s3 endpoint> bucket=<bucket name> path=<optional-path> region=<region> s3-uri-style=<path or host> |
| 109 | +juju run s3-integrator/leader sync-s3-credentials access-key=<access-key> secret-key=<secret-key> |
| 110 | +``` |
| 111 | + |
| 112 | +Integrate with Synapse with: |
| 113 | + |
| 114 | +`juju integrate synapse:backup s3-integrator` |
| 115 | + |
| 116 | +List the backups and take note of the desired `backup-id` |
| 117 | +``` |
| 118 | +juju run synapse/leader list-backups |
| 119 | +``` |
| 120 | + |
| 121 | +Restore the backup: |
| 122 | +``` |
| 123 | +juju run synapse/leader restore-backup backup-id=<backup-id from the list of backups> |
| 124 | +``` |
| 125 | + |
| 126 | +At this point, Synapse should be active and the restore procedure complete. |
0 commit comments