Repository: canonical/synapse-operator
Pull request #748: Add docs for upgrading from latest/edge to 2/edge. Add config option to allow changing the OIDC subject claim
Author: login: Thanhphan1147
Labels: name: documentation
description: Improvements or additions to documentation
name: Libraries: Out of sync
name: complex
Created: 2025-03-28T19:26:11Z | Merged: 2025-04-05T13:08:54Z

As we don’t support direct automatic upgrade from the legacy synapse charm on latest/edge to 2/edge, we need to document the manual upgrade process, this should cover:
* Setting up OIDC for MAS ( required to migrate homeservers using SAML )
* Moving the users from synapse to MAS
* Migrate the database from the old synapse instance to the new synapse instance
* Update the OIDC subject claim

This PR also adds a configuration option to set the oauth provider's subject claim.

### Checklist

- [x] The [charm style guide](https://juju.is/docs/sdk/styleguide) was applied
- [x] The [contributing guide](https://github.com/canonical/is-charms-contributing-guide) was applied
- [x] The changes are compliant with [ISD054 - Manging Charm Complexity](https://discourse.charmhub.io/t/specification-isd014-managing-charm-complexity/11619)
- [x] The documentation for charmhub is updated.
- [x] The PR is tagged with appropriate label (`urgent`, `trivial`, `complex`)
- [x] The changelog is updated with changes that affect the users of the charm.

<!-- Explanation for any unchecked items above -->



Diff:
diff --git a/config.yaml b/config.yaml
index c39648982..2ebb97931 100644
--- a/config.yaml
+++ b/config.yaml
@@ -128,3 +128,10 @@ options:
       setting instance_map and stream writers. This configuration should be used
       in case of unrecoverable broken units and takes the form of
       worker0,worker1
+  oidc_subject_claim:
+    type: string
+    default: user.email
+    description: |
+      For advanced use only! Only relevant if synapse is related to an oauth provider.
+      Configure the subject claim that is used to map upstream provider users to local
+      MAS users.  
diff --git a/docs/how-to/migrate-to-mas.md b/docs/how-to/migrate-to-mas.md
new file mode 100644
index 000000000..9c17a66c9
--- /dev/null
+++ b/docs/how-to/migrate-to-mas.md
@@ -0,0 +1,158 @@
+# How to migrate Synapse to the `2/edge` track
+This document shows how to migrate a legacy Synapse homeserver (`1/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `1/edge` track that uses the `saml-integrator` charm to provide authentication via SAML.
+
+> **_NOTE:_** The existing synapse charm is deployed with the name `server`.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will deploy the new synapse charm with the name `server-mas`. We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with the `postgresql-k8s` charm
+Integrate with the existing `postgresql-k8s` charm to set up the database for the new charm. Note that you need to integrate with the `postgresql-k8s` charm via both the `database` and the `mas-database` endpoints.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers. For example, to use the Google IdP, we will deploy the `oauth-external-idp-integrator` charm.
+
+Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration`.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju integrate server-mas oidc
+```
+
+Finally, we need to allow the MAS redirect URL on the OIDC client. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be formatted like `<public_baseurl>/auth/upstream/callback/<provider_id>`. We can now go back to the OIDC client configuration on the IdP and add the redirect URL to the allowlist. 
+
+## Back up the existing synapse charm and restore on the new synapse charm
+### Back up and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Back up and Restore"](https://charmhub.io/synapse/docs/how-to-backup-and-restore) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target S3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup:
+```
+juju integrate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID; we will use it to restore the backup on the new synapse charm.
+```
+juju integrate s3-integrator server-mas
+juju run synapse/leader restore-backup backup-id=<backup-id>
+```
+
+## Synapse database migration
+Stop all services on the new and the existing synapse charms:
+```
+juju ssh --container synapse server-mas/0 "pebble stop synapse; pebble stop synapse-mas; pebble stop stats-exporter"
+juju ssh --container synapse server/0 "pebble stop synapse; pebble stop stats-exporter"
+```
+
+Connect the new synapse charm to the database:
+```
+juju ssh --container synapse server-mas/0 bash
+```
+
+The following commands assume that you are in the `synapse` container of the `server-mas` application.
+```
+apt update
+apt install wget postgresql-client -y
+wget https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64 -O /usr/bin/yq && chmod +x /usr/bin/yq
+```
+
+Copy the original synapse charm database:
+```
+DB_HOST=$(yq e '.database.args.host' /data/homeserver.yaml)
+DB_PORT=$(yq e '.database.args.port' /data/homeserver.yaml)
+DB_PASSWORD=$(yq e '.database.args.password' /data/homeserver.yaml)
+DB_USER=$(yq e '.database.args.user' /data/homeserver.yaml)
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c 'drop database "server-mas";'
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c "create database \"server-mas\" with template server owner $DB_USER;"
+```
+
+In case where postgres gives you an error saying "ERROR:  source database "synapse" is being accessed by other users", drop all connections from the database:
+
+First log in to the database:
+```
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres
+```
+
+Then run this SQL query to drop all connection from the relevant database ( `<database_name>` ):
+```
+SELECT pg_terminate_backend(pg_stat_activity.pid) FROM pg_stat_activity 
+WHERE pg_stat_activity.datname = '<database_name>' AND pid <> pg_backend_pid();
+```
+
+## Migrate users to MAS
+### Perform user migration to MAS database
+Run the `migrate` command with the `--dryRun` flag to check that there are no errors:
+```
+OAUTH2_PROVIDER_ID=$(yq e '.upstream_oauth2.providers[0].id' /mas/config.yaml)
+npx --yes @vector-im/syn2mas \
+    --command migrate \
+    --synapseConfigFile /data/homeserver.yaml \
+    --masConfigFile /mas/config.yaml \
+    --upstreamProviderMapping saml:$OAUTH2_PROVIDER_ID \
+    --dryRun
+```
+
+You should see the 0 fatals and 0 warnings in the command output:
+```
+[INFO] migrate - Completed migration dry-run of x users with 0 fatals and 0 warnings:
+```
+
+Finally, run the migration command:
+```
+npx --yes @vector-im/syn2mas \
+    --command migrate \
+    --synapseConfigFile /data/homeserver.yaml \
+    --masConfigFile /mas/config.yaml \
+    --upstreamProviderMapping saml:$OAUTH2_PROVIDER_ID
+```
+
+You should see an output similar to that of the dry-run command.
+
+### Configure the OIDC subject claim
+After the migration, the `external_id` of the Synapse user is used as the OIDC subject in MAS. Most of the time, this needs to be changed so that the local account gets recognized by MAS when authenticating with the upstream provider. 
+
+```
+psql $(yq e '.database.uri' /mas/config.yaml)
+```
+
+Then run the appropriate SQL command to update the subject field. For example, to use the email address as the OIDC subject, we run this SQL query:
+```
+update upstream_oauth_links
+SET subject=(select email from user_emails where upstream_oauth_links.user_id=user_emails.user_id);
+```
+
+After updating the OIDC subject in the MAS database, we need to also configure the OIDC subject claim. **On the host machine**, run:
+```
+juju config server-mas oidc_subject_claim=user.email
+```
diff --git a/src/auth/mas.py b/src/auth/mas.py
index d485276b4..42a2e75f0 100644
--- a/src/auth/mas.py
+++ b/src/auth/mas.py
@@ -22,22 +22,6 @@
 MAS_WORKING_DIR = "/mas"
 MAS_CONFIGURATION_PATH = f"{MAS_WORKING_DIR}/config.yaml"
 
-MAS_PEBBLE_LAYER = ops.pebble.LayerDict(
-    {
-        "summary": "Matrix Authentication Service layer",
-        "description": "pebble config layer for MAS",
-        "services": {
-            MAS_SERVICE_NAME: {
-                "override": "replace",
-                "summary": "Matrix Authentication Service",
-                "startup": "enabled",
-                "command": f"{MAS_EXECUTABLE_PATH} server -c {MAS_CONFIGURATION_PATH}",
-                "working-dir": MAS_WORKING_DIR,
-            }
-        },
-    }
-)
-
 MAS_AUTHORIZATION_GRANT = ["authorization_code"]
 MAS_OIDC_SCOPE = "openid profile email"
 # Disabling bandit checks since these are only the labels for juju secret
@@ -259,6 +243,7 @@ def generate_mas_config(
         "oauth_provider_info": oauth_provider_info,
         "mas_oidc_scope": MAS_OIDC_SCOPE,
         "smtp_configuration": smtp_configuration,
+        "oidc_subject_claim": f'"{{{{ {mas_context.oidc_subject_claim} }}}}"',
     }
     env = Environment(
         loader=FileSystemLoader("./templates"),
diff --git a/src/pebble.py b/src/pebble.py
index bc3607489..d0050ca2f 100644
--- a/src/pebble.py
+++ b/src/pebble.py
@@ -19,8 +19,9 @@
 import synapse
 from auth.mas import (
     MAS_CONFIGURATION_PATH,
-    MAS_PEBBLE_LAYER,
+    MAS_EXECUTABLE_PATH,
     MAS_SERVICE_NAME,
+    MAS_WORKING_DIR,
     sync_mas_config,
     validate_mas_config,
 )
@@ -187,13 +188,14 @@ def replan_synapse_federation_sender(
     container.replan()
 
 
-def replan_mas(container: ops.model.Container) -> None:
+def replan_mas(container: ops.model.Container, charm_state: CharmState) -> None:
     """Replan Matrix Authentication Service.
 
     Args:
         container: Charm container.
+        charm_state: Instance of CharmState.
     """
-    container.add_layer(MAS_SERVICE_NAME, MAS_PEBBLE_LAYER, combine=True)
+    container.add_layer(MAS_SERVICE_NAME, _mas_pebble_layer(charm_state), combine=True)
     container.replan()
 
 
@@ -315,7 +317,7 @@ def reconcile(  # noqa: C901
         PebbleServiceError: if something goes wrong while interacting with Pebble.
     """
     try:
-        restart_mas(container, rendered_mas_configuration)
+        restart_mas(container, rendered_mas_configuration, charm_state)
 
         if _environment_has_changed(container=container, charm_state=charm_state, is_main=is_main):
             # Configurations set via environment variables:
@@ -591,6 +593,39 @@ def _moderation_pebble_layer() -> ops.pebble.LayerDict:
     return typing.cast(ops.pebble.LayerDict, layer)
 
 
+def _mas_pebble_layer(charm_state: CharmState) -> ops.pebble.LayerDict:
+    """Generate pebble config for the MAS service.
+
+    Args:
+        charm_state: Instance of CharmState
+
+    Returns:
+        The pebble configuration for the MAS service.
+    """
+    environment = {}
+    for proxy in ("http_proxy", "https_proxy", "no_proxy"):
+        proxy_value = getattr(charm_state.proxy, proxy)
+        if proxy_value:
+            environment[proxy] = str(proxy_value)
+            environment[proxy.upper()] = str(proxy_value)
+
+    layer = {
+        "summary": "Matrix Authentication Service layer",
+        "description": "pebble config layer for MAS",
+        "services": {
+            MAS_SERVICE_NAME: {
+                "override": "replace",
+                "summary": "Matrix Authentication Service",
+                "startup": "enabled",
+                "command": f"{MAS_EXECUTABLE_PATH} server -c {MAS_CONFIGURATION_PATH}",
+                "working-dir": MAS_WORKING_DIR,
+                "environment": environment,
+            }
+        },
+    }
+    return typing.cast(ops.pebble.LayerDict, layer)
+
+
 def check_moderation_ready() -> ops.pebble.CheckDict:
     """Return the Moderation service check.
 
@@ -607,14 +642,17 @@ def check_moderation_ready() -> ops.pebble.CheckDict:
     return check.to_dict()
 
 
-def restart_mas(container: ops.model.Container, rendered_mas_configuration: str) -> None:
+def restart_mas(
+    container: ops.model.Container, rendered_mas_configuration: str, charm_state: CharmState
+) -> None:
     """Update MAS configuration and restart MAS.
 
     Args:
         container: The synapse container.
         rendered_mas_configuration: YAML configuration for MAS.
+        charm_state: Instance of CharmState
     """
     _push_mas_config(container, rendered_mas_configuration, MAS_CONFIGURATION_PATH)
     validate_mas_config(container)
     sync_mas_config(container)
-    replan_mas(container)
+    replan_mas(container, charm_state)
diff --git a/src/state/mas.py b/src/state/mas.py
index b2f8f1ebe..b37d621e0 100644
--- a/src/state/mas.py
+++ b/src/state/mas.py
@@ -52,6 +52,7 @@ class MASContext(BaseModel):
         synapse_oidc_client_id: OIDC client ID used by synapse
         synapse_oidc_client_secret: OIDC client secret used by synapse
         upstream_oidc_provider_id: ULID to identify the upstream oidc provider
+        oidc_subject_claim: The configured OIDC subject claim
     """
 
     encryption_key: str = Field(min_length=64, max_length=64)
@@ -61,6 +62,7 @@ class MASContext(BaseModel):
     synapse_oidc_client_id: str = Field()
     synapse_oidc_client_secret: str = Field(min_length=32, max_length=32)
     upstream_oidc_provider_id: str = Field()
+    oidc_subject_claim: str = Field(min_length=1)
 
 
 class SigningKey(typing.NamedTuple):
@@ -147,8 +149,6 @@ def from_charm(cls, charm: ops.CharmBase) -> "MASConfiguration":
         datasource = charm._mas_database.get_relation_as_datasource()  # type: ignore
         validate_datasource(datasource)
 
-        logger.info("Datasource validated: %s", datasource)
-
         try:
             secret = charm.model.get_secret(label=MAS_CONTEXT_LABEL)
             mas_context_secret = secret.get_content()
@@ -183,6 +183,7 @@ def from_charm(cls, charm: ops.CharmBase) -> "MASConfiguration":
                 synapse_oidc_client_id=mas_context_secret["synapse-oidc-client-id"],
                 synapse_oidc_client_secret=mas_context_secret["synapse-oidc-client-secret"],
                 upstream_oidc_provider_id=mas_context_secret["upstream-oidc-provider-id"],
+                oidc_subject_claim=typing.cast(str, charm.config.get("oidc_subject_claim")),
             )
         except ValidationError as exc:
             logger.exception("Error validating MAS context.")
diff --git a/templates/mas_config.yaml.j2 b/templates/mas_config.yaml.j2
index 8e2632e0b..61025c21d 100644
--- a/templates/mas_config.yaml.j2
+++ b/templates/mas_config.yaml.j2
@@ -61,7 +61,7 @@ upstream_oauth2:
       claims_imports:
           subject:
               action: require
-              template: {{ '"{{ user.sub }}"' }}
+              template: {{ oidc_subject_claim }}
           displayname:
               action: suggest
               template: {{ '"{{ user.name }}"' }}


Reviews:
user: login: erinecon
body: Thanks for adding this document!
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-03T13:44:02Z
user: login: amandahla
state: COMMENTED
author_association: NONE
submitted_at: 2025-04-03T13:55:17Z
user: login: amandahla
state: COMMENTED
author_association: NONE
submitted_at: 2025-04-03T13:56:32Z
user: login: amandahla
state: COMMENTED
author_association: NONE
submitted_at: 2025-04-03T13:57:50Z
user: login: amandahla
state: COMMENTED
author_association: NONE
submitted_at: 2025-04-03T13:59:49Z
user: login: amandahla
state: COMMENTED
author_association: NONE
submitted_at: 2025-04-03T14:02:48Z
user: login: Thanhphan1147
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-03T16:01:31Z
user: login: Thanhphan1147
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-03T16:02:26Z
user: login: Thanhphan1147
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-03T16:03:19Z
user: login: Thanhphan1147
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-03T16:04:09Z
user: login: Thanhphan1147
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-03T16:12:39Z
user: login: Thanhphan1147
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-03T16:28:20Z
user: login: Thanhphan1147
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-03T16:32:31Z
user: login: Thanhphan1147
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-03T16:38:48Z
user: login: Thanhphan1147
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-03T21:34:58Z
user: login: Thanhphan1147
state: COMMENTED
author_association: COLLABORATOR
submitted_at: 2025-04-03T21:35:06Z
user: login: erinecon
body: The document is looking great! 
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-04T11:56:14Z
user: login: erinecon
state: COMMENTED
author_association: CONTRIBUTOR
submitted_at: 2025-04-04T14:40:18Z
user: login: erinecon
state: APPROVED
author_association: CONTRIBUTOR
submitted_at: 2025-04-04T14:40:23Z
user: login: amandahla
state: COMMENTED
author_association: NONE
submitted_at: 2025-04-04T17:00:53Z
user: login: amandahla
state: APPROVED
author_association: NONE
submitted_at: 2025-04-04T20:12:14Z

Review comments:
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
This document shows how to migrate a legacy Synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
```
created_at: 2025-04-03T13:19:25Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication via SAML.
```
created_at: 2025-04-03T13:19:58Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: Mention that deploying the new synapse charm with the name `server-mas`
created_at: 2025-04-03T13:21:10Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
### Integrate with `postgresql` charm
```
created_at: 2025-04-03T13:21:52Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
Integrate with the existing `postgresql` charm to set up the database for the new charm.
```
Also might be worth mentioning that you need both endpoints 
created_at: 2025-04-03T13:22:50Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: Add another sentence starting with `For example` that indicates this is not the only way and this is for integrating with Google
created_at: 2025-04-03T13:26:52Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
juju integrate server-mas oidc
```
created_at: 2025-04-03T13:26:59Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
The MAS redirect URL will be formatted like `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration`. 
```
created_at: 2025-04-03T13:31:14Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
## Back up the existing synapse charm and restore on the new synapse charm
```
created_at: 2025-04-03T13:31:25Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
+### Backup and restore using the s3-integrator charm
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
### Back up and restore using the s3-integrator charm
```
created_at: 2025-04-03T13:31:37Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
+### Backup and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Backup and Restore"](https://discourse.charmhub.io/t/synapse-docs-backup-and-restore/13212) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Back up and Restore"](https://charmhub.io/synapse/docs/how-to-backup-and-restore) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
```
created_at: 2025-04-03T13:33:30Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
+### Backup and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Backup and Restore"](https://discourse.charmhub.io/t/synapse-docs-backup-and-restore/13212) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
Then we integrate with the existing synapse charm and create the backup:
```
created_at: 2025-04-03T13:33:54Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
+### Backup and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Backup and Restore"](https://discourse.charmhub.io/t/synapse-docs-backup-and-restore/13212) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup
+```
+juju relate s3-integrator server
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
juju integrate s3-integrator server
```
created_at: 2025-04-03T13:34:08Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
+### Backup and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Backup and Restore"](https://discourse.charmhub.io/t/synapse-docs-backup-and-restore/13212) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup
+```
+juju relate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID, we will use it to restore the backup on the new synapse charm.
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
Take note of the backup ID; we will use it to restore the backup on the new synapse charm.
```
created_at: 2025-04-03T13:34:27Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
+### Backup and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Backup and Restore"](https://discourse.charmhub.io/t/synapse-docs-backup-and-restore/13212) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup
+```
+juju relate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID, we will use it to restore the backup on the new synapse charm.
+```
+juju relate s3-integrator server-mas
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
juju integrate s3-integrator server-mas
```
created_at: 2025-04-03T13:34:35Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
+### Backup and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Backup and Restore"](https://discourse.charmhub.io/t/synapse-docs-backup-and-restore/13212) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup
+```
+juju relate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID, we will use it to restore the backup on the new synapse charm.
+```
+juju relate s3-integrator server-mas
+juju run synapse/leader restore-backup backup-id=<backup-id>
+```
+
+## Synapse database migration
+### Stop all services on the new and the existing synapse charm
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
### Stop all services on the new and the existing synapse charms
```
created_at: 2025-04-03T13:35:02Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
+### Backup and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Backup and Restore"](https://discourse.charmhub.io/t/synapse-docs-backup-and-restore/13212) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup
+```
+juju relate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID, we will use it to restore the backup on the new synapse charm.
+```
+juju relate s3-integrator server-mas
+juju run synapse/leader restore-backup backup-id=<backup-id>
+```
+
+## Synapse database migration
+### Stop all services on the new and the existing synapse charm
+```
+juju ssh --container synapse server-mas/0 "pebble stop synapse; pebble stop synapse-mas; pebble stop stats-exporter"
+juju ssh --container synapse server/0 "pebble stop synapse; pebble stop stats-exporter"
+```
+
+### Connect to the database
+```
+juju ssh --container synapse server-mas/0 bash
+```
+
+The following commands assume that you are in the `synapse` container of the `server-mas` application.
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: Nitpick: Might be good as a note/warning admonition
created_at: 2025-04-03T13:35:52Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
+### Backup and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Backup and Restore"](https://discourse.charmhub.io/t/synapse-docs-backup-and-restore/13212) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup
+```
+juju relate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID, we will use it to restore the backup on the new synapse charm.
+```
+juju relate s3-integrator server-mas
+juju run synapse/leader restore-backup backup-id=<backup-id>
+```
+
+## Synapse database migration
+### Stop all services on the new and the existing synapse charm
+```
+juju ssh --container synapse server-mas/0 "pebble stop synapse; pebble stop synapse-mas; pebble stop stats-exporter"
+juju ssh --container synapse server/0 "pebble stop synapse; pebble stop stats-exporter"
+```
+
+### Connect to the database
+```
+juju ssh --container synapse server-mas/0 bash
+```
+
+The following commands assume that you are in the `synapse` container of the `server-mas` application.
+```
+apt update
+apt install wget postgresql-client -y
+wget https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64 -O /usr/bin/yq && chmod +x /usr/bin/yq
+```
+
+Copy the original synapse database
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
Copy the original synapse charm database:
```
created_at: 2025-04-03T13:36:36Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
+### Backup and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Backup and Restore"](https://discourse.charmhub.io/t/synapse-docs-backup-and-restore/13212) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup
+```
+juju relate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID, we will use it to restore the backup on the new synapse charm.
+```
+juju relate s3-integrator server-mas
+juju run synapse/leader restore-backup backup-id=<backup-id>
+```
+
+## Synapse database migration
+### Stop all services on the new and the existing synapse charm
+```
+juju ssh --container synapse server-mas/0 "pebble stop synapse; pebble stop synapse-mas; pebble stop stats-exporter"
+juju ssh --container synapse server/0 "pebble stop synapse; pebble stop stats-exporter"
+```
+
+### Connect to the database
+```
+juju ssh --container synapse server-mas/0 bash
+```
+
+The following commands assume that you are in the `synapse` container of the `server-mas` application.
+```
+apt update
+apt install wget postgresql-client -y
+wget https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64 -O /usr/bin/yq && chmod +x /usr/bin/yq
+```
+
+Copy the original synapse database
+```
+DB_HOST=$(yq e '.database.args.host' /data/homeserver.yaml)
+DB_PORT=$(yq e '.database.args.port' /data/homeserver.yaml)
+DB_PASSWORD=$(yq e '.database.args.password' /data/homeserver.yaml)
+DB_USER=$(yq e '.database.args.user' /data/homeserver.yaml)
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c 'drop database "server-mas";'
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c "create database \"server-mas\" with template server owner $DB_USER;"
+```
+
+In case where postgres gives you an error saying "", drop all connections from the database
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
In case where PostgreSQL gives you an error saying "", drop all connections from the database:
```
Also update the error message
created_at: 2025-04-03T13:37:59Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
+### Backup and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Backup and Restore"](https://discourse.charmhub.io/t/synapse-docs-backup-and-restore/13212) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup
+```
+juju relate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID, we will use it to restore the backup on the new synapse charm.
+```
+juju relate s3-integrator server-mas
+juju run synapse/leader restore-backup backup-id=<backup-id>
+```
+
+## Synapse database migration
+### Stop all services on the new and the existing synapse charm
+```
+juju ssh --container synapse server-mas/0 "pebble stop synapse; pebble stop synapse-mas; pebble stop stats-exporter"
+juju ssh --container synapse server/0 "pebble stop synapse; pebble stop stats-exporter"
+```
+
+### Connect to the database
+```
+juju ssh --container synapse server-mas/0 bash
+```
+
+The following commands assume that you are in the `synapse` container of the `server-mas` application.
+```
+apt update
+apt install wget postgresql-client -y
+wget https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64 -O /usr/bin/yq && chmod +x /usr/bin/yq
+```
+
+Copy the original synapse database
+```
+DB_HOST=$(yq e '.database.args.host' /data/homeserver.yaml)
+DB_PORT=$(yq e '.database.args.port' /data/homeserver.yaml)
+DB_PASSWORD=$(yq e '.database.args.password' /data/homeserver.yaml)
+DB_USER=$(yq e '.database.args.user' /data/homeserver.yaml)
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c 'drop database "server-mas";'
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c "create database \"server-mas\" with template server owner $DB_USER;"
+```
+
+In case where postgres gives you an error saying "", drop all connections from the database
+```
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c SELECT pg_terminate_backend(pg_stat_activity.pid) FROM pg_stat_activity WHERE pg_stat_activity.datname = "server" AND pid <> pg_backend_pid();
+```
+
+## Migrating users to MAS
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
## Migrate users to MAS
```
created_at: 2025-04-03T13:38:39Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
+### Backup and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Backup and Restore"](https://discourse.charmhub.io/t/synapse-docs-backup-and-restore/13212) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup
+```
+juju relate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID, we will use it to restore the backup on the new synapse charm.
+```
+juju relate s3-integrator server-mas
+juju run synapse/leader restore-backup backup-id=<backup-id>
+```
+
+## Synapse database migration
+### Stop all services on the new and the existing synapse charm
+```
+juju ssh --container synapse server-mas/0 "pebble stop synapse; pebble stop synapse-mas; pebble stop stats-exporter"
+juju ssh --container synapse server/0 "pebble stop synapse; pebble stop stats-exporter"
+```
+
+### Connect to the database
+```
+juju ssh --container synapse server-mas/0 bash
+```
+
+The following commands assume that you are in the `synapse` container of the `server-mas` application.
+```
+apt update
+apt install wget postgresql-client -y
+wget https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64 -O /usr/bin/yq && chmod +x /usr/bin/yq
+```
+
+Copy the original synapse database
+```
+DB_HOST=$(yq e '.database.args.host' /data/homeserver.yaml)
+DB_PORT=$(yq e '.database.args.port' /data/homeserver.yaml)
+DB_PASSWORD=$(yq e '.database.args.password' /data/homeserver.yaml)
+DB_USER=$(yq e '.database.args.user' /data/homeserver.yaml)
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c 'drop database "server-mas";'
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c "create database \"server-mas\" with template server owner $DB_USER;"
+```
+
+In case where postgres gives you an error saying "", drop all connections from the database
+```
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c SELECT pg_terminate_backend(pg_stat_activity.pid) FROM pg_stat_activity WHERE pg_stat_activity.datname = "server" AND pid <> pg_backend_pid();
+```
+
+## Migrating users to MAS
+### Perform user migration to MAS database
+Run the `advisir` command as well as the `migrate` command with the `--dryRun` flag to check that there are no errors.
+```
+npx --yes @vector-im/syn2mas \
+    --command advisor \
+    --synapseConfigFile /data/homeserver.yaml
+
+OAUTH2_PROVIDER_ID=$(yq e '.upstream_oauth2.providers[0].id' /mas/config.yaml)
+npx --yes @vector-im/syn2mas \
+    --command migrate \
+    --synapseConfigFile /data/homeserver.yaml \
+    --masConfigFile /mas/config.yaml \
+    --upstreamProviderMapping saml:$OAUTH2_PROVIDER_ID \
+    --dryRun
+```
+
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: Add some indication of what a "no error" message looks like for all the commands
created_at: 2025-04-03T13:39:40Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
+### Backup and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Backup and Restore"](https://discourse.charmhub.io/t/synapse-docs-backup-and-restore/13212) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup
+```
+juju relate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID, we will use it to restore the backup on the new synapse charm.
+```
+juju relate s3-integrator server-mas
+juju run synapse/leader restore-backup backup-id=<backup-id>
+```
+
+## Synapse database migration
+### Stop all services on the new and the existing synapse charm
+```
+juju ssh --container synapse server-mas/0 "pebble stop synapse; pebble stop synapse-mas; pebble stop stats-exporter"
+juju ssh --container synapse server/0 "pebble stop synapse; pebble stop stats-exporter"
+```
+
+### Connect to the database
+```
+juju ssh --container synapse server-mas/0 bash
+```
+
+The following commands assume that you are in the `synapse` container of the `server-mas` application.
+```
+apt update
+apt install wget postgresql-client -y
+wget https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64 -O /usr/bin/yq && chmod +x /usr/bin/yq
+```
+
+Copy the original synapse database
+```
+DB_HOST=$(yq e '.database.args.host' /data/homeserver.yaml)
+DB_PORT=$(yq e '.database.args.port' /data/homeserver.yaml)
+DB_PASSWORD=$(yq e '.database.args.password' /data/homeserver.yaml)
+DB_USER=$(yq e '.database.args.user' /data/homeserver.yaml)
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c 'drop database "server-mas";'
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c "create database \"server-mas\" with template server owner $DB_USER;"
+```
+
+In case where postgres gives you an error saying "", drop all connections from the database
+```
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c SELECT pg_terminate_backend(pg_stat_activity.pid) FROM pg_stat_activity WHERE pg_stat_activity.datname = "server" AND pid <> pg_backend_pid();
+```
+
+## Migrating users to MAS
+### Perform user migration to MAS database
+Run the `advisir` command as well as the `migrate` command with the `--dryRun` flag to check that there are no errors.
+```
+npx --yes @vector-im/syn2mas \
+    --command advisor \
+    --synapseConfigFile /data/homeserver.yaml
+
+OAUTH2_PROVIDER_ID=$(yq e '.upstream_oauth2.providers[0].id' /mas/config.yaml)
+npx --yes @vector-im/syn2mas \
+    --command migrate \
+    --synapseConfigFile /data/homeserver.yaml \
+    --masConfigFile /mas/config.yaml \
+    --upstreamProviderMapping saml:$OAUTH2_PROVIDER_ID \
+    --dryRun
+```
+
+Finally, run the migration command
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
Finally, run the migration command:
```
created_at: 2025-04-03T13:39:55Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
+### Backup and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Backup and Restore"](https://discourse.charmhub.io/t/synapse-docs-backup-and-restore/13212) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup
+```
+juju relate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID, we will use it to restore the backup on the new synapse charm.
+```
+juju relate s3-integrator server-mas
+juju run synapse/leader restore-backup backup-id=<backup-id>
+```
+
+## Synapse database migration
+### Stop all services on the new and the existing synapse charm
+```
+juju ssh --container synapse server-mas/0 "pebble stop synapse; pebble stop synapse-mas; pebble stop stats-exporter"
+juju ssh --container synapse server/0 "pebble stop synapse; pebble stop stats-exporter"
+```
+
+### Connect to the database
+```
+juju ssh --container synapse server-mas/0 bash
+```
+
+The following commands assume that you are in the `synapse` container of the `server-mas` application.
+```
+apt update
+apt install wget postgresql-client -y
+wget https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64 -O /usr/bin/yq && chmod +x /usr/bin/yq
+```
+
+Copy the original synapse database
+```
+DB_HOST=$(yq e '.database.args.host' /data/homeserver.yaml)
+DB_PORT=$(yq e '.database.args.port' /data/homeserver.yaml)
+DB_PASSWORD=$(yq e '.database.args.password' /data/homeserver.yaml)
+DB_USER=$(yq e '.database.args.user' /data/homeserver.yaml)
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c 'drop database "server-mas";'
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c "create database \"server-mas\" with template server owner $DB_USER;"
+```
+
+In case where postgres gives you an error saying "", drop all connections from the database
+```
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c SELECT pg_terminate_backend(pg_stat_activity.pid) FROM pg_stat_activity WHERE pg_stat_activity.datname = "server" AND pid <> pg_backend_pid();
+```
+
+## Migrating users to MAS
+### Perform user migration to MAS database
+Run the `advisir` command as well as the `migrate` command with the `--dryRun` flag to check that there are no errors.
+```
+npx --yes @vector-im/syn2mas \
+    --command advisor \
+    --synapseConfigFile /data/homeserver.yaml
+
+OAUTH2_PROVIDER_ID=$(yq e '.upstream_oauth2.providers[0].id' /mas/config.yaml)
+npx --yes @vector-im/syn2mas \
+    --command migrate \
+    --synapseConfigFile /data/homeserver.yaml \
+    --masConfigFile /mas/config.yaml \
+    --upstreamProviderMapping saml:$OAUTH2_PROVIDER_ID \
+    --dryRun
+```
+
+Finally, run the migration command
+```
+npx --yes @vector-im/syn2mas \
+    --command migrate \
+    --synapseConfigFile /data/homeserver.yaml \
+    --masConfigFile /mas/config.yaml \
+    --upstreamProviderMapping saml:$OAUTH2_PROVIDER_ID
+```
+
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: Also good to add an indication of what success looks like in the terminal
created_at: 2025-04-03T13:40:28Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
+### Backup and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Backup and Restore"](https://discourse.charmhub.io/t/synapse-docs-backup-and-restore/13212) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup
+```
+juju relate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID, we will use it to restore the backup on the new synapse charm.
+```
+juju relate s3-integrator server-mas
+juju run synapse/leader restore-backup backup-id=<backup-id>
+```
+
+## Synapse database migration
+### Stop all services on the new and the existing synapse charm
+```
+juju ssh --container synapse server-mas/0 "pebble stop synapse; pebble stop synapse-mas; pebble stop stats-exporter"
+juju ssh --container synapse server/0 "pebble stop synapse; pebble stop stats-exporter"
+```
+
+### Connect to the database
+```
+juju ssh --container synapse server-mas/0 bash
+```
+
+The following commands assume that you are in the `synapse` container of the `server-mas` application.
+```
+apt update
+apt install wget postgresql-client -y
+wget https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64 -O /usr/bin/yq && chmod +x /usr/bin/yq
+```
+
+Copy the original synapse database
+```
+DB_HOST=$(yq e '.database.args.host' /data/homeserver.yaml)
+DB_PORT=$(yq e '.database.args.port' /data/homeserver.yaml)
+DB_PASSWORD=$(yq e '.database.args.password' /data/homeserver.yaml)
+DB_USER=$(yq e '.database.args.user' /data/homeserver.yaml)
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c 'drop database "server-mas";'
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c "create database \"server-mas\" with template server owner $DB_USER;"
+```
+
+In case where postgres gives you an error saying "", drop all connections from the database
+```
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c SELECT pg_terminate_backend(pg_stat_activity.pid) FROM pg_stat_activity WHERE pg_stat_activity.datname = "server" AND pid <> pg_backend_pid();
+```
+
+## Migrating users to MAS
+### Perform user migration to MAS database
+Run the `advisir` command as well as the `migrate` command with the `--dryRun` flag to check that there are no errors.
+```
+npx --yes @vector-im/syn2mas \
+    --command advisor \
+    --synapseConfigFile /data/homeserver.yaml
+
+OAUTH2_PROVIDER_ID=$(yq e '.upstream_oauth2.providers[0].id' /mas/config.yaml)
+npx --yes @vector-im/syn2mas \
+    --command migrate \
+    --synapseConfigFile /data/homeserver.yaml \
+    --masConfigFile /mas/config.yaml \
+    --upstreamProviderMapping saml:$OAUTH2_PROVIDER_ID \
+    --dryRun
+```
+
+Finally, run the migration command
+```
+npx --yes @vector-im/syn2mas \
+    --command migrate \
+    --synapseConfigFile /data/homeserver.yaml \
+    --masConfigFile /mas/config.yaml \
+    --upstreamProviderMapping saml:$OAUTH2_PROVIDER_ID
+```
+
+### Configure the OIDC subject claim
+After the migration, the `external_id` of the synapse user is used as the OIDC subject in MAS. Most of the time this needs to be changed so that the local account gets recognized by MAS when authenticating with the upstream provider. 
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
After the migration, the `external_id` of the Synapse user is used as the OIDC subject in MAS. Most of the time, this needs to be changed so that the local account gets recognized by MAS when authenticating with the upstream provider. 
```
Add another sentence explaining what the `psql` command is doing (logging into the database)
created_at: 2025-04-03T13:42:02Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
+### Backup and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Backup and Restore"](https://discourse.charmhub.io/t/synapse-docs-backup-and-restore/13212) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup
+```
+juju relate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID, we will use it to restore the backup on the new synapse charm.
+```
+juju relate s3-integrator server-mas
+juju run synapse/leader restore-backup backup-id=<backup-id>
+```
+
+## Synapse database migration
+### Stop all services on the new and the existing synapse charm
+```
+juju ssh --container synapse server-mas/0 "pebble stop synapse; pebble stop synapse-mas; pebble stop stats-exporter"
+juju ssh --container synapse server/0 "pebble stop synapse; pebble stop stats-exporter"
+```
+
+### Connect to the database
+```
+juju ssh --container synapse server-mas/0 bash
+```
+
+The following commands assume that you are in the `synapse` container of the `server-mas` application.
+```
+apt update
+apt install wget postgresql-client -y
+wget https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64 -O /usr/bin/yq && chmod +x /usr/bin/yq
+```
+
+Copy the original synapse database
+```
+DB_HOST=$(yq e '.database.args.host' /data/homeserver.yaml)
+DB_PORT=$(yq e '.database.args.port' /data/homeserver.yaml)
+DB_PASSWORD=$(yq e '.database.args.password' /data/homeserver.yaml)
+DB_USER=$(yq e '.database.args.user' /data/homeserver.yaml)
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c 'drop database "server-mas";'
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c "create database \"server-mas\" with template server owner $DB_USER;"
+```
+
+In case where postgres gives you an error saying "", drop all connections from the database
+```
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c SELECT pg_terminate_backend(pg_stat_activity.pid) FROM pg_stat_activity WHERE pg_stat_activity.datname = "server" AND pid <> pg_backend_pid();
+```
+
+## Migrating users to MAS
+### Perform user migration to MAS database
+Run the `advisir` command as well as the `migrate` command with the `--dryRun` flag to check that there are no errors.
+```
+npx --yes @vector-im/syn2mas \
+    --command advisor \
+    --synapseConfigFile /data/homeserver.yaml
+
+OAUTH2_PROVIDER_ID=$(yq e '.upstream_oauth2.providers[0].id' /mas/config.yaml)
+npx --yes @vector-im/syn2mas \
+    --command migrate \
+    --synapseConfigFile /data/homeserver.yaml \
+    --masConfigFile /mas/config.yaml \
+    --upstreamProviderMapping saml:$OAUTH2_PROVIDER_ID \
+    --dryRun
+```
+
+Finally, run the migration command
+```
+npx --yes @vector-im/syn2mas \
+    --command migrate \
+    --synapseConfigFile /data/homeserver.yaml \
+    --masConfigFile /mas/config.yaml \
+    --upstreamProviderMapping saml:$OAUTH2_PROVIDER_ID
+```
+
+### Configure the OIDC subject claim
+After the migration, the `external_id` of the synapse user is used as the OIDC subject in MAS. Most of the time this needs to be changed so that the local account gets recognized by MAS when authenticating with the upstream provider. 
+
+```
+psql $(yq e '.database.uri' /mas/config.yaml)
+```
+
+Then run the appropriate SQL command to update the subject field. For example, to use the email address as the OIDC subject, we run this SQL query:
+```
+update upstream_oauth_links
+SET subject=(select email from user_emails where upstream_oauth_links.user_id=user_emails.user_id);
+
+\q
+```
+
+After updating the OIDC subject in the MAS database, we need to also configure the OIDC subject claim:
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
After updating the OIDC subject in the MAS database, we need to also configure the OIDC subject claim outside of the PostgreSQL container:
```
created_at: 2025-04-03T13:43:07Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
path: docs/how-to/migrate-to-mas.md
user: login: amandahla
body: latest/edge -> 1/edge
created_at: 2025-04-03T13:55:17Z
author_association: NONE
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
path: docs/how-to/migrate-to-mas.md
user: login: amandahla
body: Some note about external access needed?
created_at: 2025-04-03T13:56:32Z
author_association: NONE
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
+### Backup and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Backup and Restore"](https://discourse.charmhub.io/t/synapse-docs-backup-and-restore/13212) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup
+```
+juju relate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID, we will use it to restore the backup on the new synapse charm.
+```
+juju relate s3-integrator server-mas
+juju run synapse/leader restore-backup backup-id=<backup-id>
+```
+
+## Synapse database migration
+### Stop all services on the new and the existing synapse charm
+```
+juju ssh --container synapse server-mas/0 "pebble stop synapse; pebble stop synapse-mas; pebble stop stats-exporter"
+juju ssh --container synapse server/0 "pebble stop synapse; pebble stop stats-exporter"
+```
+
+### Connect to the database
+```
+juju ssh --container synapse server-mas/0 bash
+```
+
+The following commands assume that you are in the `synapse` container of the `server-mas` application.
+```
+apt update
+apt install wget postgresql-client -y
+wget https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64 -O /usr/bin/yq && chmod +x /usr/bin/yq
+```
+
+Copy the original synapse database
+```
+DB_HOST=$(yq e '.database.args.host' /data/homeserver.yaml)
+DB_PORT=$(yq e '.database.args.port' /data/homeserver.yaml)
+DB_PASSWORD=$(yq e '.database.args.password' /data/homeserver.yaml)
+DB_USER=$(yq e '.database.args.user' /data/homeserver.yaml)
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c 'drop database "server-mas";'
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c "create database \"server-mas\" with template server owner $DB_USER;"
+```
+
+In case where postgres gives you an error saying "", drop all connections from the database
+```
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c SELECT pg_terminate_backend(pg_stat_activity.pid) FROM pg_stat_activity WHERE pg_stat_activity.datname = "server" AND pid <> pg_backend_pid();
+```
+
+## Migrating users to MAS
+### Perform user migration to MAS database
path: docs/how-to/migrate-to-mas.md
user: login: amandahla
body: a note about proxy?
created_at: 2025-04-03T13:57:49Z
author_association: NONE
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
+### Backup and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Backup and Restore"](https://discourse.charmhub.io/t/synapse-docs-backup-and-restore/13212) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup
+```
+juju relate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID, we will use it to restore the backup on the new synapse charm.
+```
+juju relate s3-integrator server-mas
+juju run synapse/leader restore-backup backup-id=<backup-id>
+```
+
+## Synapse database migration
+### Stop all services on the new and the existing synapse charm
+```
+juju ssh --container synapse server-mas/0 "pebble stop synapse; pebble stop synapse-mas; pebble stop stats-exporter"
+juju ssh --container synapse server/0 "pebble stop synapse; pebble stop stats-exporter"
+```
+
+### Connect to the database
+```
+juju ssh --container synapse server-mas/0 bash
+```
+
+The following commands assume that you are in the `synapse` container of the `server-mas` application.
+```
+apt update
+apt install wget postgresql-client -y
+wget https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64 -O /usr/bin/yq && chmod +x /usr/bin/yq
+```
+
+Copy the original synapse database
+```
+DB_HOST=$(yq e '.database.args.host' /data/homeserver.yaml)
+DB_PORT=$(yq e '.database.args.port' /data/homeserver.yaml)
+DB_PASSWORD=$(yq e '.database.args.password' /data/homeserver.yaml)
+DB_USER=$(yq e '.database.args.user' /data/homeserver.yaml)
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c 'drop database "server-mas";'
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c "create database \"server-mas\" with template server owner $DB_USER;"
path: docs/how-to/migrate-to-mas.md
user: login: amandahla
body: Was the idea here to restore the current database to the new one? This seems that is just creating.
created_at: 2025-04-03T13:59:49Z
author_association: NONE
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
path: docs/how-to/migrate-to-mas.md
user: login: amandahla
body: What about adding a warning to create a backup and mentioning that this procedure is irreversible? Also, the current instance should be stopped during the process.
created_at: 2025-04-03T14:02:48Z
author_association: NONE
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
+### Backup and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Backup and Restore"](https://discourse.charmhub.io/t/synapse-docs-backup-and-restore/13212) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup
+```
+juju relate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID, we will use it to restore the backup on the new synapse charm.
+```
+juju relate s3-integrator server-mas
+juju run synapse/leader restore-backup backup-id=<backup-id>
+```
+
+## Synapse database migration
+### Stop all services on the new and the existing synapse charm
+```
+juju ssh --container synapse server-mas/0 "pebble stop synapse; pebble stop synapse-mas; pebble stop stats-exporter"
+juju ssh --container synapse server/0 "pebble stop synapse; pebble stop stats-exporter"
+```
+
+### Connect to the database
+```
+juju ssh --container synapse server-mas/0 bash
+```
+
+The following commands assume that you are in the `synapse` container of the `server-mas` application.
+```
+apt update
+apt install wget postgresql-client -y
+wget https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64 -O /usr/bin/yq && chmod +x /usr/bin/yq
+```
+
+Copy the original synapse database
+```
+DB_HOST=$(yq e '.database.args.host' /data/homeserver.yaml)
+DB_PORT=$(yq e '.database.args.port' /data/homeserver.yaml)
+DB_PASSWORD=$(yq e '.database.args.password' /data/homeserver.yaml)
+DB_USER=$(yq e '.database.args.user' /data/homeserver.yaml)
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c 'drop database "server-mas";'
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c "create database \"server-mas\" with template server owner $DB_USER;"
path: docs/how-to/migrate-to-mas.md
user: login: Thanhphan1147
body: The `with template server` will actually make a copy of the current database iiuc.

created_at: 2025-04-03T16:01:30Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
path: docs/how-to/migrate-to-mas.md
user: login: Thanhphan1147
body: Hmm, I'm not sure that this process is irreversible as we don't touch the existing database, we can always remove the new charm and start over again.
created_at: 2025-04-03T16:02:26Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
+### Backup and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Backup and Restore"](https://discourse.charmhub.io/t/synapse-docs-backup-and-restore/13212) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup
+```
+juju relate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID, we will use it to restore the backup on the new synapse charm.
+```
+juju relate s3-integrator server-mas
+juju run synapse/leader restore-backup backup-id=<backup-id>
+```
+
+## Synapse database migration
+### Stop all services on the new and the existing synapse charm
+```
+juju ssh --container synapse server-mas/0 "pebble stop synapse; pebble stop synapse-mas; pebble stop stats-exporter"
+juju ssh --container synapse server/0 "pebble stop synapse; pebble stop stats-exporter"
+```
+
+### Connect to the database
+```
+juju ssh --container synapse server-mas/0 bash
+```
+
+The following commands assume that you are in the `synapse` container of the `server-mas` application.
+```
+apt update
+apt install wget postgresql-client -y
+wget https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64 -O /usr/bin/yq && chmod +x /usr/bin/yq
+```
+
+Copy the original synapse database
+```
+DB_HOST=$(yq e '.database.args.host' /data/homeserver.yaml)
+DB_PORT=$(yq e '.database.args.port' /data/homeserver.yaml)
+DB_PASSWORD=$(yq e '.database.args.password' /data/homeserver.yaml)
+DB_USER=$(yq e '.database.args.user' /data/homeserver.yaml)
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c 'drop database "server-mas";'
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c "create database \"server-mas\" with template server owner $DB_USER;"
+```
+
+In case where postgres gives you an error saying "", drop all connections from the database
+```
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c SELECT pg_terminate_backend(pg_stat_activity.pid) FROM pg_stat_activity WHERE pg_stat_activity.datname = "server" AND pid <> pg_backend_pid();
+```
+
+## Migrating users to MAS
+### Perform user migration to MAS database
path: docs/how-to/migrate-to-mas.md
user: login: Thanhphan1147
body: I thought about it but I don't think that it should be put here since it's quite specific to the environment, what do you think?

created_at: 2025-04-03T16:03:19Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
path: docs/how-to/migrate-to-mas.md
user: login: Thanhphan1147
body: We added the proxy config to the MAS's pebble layer so I don't think we need to do anything manually anymore

created_at: 2025-04-03T16:04:09Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
path: docs/how-to/migrate-to-mas.md
user: login: Thanhphan1147
body: thanks, updated!
created_at: 2025-04-03T16:12:39Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
+### Backup and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Backup and Restore"](https://discourse.charmhub.io/t/synapse-docs-backup-and-restore/13212) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup
+```
+juju relate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID, we will use it to restore the backup on the new synapse charm.
+```
+juju relate s3-integrator server-mas
+juju run synapse/leader restore-backup backup-id=<backup-id>
+```
+
+## Synapse database migration
+### Stop all services on the new and the existing synapse charm
+```
+juju ssh --container synapse server-mas/0 "pebble stop synapse; pebble stop synapse-mas; pebble stop stats-exporter"
+juju ssh --container synapse server/0 "pebble stop synapse; pebble stop stats-exporter"
+```
+
+### Connect to the database
+```
+juju ssh --container synapse server-mas/0 bash
+```
+
+The following commands assume that you are in the `synapse` container of the `server-mas` application.
+```
+apt update
+apt install wget postgresql-client -y
+wget https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64 -O /usr/bin/yq && chmod +x /usr/bin/yq
+```
+
+Copy the original synapse database
+```
+DB_HOST=$(yq e '.database.args.host' /data/homeserver.yaml)
+DB_PORT=$(yq e '.database.args.port' /data/homeserver.yaml)
+DB_PASSWORD=$(yq e '.database.args.password' /data/homeserver.yaml)
+DB_USER=$(yq e '.database.args.user' /data/homeserver.yaml)
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c 'drop database "server-mas";'
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c "create database \"server-mas\" with template server owner $DB_USER;"
+```
+
+In case where postgres gives you an error saying "", drop all connections from the database
+```
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c SELECT pg_terminate_backend(pg_stat_activity.pid) FROM pg_stat_activity WHERE pg_stat_activity.datname = "server" AND pid <> pg_backend_pid();
+```
+
+## Migrating users to MAS
+### Perform user migration to MAS database
+Run the `advisir` command as well as the `migrate` command with the `--dryRun` flag to check that there are no errors.
+```
+npx --yes @vector-im/syn2mas \
+    --command advisor \
+    --synapseConfigFile /data/homeserver.yaml
+
+OAUTH2_PROVIDER_ID=$(yq e '.upstream_oauth2.providers[0].id' /mas/config.yaml)
+npx --yes @vector-im/syn2mas \
+    --command migrate \
+    --synapseConfigFile /data/homeserver.yaml \
+    --masConfigFile /mas/config.yaml \
+    --upstreamProviderMapping saml:$OAUTH2_PROVIDER_ID \
+    --dryRun
+```
+
+Finally, run the migration command
+```
+npx --yes @vector-im/syn2mas \
+    --command migrate \
+    --synapseConfigFile /data/homeserver.yaml \
+    --masConfigFile /mas/config.yaml \
+    --upstreamProviderMapping saml:$OAUTH2_PROVIDER_ID
+```
+
+### Configure the OIDC subject claim
+After the migration, the `external_id` of the synapse user is used as the OIDC subject in MAS. Most of the time this needs to be changed so that the local account gets recognized by MAS when authenticating with the upstream provider. 
+
+```
+psql $(yq e '.database.uri' /mas/config.yaml)
+```
+
+Then run the appropriate SQL command to update the subject field. For example, to use the email address as the OIDC subject, we run this SQL query:
+```
+update upstream_oauth_links
+SET subject=(select email from user_emails where upstream_oauth_links.user_id=user_emails.user_id);
+
+\q
+```
+
+After updating the OIDC subject in the MAS database, we need to also configure the OIDC subject claim:
path: docs/how-to/migrate-to-mas.md
user: login: Thanhphan1147
body: updated, thanks
created_at: 2025-04-03T16:28:20Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
path: docs/how-to/migrate-to-mas.md
user: login: Thanhphan1147
body: updated!
created_at: 2025-04-03T16:32:31Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
path: docs/how-to/migrate-to-mas.md
user: login: Thanhphan1147
body: updated!
created_at: 2025-04-03T16:38:48Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
+### Backup and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Backup and Restore"](https://discourse.charmhub.io/t/synapse-docs-backup-and-restore/13212) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup
+```
+juju relate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID, we will use it to restore the backup on the new synapse charm.
+```
+juju relate s3-integrator server-mas
+juju run synapse/leader restore-backup backup-id=<backup-id>
+```
+
+## Synapse database migration
+### Stop all services on the new and the existing synapse charm
+```
+juju ssh --container synapse server-mas/0 "pebble stop synapse; pebble stop synapse-mas; pebble stop stats-exporter"
+juju ssh --container synapse server/0 "pebble stop synapse; pebble stop stats-exporter"
+```
+
+### Connect to the database
+```
+juju ssh --container synapse server-mas/0 bash
+```
+
+The following commands assume that you are in the `synapse` container of the `server-mas` application.
+```
+apt update
+apt install wget postgresql-client -y
+wget https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64 -O /usr/bin/yq && chmod +x /usr/bin/yq
+```
+
+Copy the original synapse database
+```
+DB_HOST=$(yq e '.database.args.host' /data/homeserver.yaml)
+DB_PORT=$(yq e '.database.args.port' /data/homeserver.yaml)
+DB_PASSWORD=$(yq e '.database.args.password' /data/homeserver.yaml)
+DB_USER=$(yq e '.database.args.user' /data/homeserver.yaml)
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c 'drop database "server-mas";'
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c "create database \"server-mas\" with template server owner $DB_USER;"
+```
+
+In case where postgres gives you an error saying "", drop all connections from the database
+```
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c SELECT pg_terminate_backend(pg_stat_activity.pid) FROM pg_stat_activity WHERE pg_stat_activity.datname = "server" AND pid <> pg_backend_pid();
+```
+
+## Migrating users to MAS
+### Perform user migration to MAS database
+Run the `advisir` command as well as the `migrate` command with the `--dryRun` flag to check that there are no errors.
+```
+npx --yes @vector-im/syn2mas \
+    --command advisor \
+    --synapseConfigFile /data/homeserver.yaml
+
+OAUTH2_PROVIDER_ID=$(yq e '.upstream_oauth2.providers[0].id' /mas/config.yaml)
+npx --yes @vector-im/syn2mas \
+    --command migrate \
+    --synapseConfigFile /data/homeserver.yaml \
+    --masConfigFile /mas/config.yaml \
+    --upstreamProviderMapping saml:$OAUTH2_PROVIDER_ID \
+    --dryRun
+```
+
+Finally, run the migration command
+```
+npx --yes @vector-im/syn2mas \
+    --command migrate \
+    --synapseConfigFile /data/homeserver.yaml \
+    --masConfigFile /mas/config.yaml \
+    --upstreamProviderMapping saml:$OAUTH2_PROVIDER_ID
+```
+
path: docs/how-to/migrate-to-mas.md
user: login: Thanhphan1147
body: added, thanks!
created_at: 2025-04-03T21:34:58Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
+### Backup and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Backup and Restore"](https://discourse.charmhub.io/t/synapse-docs-backup-and-restore/13212) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup
+```
+juju relate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID, we will use it to restore the backup on the new synapse charm.
+```
+juju relate s3-integrator server-mas
+juju run synapse/leader restore-backup backup-id=<backup-id>
+```
+
+## Synapse database migration
+### Stop all services on the new and the existing synapse charm
+```
+juju ssh --container synapse server-mas/0 "pebble stop synapse; pebble stop synapse-mas; pebble stop stats-exporter"
+juju ssh --container synapse server/0 "pebble stop synapse; pebble stop stats-exporter"
+```
+
+### Connect to the database
+```
+juju ssh --container synapse server-mas/0 bash
+```
+
+The following commands assume that you are in the `synapse` container of the `server-mas` application.
+```
+apt update
+apt install wget postgresql-client -y
+wget https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64 -O /usr/bin/yq && chmod +x /usr/bin/yq
+```
+
+Copy the original synapse database
+```
+DB_HOST=$(yq e '.database.args.host' /data/homeserver.yaml)
+DB_PORT=$(yq e '.database.args.port' /data/homeserver.yaml)
+DB_PASSWORD=$(yq e '.database.args.password' /data/homeserver.yaml)
+DB_USER=$(yq e '.database.args.user' /data/homeserver.yaml)
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c 'drop database "server-mas";'
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c "create database \"server-mas\" with template server owner $DB_USER;"
+```
+
+In case where postgres gives you an error saying "", drop all connections from the database
+```
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c SELECT pg_terminate_backend(pg_stat_activity.pid) FROM pg_stat_activity WHERE pg_stat_activity.datname = "server" AND pid <> pg_backend_pid();
+```
+
+## Migrating users to MAS
+### Perform user migration to MAS database
+Run the `advisir` command as well as the `migrate` command with the `--dryRun` flag to check that there are no errors.
+```
+npx --yes @vector-im/syn2mas \
+    --command advisor \
+    --synapseConfigFile /data/homeserver.yaml
+
+OAUTH2_PROVIDER_ID=$(yq e '.upstream_oauth2.providers[0].id' /mas/config.yaml)
+npx --yes @vector-im/syn2mas \
+    --command migrate \
+    --synapseConfigFile /data/homeserver.yaml \
+    --masConfigFile /mas/config.yaml \
+    --upstreamProviderMapping saml:$OAUTH2_PROVIDER_ID \
+    --dryRun
+```
+
path: docs/how-to/migrate-to-mas.md
user: login: Thanhphan1147
body: added, thanks!
created_at: 2025-04-03T21:35:05Z
author_association: COLLABORATOR
diff_hunk: @@ -0,0 +1,156 @@
+# How to migrate Synapse to the `2/edge` track
+This document shows how to migrate a legacy synapse homeserver (`1/edge` track) to an oidc-native homeserver (`2/edge` track).
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
This document shows how to migrate a legacy Synapse homeserver (`1/edge` track) to an oidc-native homeserver (`2/edge` track).
```
created_at: 2025-04-04T11:46:36Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,156 @@
+# How to migrate Synapse to the `2/edge` track
+This document shows how to migrate a legacy synapse homeserver (`1/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `1/edge` track that us using the `saml-integrator` charm to provide authentication via SAML.
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
This document will cover the migration path for a synapse charm on the `1/edge` track that uses the `saml-integrator` charm to provide authentication via SAML.
```
created_at: 2025-04-04T11:46:58Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,156 @@
+# How to migrate Synapse to the `2/edge` track
+This document shows how to migrate a legacy synapse homeserver (`1/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `1/edge` track that us using the `saml-integrator` charm to provide authentication via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will deploy the new synapse charm with the name `server-mas`. We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with the `postgresql-k8s` charm
+Integrate with the existing `postgresql-k8s` charm to set up the database for the new charm. Note that you need to integrate with the `postgresql-k8s` charm via both the `database` and the `mas-database` endpoint
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
Integrate with the existing `postgresql-k8s` charm to set up the database for the new charm. Note that you need to integrate with the `postgresql-k8s` charm via both the `database` and the `mas-database` endpoints.
```
created_at: 2025-04-04T11:49:24Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,156 @@
+# How to migrate Synapse to the `2/edge` track
+This document shows how to migrate a legacy synapse homeserver (`1/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `1/edge` track that us using the `saml-integrator` charm to provide authentication via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will deploy the new synapse charm with the name `server-mas`. We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with the `postgresql-k8s` charm
+Integrate with the existing `postgresql-k8s` charm to set up the database for the new charm. Note that you need to integrate with the `postgresql-k8s` charm via both the `database` and the `mas-database` endpoint
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers. For example, to use the Google IdP, we will deploy the `oauth-external-idp-integrator` charm.
+
+Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration`
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration`.
```
created_at: 2025-04-04T11:49:53Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,156 @@
+# How to migrate Synapse to the `2/edge` track
+This document shows how to migrate a legacy synapse homeserver (`1/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `1/edge` track that us using the `saml-integrator` charm to provide authentication via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will deploy the new synapse charm with the name `server-mas`. We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with the `postgresql-k8s` charm
+Integrate with the existing `postgresql-k8s` charm to set up the database for the new charm. Note that you need to integrate with the `postgresql-k8s` charm via both the `database` and the `mas-database` endpoint
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers. For example, to use the Google IdP, we will deploy the `oauth-external-idp-integrator` charm.
+
+Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration`
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju integrate server-mas oidc
+```
+
+Finally, we need to whitelist the MAS redirect URL on the OIDC client. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: Is there another (more inclusive) word we can use instead of whitelist? Here's a suggestion, let me know if it still has the same meaning.
```suggestion
Finally, we need to allow the MAS redirect URL on the OIDC client. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
```
created_at: 2025-04-04T11:51:25Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,156 @@
+# How to migrate Synapse to the `2/edge` track
+This document shows how to migrate a legacy synapse homeserver (`1/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `1/edge` track that us using the `saml-integrator` charm to provide authentication via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will deploy the new synapse charm with the name `server-mas`. We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with the `postgresql-k8s` charm
+Integrate with the existing `postgresql-k8s` charm to set up the database for the new charm. Note that you need to integrate with the `postgresql-k8s` charm via both the `database` and the `mas-database` endpoint
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers. For example, to use the Google IdP, we will deploy the `oauth-external-idp-integrator` charm.
+
+Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration`
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju integrate server-mas oidc
+```
+
+Finally, we need to whitelist the MAS redirect URL on the OIDC client. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be formatted like `<public_baseurl>/auth/upstream/callback/<provider_id>`. We can now go back to the OIDC client configuration on the IdP and whitelist the redirect URL. 
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: Same comment here about "whitelist". Another suggestion, let me know if any meaning is lost.
```suggestion
The MAS redirect URL will be formatted like `<public_baseurl>/auth/upstream/callback/<provider_id>`. We can now go back to the OIDC client configuration on the IdP and add the redirect URL to the allowlist. 
```
created_at: 2025-04-04T11:52:06Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,156 @@
+# How to migrate Synapse to the `2/edge` track
+This document shows how to migrate a legacy synapse homeserver (`1/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `1/edge` track that us using the `saml-integrator` charm to provide authentication via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will deploy the new synapse charm with the name `server-mas`. We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with the `postgresql-k8s` charm
+Integrate with the existing `postgresql-k8s` charm to set up the database for the new charm. Note that you need to integrate with the `postgresql-k8s` charm via both the `database` and the `mas-database` endpoint
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers. For example, to use the Google IdP, we will deploy the `oauth-external-idp-integrator` charm.
+
+Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration`
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju integrate server-mas oidc
+```
+
+Finally, we need to whitelist the MAS redirect URL on the OIDC client. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be formatted like `<public_baseurl>/auth/upstream/callback/<provider_id>`. We can now go back to the OIDC client configuration on the IdP and whitelist the redirect URL. 
+
+## Back up the existing synapse charm and restore on the new synapse charm
+### Back up and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Back up and Restore"](https://charmhub.io/synapse/docs/how-to-backup-and-restore) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Back up and Restore"](https://charmhub.io/synapse/docs/how-to-backup-and-restore) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target S3 bucket:
```
created_at: 2025-04-04T11:52:33Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,156 @@
+# How to migrate Synapse to the `2/edge` track
+This document shows how to migrate a legacy synapse homeserver (`1/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `1/edge` track that us using the `saml-integrator` charm to provide authentication via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will deploy the new synapse charm with the name `server-mas`. We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with the `postgresql-k8s` charm
+Integrate with the existing `postgresql-k8s` charm to set up the database for the new charm. Note that you need to integrate with the `postgresql-k8s` charm via both the `database` and the `mas-database` endpoint
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers. For example, to use the Google IdP, we will deploy the `oauth-external-idp-integrator` charm.
+
+Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration`
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju integrate server-mas oidc
+```
+
+Finally, we need to whitelist the MAS redirect URL on the OIDC client. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be formatted like `<public_baseurl>/auth/upstream/callback/<provider_id>`. We can now go back to the OIDC client configuration on the IdP and whitelist the redirect URL. 
+
+## Back up the existing synapse charm and restore on the new synapse charm
+### Back up and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Back up and Restore"](https://charmhub.io/synapse/docs/how-to-backup-and-restore) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup:
+```
+juju integrate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID; we will use it to restore the backup on the new synapse charm.
+```
+juju integrate s3-integrator server-mas
+juju run synapse/leader restore-backup backup-id=<backup-id>
+```
+
+## Synapse database migration
+### Stop all services on the new and the existing synapse charms
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: Nitpick: I think this could be demoted to text like in the following suggestion:
```suggestion
Stop all services on the new and the existing synapse charms:
```
created_at: 2025-04-04T11:53:34Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,156 @@
+# How to migrate Synapse to the `2/edge` track
+This document shows how to migrate a legacy synapse homeserver (`1/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `1/edge` track that us using the `saml-integrator` charm to provide authentication via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will deploy the new synapse charm with the name `server-mas`. We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with the `postgresql-k8s` charm
+Integrate with the existing `postgresql-k8s` charm to set up the database for the new charm. Note that you need to integrate with the `postgresql-k8s` charm via both the `database` and the `mas-database` endpoint
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers. For example, to use the Google IdP, we will deploy the `oauth-external-idp-integrator` charm.
+
+Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration`
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju integrate server-mas oidc
+```
+
+Finally, we need to whitelist the MAS redirect URL on the OIDC client. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be formatted like `<public_baseurl>/auth/upstream/callback/<provider_id>`. We can now go back to the OIDC client configuration on the IdP and whitelist the redirect URL. 
+
+## Back up the existing synapse charm and restore on the new synapse charm
+### Back up and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Back up and Restore"](https://charmhub.io/synapse/docs/how-to-backup-and-restore) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup:
+```
+juju integrate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID; we will use it to restore the backup on the new synapse charm.
+```
+juju integrate s3-integrator server-mas
+juju run synapse/leader restore-backup backup-id=<backup-id>
+```
+
+## Synapse database migration
+### Stop all services on the new and the existing synapse charms
+```
+juju ssh --container synapse server-mas/0 "pebble stop synapse; pebble stop synapse-mas; pebble stop stats-exporter"
+juju ssh --container synapse server/0 "pebble stop synapse; pebble stop stats-exporter"
+```
+
+### Connect to the database
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: Nitpick: I also think this header could be demoted to text.
```suggestion
Connect the new synapse charm to the database:
```
created_at: 2025-04-04T11:54:24Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,156 @@
+# How to migrate Synapse to the `2/edge` track
+This document shows how to migrate a legacy synapse homeserver (`1/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `1/edge` track that us using the `saml-integrator` charm to provide authentication via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will deploy the new synapse charm with the name `server-mas`. We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with the `postgresql-k8s` charm
+Integrate with the existing `postgresql-k8s` charm to set up the database for the new charm. Note that you need to integrate with the `postgresql-k8s` charm via both the `database` and the `mas-database` endpoint
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers. For example, to use the Google IdP, we will deploy the `oauth-external-idp-integrator` charm.
+
+Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration`
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju integrate server-mas oidc
+```
+
+Finally, we need to whitelist the MAS redirect URL on the OIDC client. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be formatted like `<public_baseurl>/auth/upstream/callback/<provider_id>`. We can now go back to the OIDC client configuration on the IdP and whitelist the redirect URL. 
+
+## Back up the existing synapse charm and restore on the new synapse charm
+### Back up and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Back up and Restore"](https://charmhub.io/synapse/docs/how-to-backup-and-restore) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup:
+```
+juju integrate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID; we will use it to restore the backup on the new synapse charm.
+```
+juju integrate s3-integrator server-mas
+juju run synapse/leader restore-backup backup-id=<backup-id>
+```
+
+## Synapse database migration
+### Stop all services on the new and the existing synapse charms
+```
+juju ssh --container synapse server-mas/0 "pebble stop synapse; pebble stop synapse-mas; pebble stop stats-exporter"
+juju ssh --container synapse server/0 "pebble stop synapse; pebble stop stats-exporter"
+```
+
+### Connect to the database
+```
+juju ssh --container synapse server-mas/0 bash
+```
+
+The following commands assume that you are in the `synapse` container of the `server-mas` application.
+```
+apt update
+apt install wget postgresql-client -y
+wget https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64 -O /usr/bin/yq && chmod +x /usr/bin/yq
+```
+
+Copy the original synapse database
+```
+DB_HOST=$(yq e '.database.args.host' /data/homeserver.yaml)
+DB_PORT=$(yq e '.database.args.port' /data/homeserver.yaml)
+DB_PASSWORD=$(yq e '.database.args.password' /data/homeserver.yaml)
+DB_USER=$(yq e '.database.args.user' /data/homeserver.yaml)
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c 'drop database "server-mas";'
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c "create database \"server-mas\" with template server owner $DB_USER;"
+```
+
+In case where postgres gives you an error saying "ERROR:  source database "synapse" is being accessed by other users", drop all connections from the database:
+
+First login to the database
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
First log in to the database:
```
created_at: 2025-04-04T11:54:59Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,156 @@
+# How to migrate Synapse to the `2/edge` track
+This document shows how to migrate a legacy synapse homeserver (`1/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `1/edge` track that us using the `saml-integrator` charm to provide authentication via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will deploy the new synapse charm with the name `server-mas`. We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with the `postgresql-k8s` charm
+Integrate with the existing `postgresql-k8s` charm to set up the database for the new charm. Note that you need to integrate with the `postgresql-k8s` charm via both the `database` and the `mas-database` endpoint
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers. For example, to use the Google IdP, we will deploy the `oauth-external-idp-integrator` charm.
+
+Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration`
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju integrate server-mas oidc
+```
+
+Finally, we need to whitelist the MAS redirect URL on the OIDC client. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be formatted like `<public_baseurl>/auth/upstream/callback/<provider_id>`. We can now go back to the OIDC client configuration on the IdP and whitelist the redirect URL. 
+
+## Back up the existing synapse charm and restore on the new synapse charm
+### Back up and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Back up and Restore"](https://charmhub.io/synapse/docs/how-to-backup-and-restore) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup:
+```
+juju integrate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID; we will use it to restore the backup on the new synapse charm.
+```
+juju integrate s3-integrator server-mas
+juju run synapse/leader restore-backup backup-id=<backup-id>
+```
+
+## Synapse database migration
+### Stop all services on the new and the existing synapse charms
+```
+juju ssh --container synapse server-mas/0 "pebble stop synapse; pebble stop synapse-mas; pebble stop stats-exporter"
+juju ssh --container synapse server/0 "pebble stop synapse; pebble stop stats-exporter"
+```
+
+### Connect to the database
+```
+juju ssh --container synapse server-mas/0 bash
+```
+
+The following commands assume that you are in the `synapse` container of the `server-mas` application.
+```
+apt update
+apt install wget postgresql-client -y
+wget https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64 -O /usr/bin/yq && chmod +x /usr/bin/yq
+```
+
+Copy the original synapse database
+```
+DB_HOST=$(yq e '.database.args.host' /data/homeserver.yaml)
+DB_PORT=$(yq e '.database.args.port' /data/homeserver.yaml)
+DB_PASSWORD=$(yq e '.database.args.password' /data/homeserver.yaml)
+DB_USER=$(yq e '.database.args.user' /data/homeserver.yaml)
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c 'drop database "server-mas";'
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c "create database \"server-mas\" with template server owner $DB_USER;"
+```
+
+In case where postgres gives you an error saying "ERROR:  source database "synapse" is being accessed by other users", drop all connections from the database:
+
+First login to the database
+```
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres
+```
+
+Then run this SQL query to drop all connection from the relevant database ( `<database_name>` )
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
Then run this SQL query to drop all connection from the relevant database ( `<database_name>` ):
```
created_at: 2025-04-04T11:55:09Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,156 @@
+# How to migrate Synapse to the `2/edge` track
+This document shows how to migrate a legacy synapse homeserver (`1/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `1/edge` track that us using the `saml-integrator` charm to provide authentication via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will deploy the new synapse charm with the name `server-mas`. We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with the `postgresql-k8s` charm
+Integrate with the existing `postgresql-k8s` charm to set up the database for the new charm. Note that you need to integrate with the `postgresql-k8s` charm via both the `database` and the `mas-database` endpoint
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers. For example, to use the Google IdP, we will deploy the `oauth-external-idp-integrator` charm.
+
+Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration`
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju integrate server-mas oidc
+```
+
+Finally, we need to whitelist the MAS redirect URL on the OIDC client. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be formatted like `<public_baseurl>/auth/upstream/callback/<provider_id>`. We can now go back to the OIDC client configuration on the IdP and whitelist the redirect URL. 
+
+## Back up the existing synapse charm and restore on the new synapse charm
+### Back up and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Back up and Restore"](https://charmhub.io/synapse/docs/how-to-backup-and-restore) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup:
+```
+juju integrate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID; we will use it to restore the backup on the new synapse charm.
+```
+juju integrate s3-integrator server-mas
+juju run synapse/leader restore-backup backup-id=<backup-id>
+```
+
+## Synapse database migration
+### Stop all services on the new and the existing synapse charms
+```
+juju ssh --container synapse server-mas/0 "pebble stop synapse; pebble stop synapse-mas; pebble stop stats-exporter"
+juju ssh --container synapse server/0 "pebble stop synapse; pebble stop stats-exporter"
+```
+
+### Connect to the database
+```
+juju ssh --container synapse server-mas/0 bash
+```
+
+The following commands assume that you are in the `synapse` container of the `server-mas` application.
+```
+apt update
+apt install wget postgresql-client -y
+wget https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64 -O /usr/bin/yq && chmod +x /usr/bin/yq
+```
+
+Copy the original synapse database
+```
+DB_HOST=$(yq e '.database.args.host' /data/homeserver.yaml)
+DB_PORT=$(yq e '.database.args.port' /data/homeserver.yaml)
+DB_PASSWORD=$(yq e '.database.args.password' /data/homeserver.yaml)
+DB_USER=$(yq e '.database.args.user' /data/homeserver.yaml)
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c 'drop database "server-mas";'
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c "create database \"server-mas\" with template server owner $DB_USER;"
+```
+
+In case where postgres gives you an error saying "ERROR:  source database "synapse" is being accessed by other users", drop all connections from the database:
+
+First login to the database
+```
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres
+```
+
+Then run this SQL query to drop all connection from the relevant database ( `<database_name>` )
+```
+SELECT pg_terminate_backend(pg_stat_activity.pid) FROM pg_stat_activity 
+WHERE pg_stat_activity.datname = '<database_name>' AND pid <> pg_backend_pid();
+```
+
+## Migrating users to MAS
+### Perform user migration to MAS database
+Run the `migrate` command with the `--dryRun` flag to check that there are no errors:
+```
+OAUTH2_PROVIDER_ID=$(yq e '.upstream_oauth2.providers[0].id' /mas/config.yaml)
+npx --yes @vector-im/syn2mas \
+    --command migrate \
+    --synapseConfigFile /data/homeserver.yaml \
+    --masConfigFile /mas/config.yaml \
+    --upstreamProviderMapping saml:$OAUTH2_PROVIDER_ID \
+    --dryRun
+```
+
+You should see the 0 fatals and 0 warnings in the command output:
+```
+[INFO] migrate - Completed migration dry-run of x users with 0 fatals and 0 warnings:
+```
+
+Finally, run the migration command:
+```
+npx --yes @vector-im/syn2mas \
+    --command migrate \
+    --synapseConfigFile /data/homeserver.yaml \
+    --masConfigFile /mas/config.yaml \
+    --upstreamProviderMapping saml:$OAUTH2_PROVIDER_ID
+```
+
+You should see an output similar to that of the dry-run command
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: ```suggestion
You should see an output similar to that of the dry-run command.
```
created_at: 2025-04-04T11:55:35Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
+### Backup and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Backup and Restore"](https://discourse.charmhub.io/t/synapse-docs-backup-and-restore/13212) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup
+```
+juju relate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID, we will use it to restore the backup on the new synapse charm.
+```
+juju relate s3-integrator server-mas
+juju run synapse/leader restore-backup backup-id=<backup-id>
+```
+
+## Synapse database migration
+### Stop all services on the new and the existing synapse charm
+```
+juju ssh --container synapse server-mas/0 "pebble stop synapse; pebble stop synapse-mas; pebble stop stats-exporter"
+juju ssh --container synapse server/0 "pebble stop synapse; pebble stop stats-exporter"
+```
+
+### Connect to the database
+```
+juju ssh --container synapse server-mas/0 bash
+```
+
+The following commands assume that you are in the `synapse` container of the `server-mas` application.
+```
+apt update
+apt install wget postgresql-client -y
+wget https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64 -O /usr/bin/yq && chmod +x /usr/bin/yq
+```
+
+Copy the original synapse database
path: docs/how-to/migrate-to-mas.md
user: login: erinecon
body: @Thanhphan1147 besides this missing "charm"/colon, I have no further comments!
created_at: 2025-04-04T14:40:17Z
author_association: CONTRIBUTOR
diff_hunk: @@ -0,0 +1,145 @@
+# How to back up and restore Synapse
+This document shows how to migrate a legacy synapse homeserver (`latest/edge` track) to an oidc-native homeserver (`2/edge` track).
+
+## Initial deployment setup 
+This document will cover the migration path for a synapse charm on the `latest\edge` track, using the `saml-integrator` charm to provide authentication users via SAML.
+
+## Prepare the new synapse charm
+### Deploy the 2/edge channel on the same model
+We will use the same configuration as the existing synapse charm.
+```
+juju deploy synapse server-mas --channel=2/edge \
+    --config server_name=<server_name> \
+    --config public_baseurl=<public_baseurl>
+```
+
+### Integrate with postgresql
+Integrate with the existing postgresql charm to set up the database for the new charm.
+```
+juju integrate server-mas:mas-database postgresql-k8s
+juju integrate server-mas:database postgresql-k8s
+```
+
+### Configure OIDC
+This step requires the configuration of a client on the OIDC provider of your choice. Please look at the ["Configure an upstream SSO provider"](https://element-hq.github.io/matrix-authentication-service/setup/sso.html) section of the MAS documentation for detailed explanation and sample configurations for popular OIDC providers.
+```
+juju deploy oauth-external-idp-integrator oidc --channel=latest/edge
+juju config oidc \
+  issuer_url=<issuer_url> \
+  authorization_endpoint=<authorization_endpoint> \
+  userinfo_endpoint=<userinfo_endpoint> \
+  token_endpoint=<token_endpoint> \
+  introspection_endpoint=<introspection_endpoint> \
+  jwks_endpoint=<jwks_endpoint> \
+  client_id=<client_id> \
+  client_secret=<client_secret>
+juju relate server-mas oidc
+```
+
+To create the client, it's important to first retrieve the MAS redirect URL. First we get the upstream OIDC provider ID (`<provider_id>`) generated by the charm:
+```
+juju ssh --container synapse server-mas "cat /mas/config.yaml | grep 'id:'"
+```
+
+The MAS redirect URL will be of this format: `<public_baseurl>/auth/upstream/callback/<provider_id>`. Once the client has been created, take note of the `client_id` and `client_secret` generated by the provider. The required endpoints as shown below in the charm configuration can usually be found at `<issuer_url>/.well-known/openid-configuration` 
+
+## Backup the existing synapse charm and restore on the new synapse charm
+### Backup and restore using the s3-integrator charm
+To migrate everything persisted in the Synapse's `/data` directory, we will use the `s3-integrator` charm. For more information please look at the ["Backup and Restore"](https://discourse.charmhub.io/t/synapse-docs-backup-and-restore/13212) section of the charm's documentation. First we deploy the `s3-integrator` charm and configure it with the credentials for the target s3 bucket:
+```
+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>
+```
+
+Then we integrate with the existing synapse charm and create the backup
+```
+juju relate s3-integrator server
+juju run server/leader create-backup
+```
+
+Take note of the backup ID, we will use it to restore the backup on the new synapse charm.
+```
+juju relate s3-integrator server-mas
+juju run synapse/leader restore-backup backup-id=<backup-id>
+```
+
+## Synapse database migration
+### Stop all services on the new and the existing synapse charm
+```
+juju ssh --container synapse server-mas/0 "pebble stop synapse; pebble stop synapse-mas; pebble stop stats-exporter"
+juju ssh --container synapse server/0 "pebble stop synapse; pebble stop stats-exporter"
+```
+
+### Connect to the database
+```
+juju ssh --container synapse server-mas/0 bash
+```
+
+The following commands assume that you are in the `synapse` container of the `server-mas` application.
+```
+apt update
+apt install wget postgresql-client -y
+wget https://github.com/mikefarah/yq/releases/download/v4.44.3/yq_linux_amd64 -O /usr/bin/yq && chmod +x /usr/bin/yq
+```
+
+Copy the original synapse database
+```
+DB_HOST=$(yq e '.database.args.host' /data/homeserver.yaml)
+DB_PORT=$(yq e '.database.args.port' /data/homeserver.yaml)
+DB_PASSWORD=$(yq e '.database.args.password' /data/homeserver.yaml)
+DB_USER=$(yq e '.database.args.user' /data/homeserver.yaml)
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c 'drop database "server-mas";'
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c "create database \"server-mas\" with template server owner $DB_USER;"
+```
+
+In case where postgres gives you an error saying "", drop all connections from the database
+```
+PGPASSWORD=$DB_PASSWORD psql --host $DB_HOST --username $DB_USER --port $DB_PORT postgres -c SELECT pg_terminate_backend(pg_stat_activity.pid) FROM pg_stat_activity WHERE pg_stat_activity.datname = "server" AND pid <> pg_backend_pid();
+```
+
+## Migrating users to MAS
+### Perform user migration to MAS database
path: docs/how-to/migrate-to-mas.md
user: login: amandahla
body: Ok, if needed can be added later
created_at: 2025-04-04T17:00:53Z
author_association: NONE

PR comments:
user: login: github-actions[bot]
created_at: 2025-04-04T21:02:16Z
body: ## Test results for commit 91453125d0f54383eb7fc371fbe96a8049b14672

Test coverage for 91453125d0f54383eb7fc371fbe96a8049b14672

  ```
Name                                    Stmts   Miss Branch BrPart  Cover   Missing
-----------------------------------------------------------------------------------
src/actions.py                             36      0      6      0   100%
src/auth/__init__.py                        0      0      0      0   100%
src/auth/mas.py                            86      6      2      0    93%   78-80, 97-99
src/backup.py                             175      5     20      2    96%   351-352, 421-422, 479->481, 482
src/backup_observer.py                    151     16     14      0    90%   162-165, 170-173, 210-213, 242-245
src/charm.py                              276     26     62     12    89%   178->180, 183, 257, 310, 314-315, 321-322, 340-341, 365, 372, 447-451, 454-455, 483-485, 505, 535-541, 571-572
src/charm_types.py                         30      0      0      0   100%
src/database_client.py                     57      1      8      4    92%   35, 47->exit, 69->exit, 88->98
src/database_observer.py                   49      4      2      0    92%   61-64
src/exceptions.py                           3      0      0      0   100%
src/matrix_auth_observer.py                59      5      6      0    92%   133-137
src/media_observer.py                      45      4      2      1    89%   60-62, 81
src/observability.py                       13      0      0      0   100%
src/pebble.py                             221     38     50     12    82%   158->exit, 169-173, 218-219, 239-240, 258-261, 322->327, 332-333, 345-346, 348-349, 380, 382, 384, 386, 388, 395-398, 426, 577-593, 635-642
src/redis_observer.py                      39      3      4      0    93%   63-66
src/s3_parameters.py                       22      0      4      0   100%
src/smtp_observer.py                       61      1     14      2    96%   89, 108->113
src/state/__init__.py                       0      0      0      0   100%
src/state/charm_state.py                  144     11     34      7    90%   168, 172, 193, 218, 224, 230, 234-235, 321, 388-389
src/state/mas.py                           79      8      6      3    87%   154, 160-161, 188-190, 205, 225
src/state/validation.py                    36      3      2      0    92%   110-112
src/synapse/__init__.py                     2      0      0      0   100%
src/synapse/workload.py                   152      7     30      2    93%   370-373, 404-405, 453
src/synapse/workload_configuration.py     149     26     34     12    79%   90->exit, 94-95, 143-144, 173, 193-194, 226-227, 260, 269-270, 285, 290-291, 312-313, 332->337, 338, 356->358, 368-369, 397, 405->407, 407->409, 414-415, 435->442, 445, 465-466
src/user.py                                23      5      2      1    76%   27-29, 56, 73
-----------------------------------------------------------------------------------
TOTAL                                    1908    169    302     58    90%
```
  Static code analysis report

  ```
Working... ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 100% 0:00:00
Run started:2025-04-04 21:01:25.064968

Test results:
	No issues identified.

Code scanned:
	Total lines of code: 9844
	Total lines skipped (#nosec): 6
	Total potential issues skipped due to specifically being disabled (e.g., #nosec BXXX): 0

Run metrics:
	Total issues (by severity):
		Undefined: 0
		Low: 0
		Medium: 0
		High: 0
	Total issues (by confidence):
		Undefined: 0
		Low: 0
		Medium: 0
		High: 0
Files skipped (0):
```
author_association: CONTRIBUTOR