Merge origin/main

actions.yaml

@@ -41,3 +41,6 @@ promote-user-admin:
       description: |
         User name to be promoted to admin.
       type: string
+create-backup:
+  description: |
+    Creates a backup to s3 storage.

config.yaml

@@ -8,6 +8,9 @@ options:
     description: |
       Allows any other homeserver to fetch the server's public rooms directory
       via federation.
+  backup_passphrase:
+    type: string
+    description: Passphrase used to encrypt a backup using gpg with symmetric key.
   enable_mjolnir:
     type: boolean
     default: false

docs/how-to/backup.md

@@ -0,0 +1,36 @@
+# How to back up Synapse
+
+This document shows how to back up Synapse.
+
+## Deploy s3-integrator charm
+
+Synapse gets backed up to a S3 compatible object storage. To get the credentials, the `s3-integrator` is used. Refer to
+[s3-integrator](https://charmhub.io/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 with:
+
+`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>
+```
+
+## Run the backup
+
+Run the backup with the next command:
+```
+juju run synapse/leader create-backup
+```
+
+A new object should be placed in the S3 compatible object storage. This file is a tar
+file encrypted with the `gpg` command.

requirements.txt

@@ -3,5 +3,5 @@ ops ==2.10.0
 pydantic ==1.10.14
 psycopg2-binary ==2.9.9
 requests == 2.31.0
-cosl ==0.0.7
-boto3 ==1.34.35
+boto3 ==1.34.36
+cosl ==0.0.8

src-docs/backup.py.md

@@ -5,14 +5,67 @@
 # <kbd>module</kbd> `backup.py`
 Provides backup functionality for Synapse. 
 
+**Global Variables**
+---------------
+- **AWS_COMMAND**
+- **BACKUP_FILE_PATTERNS**
+- **MEDIA_LOCAL_DIR_PATTERN**
+- **S3_MAX_CONCURRENT_REQUESTS**
+- **PASSPHRASE_FILE**
+- **BASH_COMMAND**
+- **BACKUP_ID_FORMAT**
+
+---
+
+<a href="../src/backup.py#L165"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+
+## <kbd>function</kbd> `create_backup`
+
+```python
+create_backup(
+    container: Container,
+    s3_parameters: S3Parameters,
+    passphrase: str
+) → str
+```
+
+Create a backup for Synapse running it in the workload. 
+
+
+
+**Args:**
+
+ - <b>`container`</b>:  Synapse Container 
+ - <b>`s3_parameters`</b>:  S3 parameters for the backup. 
+ - <b>`passphrase`</b>:  Passphrase use to encrypt the backup. 
+
+
+
+**Returns:**
+ The backup key used for the backup. 
+
+
+
+**Raises:**
+
+ - <b>`BackupError`</b>:  If there was an error creating the backup. 
+
+
+---
+
+## <kbd>class</kbd> `BackupError`
+Generic backup Exception. 
+
+
+
 
 
 ---
 
 ## <kbd>class</kbd> `S3Client`
 S3 Client Wrapper around boto3 library. 
 
-<a href="../src/backup.py#L77"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/backup.py#L109"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ### <kbd>function</kbd> `__init__`
 
@@ -33,7 +86,7 @@ Initialize the S3 client.
 
 ---
 
-<a href="../src/backup.py#L116"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/backup.py#L148"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ### <kbd>function</kbd> `can_use_bucket`
 
@@ -87,7 +140,7 @@ Translates s3_uri_style to AWS addressing_style.
 
 ---
 
-<a href="../src/backup.py#L44"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/backup.py#L76"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ### <kbd>classmethod</kbd> `check_endpoint_or_region_set`
 

src-docs/backup_observer.py.md

@@ -16,7 +16,7 @@ S3 Backup relation observer for Synapse.
 ## <kbd>class</kbd> `BackupObserver`
 The S3 backup relation observer. 
 
-<a href="../src/backup_observer.py#L25"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
+<a href="../src/backup_observer.py#L28"><img align="right" style="float:right;" src="https://img.shields.io/badge/-source-cccccc?style=flat-square"></a>
 
 ### <kbd>function</kbd> `__init__`