Merge branch 'main' into discourse-gatekeeper/migrate

.github/ISSUE_TEMPLATE/matrix_bug_report.yml

@@ -1,6 +1,6 @@
 name: Matrix Deployment Bug Report
 description: Report a bug with the chat.ubuntu.com deployment
-labels: ["Type: Bug", "Status: Triage", "Context: deployment"]
+labels: ["Type: Bug", "Status: Triage", "Context: Deployment"]
 body:
   - type: markdown
     attributes:

.github/ISSUE_TEMPLATE/matrix_enhancement.yml

@@ -1,6 +1,6 @@
 name: Matrix Deployment Enhancement
 description: Suggest a feature for the chat.ubuntu.com deployment
-labels: ["Type: Enhancement", "Status: Triage", "deployment"]
+labels: ["Type: Enhancement", "Status: Triage", "Context: Deployment"]
 body:
   - type: markdown
     attributes:

.github/workflows/bot_pr_approval.yaml

@@ -0,0 +1,9 @@
+name: Provide approval for bot PRs
+
+on:
+  pull_request:
+
+jobs:
+  bot_pr_approval:
+    uses: canonical/operator-workflows/.github/workflows/bot_pr_approval.yaml@main
+    secrets: inherit

.github/workflows/integration_test.yaml

@@ -8,9 +8,12 @@ jobs:
     uses: canonical/operator-workflows/.github/workflows/integration_test.yaml@main
     secrets: inherit
     with:
-      chaos-app-label: app.kubernetes.io/name=synapse
-      chaos-enabled: false
-      chaos-experiments: pod-delete
+      extra-arguments: -x --localstack-address 172.17.0.1
+      pre-run-script: localstack-installation.sh
       trivy-image-config: "trivy.yaml"
+      juju-channel: 3.1/stable
+      channel: 1.28-strict/stable
+      modules: '["test_charm", "test_nginx", "test_s3", "test_redis"]'
       self-hosted-runner: true
       self-hosted-runner-label: "edge"
+      tmate-debug: true

.github/workflows/promote_charm.yaml

@@ -23,4 +23,5 @@ jobs:
     with:
       origin-channel: ${{ github.event.inputs.origin-channel }}
       destination-channel: ${{ github.event.inputs.destination-channel }}
+      doc-automation-disabled: false
     secrets: inherit

.licenserc.yaml

@@ -35,4 +35,6 @@ header:
     - 'zap_rules.tsv'
     - 'lib/**'
     - 'templates/**'
+    - 'synapse_rock/cron/**/*.py'
+    - 'synapse_rock/scripts/**/*.py'
   comment: on-failure

.woke.yaml

@@ -5,6 +5,9 @@ ignore_files:
   - tests/unit/test_synapse_workload.py
   - docs/reference/integrations.md
 rules:
+  # Ignore "master" - While https://github.com/canonical/redis-k8s-operator/pull/78
+  # is not merged
+  - name: master
   # Ignore "grandfathered" used by SAML configuration.
   - name: grandfathered
   # Ignore "whitelist" used by Synapse configuration.

README.md

