How to back up and restore Synapse
This document shows how to back up and restore Synapse.
The process of backing up and restoring depends on whether an external database is used, so the step to run the backup for PostgreSQL must be done only if PostgreSQL is used in the original Synapse application.
It is important to note that data inside the s3 bucket for media storage is essential to be included as part of the backup/restore.
Back up Synapse
Deploy s3-integrator charm
Synapse gets backed up to a S3 compatible object storage. The bucket for the backup should be provisioned before the backup is performed.
For Synapse to get the credentials, the s3-integrator is used. Refer to s3-integrator for specific configuration options.
juju deploy s3-integrator --channel edge
juju config s3-integrator endpoint=<s3 endpoint> bucket=<bucket name> path=<optional-path> region=<region> s3-uri-style=<path or host>
juju run s3-integrator/leader sync-s3-credentials access-key=<access-key> secret-key=<secret-key>
Integrate with Synapse using:
juju integrate synapse:backup s3-integrator
Configure the passphrase
The backup will be encrypted before being sent using symmetric encryption. You need to set the desired password with:
juju config synapse backup_passphrase=<secret passphase>
Create the backup
Create the backup:
juju run synapse/leader create-backup
A new object should be placed in the S3 compatible object storage, a tar file encrypted with the gpg command.
You can list the available backups with the list-backups command:
juju run synapse/leader list-backups
Back up PostgreSQL
Follow the instructions of the PostgreSQL charm:
- For postgresql-k8s.
- For postgresql.
If you plan to restore PostgreSQL in a different model or cluster, you will need to also back up the cluster passwords. See:
- For postgresql-k8s.
- For postgresql.
Restore
The recommendation is to first restore PostgreSQL if necessary. Then deploy, configure and integrate Synapse with other charms as done in a normal deployment. Finally, restore Synapse.
The PostgreSQL and Synapse charm revisions should be the same ones as the ones used
for the backup. The configuration for Synapse before restoring the backup should also
match the configuration in the original application. This is specially important for
the configuration option server_name and any other configuration related to the filesystem.
Restore PostgreSQL
If you use the PostgreSQL integration, follow the instructions given by PostgreSQL:
- For postgresql-k8s: local restore, foreign backup.
- for postgresql: local restore, foreign backup.
If you used the foreign backup, once the backup for PostgreSQL is restored, you should remove the S3 integration, as it was created in a different cluster:
juju remove-relation s3-integrator postgresql
Deploy Synapse
Synapse should be deployed, integrated with all necessary charms and configured. If necessary, Synapse should be integrated with the PostgreSQL charm that has already been restored.
Restore Synapse
Set the backup_passphrase to the passphrase used for the backup.
juju config synapse backup_passphrase=<secret passphase>
Integrate with S3, following the same instructions as in the backup procedure, that is, similar to:
juju deploy s3-integrator --channel edge
juju config s3-integrator endpoint=<s3 endpoint> bucket=<bucket name> path=<optional-path> region=<region> s3-uri-style=<path or host>
juju run s3-integrator/leader sync-s3-credentials access-key=<access-key> secret-key=<secret-key>
Integrate with Synapse with:
juju integrate synapse:backup s3-integrator
List the backups and take note of the desired backup-id
juju run synapse/leader list-backups
Restore the backup:
juju run synapse/leader restore-backup backup-id=<backup-id from the list of backups>
At this point, Synapse should be active and the restore procedure complete.