@@ -30,9 +30,9 @@ project that warmly welcomes community projects, contributions, suggestions,
 fixes and constructive feedback.
 * [Code of conduct](https://ubuntu.com/community/code-of-conduct)
 * [Get support](https://discourse.charmhub.io/)
-* [Join our online chat](https://chat.charmhub.io/charmhub/channels/charm-dev)
+* [Join our online chat](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)
 * [Contribute](https://charmhub.io/synapse/docs/contributing)
 * [Getting Started](https://charmhub.io/synapse/docs/getting-started)
-Thinking about using the Synapse Operator for your next project? [Get in touch](https://chat.charmhub.io/charmhub/channels/charm-dev)!
+Thinking about using the Synapse Operator for your next project? [Get in touch](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)!
 
 ---

actions.yaml

@@ -41,3 +41,30 @@ promote-user-admin:
       description: |
         User name to be promoted to admin.
       type: string
+create-backup:
+  description: |
+    Creates a backup to s3 storage.
+list-backups:
+  description: |
+    Lists backups in s3 storage.
+restore-backup:
+  description:  |
+    Restore a Synapse backup.
+    S3 credentials are retrieved from the relation with the S3 integrator charm.
+    The server_name and filesystem configuration for the application should be
+    identical to the application restored.
+  params:
+    backup-id:
+      type: string
+      description: The backup-id to identify the backup to restore.
+  required:
+    - backup-id
+delete-backup:
+  description: |
+    Delete a backup in s3 storage by backup-id.
+  params:
+    backup-id:
+      type: string
+      description: The backup-id to identify the backup to delete.
+  required:
+    - backup-id

config.yaml

@@ -8,12 +8,21 @@ 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
     description: |
       Configures whether to enable Mjolnir - moderation tool for Matrix.
       Reference: https://github.com/matrix-org/mjolnir
+  enable_irc_bridge:
+    type: boolean
+    default: false
+    description: |
+      Configures whether to enable IRC bridging for Matrix.
+      Reference: https://github.com/matrix-org/matrix-appservice-irc 
   enable_password_config:
     type: boolean
     default: true
@@ -36,6 +45,15 @@ options:
       Comma separated list of IP address CIDR ranges that should be allowed for
       federation, identity servers, push servers, and for checking key validity
       for third-party invite events.
+  irc_bridge_admins:
+    type: string
+    description: |
+      Comma separated list of admins to be allowed to manage the bridge.
+      This takes the form of @user1:domainX.com,@user2:domainY.com...
+  notif_from:
+    type: string
+    description: defines the "From" address to use when sending emails.
+      It must be set if the SMTP integration is enabled. Defaults to server_name.
   public_baseurl:
     type: string
     description: |
@@ -53,31 +71,6 @@ options:
       Synapse server name. Must be set to deploy the charm. Corresponds to the
       server_name option on Synapse configuration file and sets the
       public-facing domain of the server.
-  smtp_enable_tls:
-    type: boolean
-    description: If enabled, STARTTLS will be used to use an encrypted SMTP
-      connection.
-    default: true
-  smtp_host:
-    type: string
-    description: The hostname of the SMTP host used for sending emails.
-    default: ''
-  smtp_notif_from:
-    type: string
-    description: defines the "From" address to use when sending emails.
-      It must be set if email sending is enabled. Defaults to server_name.
-  smtp_pass:
-    type: string
-    description: The password if the SMTP server requires authentication.
-    default: ''
-  smtp_port:
-    type: int
-    description: The port of the SMTP server used for sending emails.
-    default: 25
-  smtp_user:
-    type: string
-    description: The username if the SMTP server requires authentication.
-    default: ''
   trusted_key_servers:
     type: string
     description: Comma separated list of trusted servers to download signing

docs/explanation/charm-architecture.md

@@ -74,6 +74,11 @@ forward non-static traffic to it.
 
 The workload that this container is running is defined in the [Synapse ROCK](https://github.com/canonical/synapse-operator/tree/main/synapse_rock).
 
+If Synapse is integrated with PostgreSQL, [Synapse Stats Exporter](https://github.com/canonical/synapse_stats_exporter) will be enabled.
+Synapse Stats Exporter listens to non-TLS port `9877` and will be configured as a
+target if the charm is integrated with Prometheus. It will provide two metrics: number of rooms and
+number of users.
+
 ## Integrations
 
 See [Integrations](https://charmhub.io/synapse/docs/reference/integrations).
@@ -103,4 +108,4 @@ juju config synapse server_name=myserver.myserver.com
 self.framework.observe(self.on.config_changed, self._on_config_changed)
 4. The method `_on_config_changed` will take the necessary actions. 
 The actions include waiting for all the relations to be ready and then configuring
-the containers.
+the containers.

docs/how-to/backup-and-restore.md

@@ -0,0 +1,126 @@
+# 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](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>
+```
+
+### Create the backup
+
+Create the backup with the next command:
+```
+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](https://charmhub.io/postgresql-k8s/docs/h-create-and-list-backups).
+ - For [postgresql](https://charmhub.io/postgresql/docs/h-create-and-list-backups).
+
+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](https://charmhub.io/postgresql-k8s/docs/h-migrate-cluster-via-restore).
+ - For [postgresql](https://charmhub.io/postgresql/docs/h-migrate-cluster-via-restore).
+
+
+## Restore
+
+The recommendation is to first restore PostgreSQL if necessary. Then deploying,
+configuring and integrating Synapse with other charms as done in a normal deployment
+and finally restoring 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](https://charmhub.io/postgresql/docs/h-restore-backup), [foreign backup](https://charmhub.io/postgresql/docs/h-migrate-cluster-via-restore).
+ - for postgresql: [local restore](https://charmhub.io/postgresql/docs/h-restore-backup), [foreign backup](https://charmhub.io/postgresql/docs/h-migrate-cluster-via-restore).
+
+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, by running:
+
+```
+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 being 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.

docs/how-to/configure-smtp.md

@@ -0,0 +1,36 @@
+# How to integrate with SMTP for sending notifications
+
+This document shows how to integrate Synapse with SMTP for sending
+emails. Synapse should be deployed beforehand.
+
+## Deploy smtp-integrator charm
+
+For synapse to use SMTP, it uses the smtp-integrator charm. Replace the configuration options with your specific configuration.
+Configuring SMTP without tls or starttls or without authentication is not supported.
+
+```
+juju deploy smtp-integrator --channel edge
+juju config smtp-integrator host=<smtp host> port=<smtp port> user=<smtp auth user> password=<smtp auth password> auth_type=plain transport_security=tls
+```
+
+## Configure email to use in `From`
+
+Configure the "From" mail for Synapse with:
+```
+juju config synapse notif_from=<email to use in the "From" address>
+```
+
+## Integrate with Synapse
+
+You can run it with the legacy integration `smtp-legacy` or with
+the new integration using secrets `smtp`. A Juju version
+with secrets is required for the `smtp` integration.
+
+With the old integration without using secrets, run:
+```
+juju integrate smtp-integrator:smtp-legacy synapse:smtp
+```
+For the new integration with secrets, run:
+```
+juju integrate smtp-integrator:smtp synapse:smtp
+```

docs/how-to/contribute.md

@@ -9,7 +9,7 @@ enhancements to the Synapse operator.
 [opening an issue](https://github.com/canonical/synapse-operator/issues)
 explaining your use case.
 - If you would like to chat with us about your use-cases or proposed
-implementation, you can reach us at [Canonical Mattermost public channel](https://chat.charmhub.io/charmhub/channels/charm-dev)
+implementation, you can reach us at [Canonical Matrix public channel](https://matrix.to/#/#charmhub-charmdev:ubuntu.com)
 or [Discourse](https://discourse.charmhub.io/).
 - Familiarising yourself with the [Charmed Operator Framework](https://juju.is/docs/sdk)
 library will help you a lot when working on new features or bug fixes.
@@ -80,12 +80,10 @@ and synapse-nginx images are required in the microk8s registry. To enable it:
 The following commands import the images in the Docker daemon and push them into
 the registry:
 
-    cd [project_dir]/synapse_rock && rockcraft pack rockcraft.yaml
-    skopeo --insecure-policy copy oci-archive:synapse_1.0_amd64.rock docker-daemon:localhost:32000/synapse:latest
-    docker push localhost:32000/synapse:latest
-    cd [project_dir]/nginx_rock && rockcraft pack rockcraft.yaml
-    skopeo --insecure-policy copy oci-archive:synapse_nginx_1.0_amd64.rock docker-daemon:localhost:32000/synapse-nginx:latest
-    docker push localhost:32000/synapse-nginx:latest
+    cd [project_dir]/synapse_rock && rockcraft pack
+    skopeo --insecure-policy copy --dest-tls-verify=false oci-archive:synapse_1.0_amd64.rock docker://localhost:32000/synapse:latest
+    cd [project_dir]/nginx_rock && rockcraft pack
+    skopeo --insecure-policy copy --dest-tls-verify=false oci-archive:synapse-nginx_1.0_amd64.rock docker://localhost:32000/synapse-nginx:latest
 
 ### Deploy
 
@@ -95,7 +93,7 @@ juju add-model synapse-dev
 # Enable DEBUG logging
 juju model-config logging-config="<root>=INFO;unit=DEBUG"
 # Deploy the charm (assuming you're on amd64)
-juju deploy ./synapse_ubuntu-20.04-amd64.charm \
+juju deploy ./synapse_ubuntu-22.04-amd64.charm \
   --resource synapse-image=localhost:32000/synapse:latest \
   --resource synapse-nginx-image=localhost:32000/synapse-nginx:latest
 ```