Migration mode + docs

docs/setup/migration.md

@@ -12,4 +12,67 @@ Features that are provided to support this include:
 - Ability to import existing upstream IdP subject ID mappings
 - Provides a compatibility layer for legacy Matrix authentication
 
+If
 There will be tools to help with the migration process itself. But these aren't quite ready yet.
+
+## Preparation for the migration
+
+The deployment is non-trivial so it is important to read through and understand the steps involved and make a plan before starting.
+
+### Run the migration advisor
+
+You can use the advisor mode of the `syn2mas` tool to identify extra configuration steps or issues with the configuration of the homeserver.
+
+```sh
+syn2mas --command=advisor --synapseConfigFile=homeserver.yaml
+```
+
+This will output `WARN` entries for any identified actions and `ERROR` entries in the case of any issues that will prevent the migration from working.
+
+### Install and configure MAS alongside your existing homeserver
+
+Follow the instructions in the [installation guide](installation.md) to install MAS alongside your existing homeserver.
+
+### Map any upstream SSO providers
+
+If you are using an upstream SSO provider then you will need to provision the upstream provide in MAS manually.
+
+Each upstream provider will need to be given as an `--upstreamProviderMapping` command line option to the import tool.
+
+### Do a dry-run of the import to test
+
+```sh
+syn2mas --command migrate --synapseConfigFile homeserver.yaml --masConfigFile config.yaml --dryRun
+```
+
+If no errors are reported then you can proceed to the next step.
+
+## Doing the migration
+
+### Backup your data
+
+As with any migration, it is important to backup your data before proceeding.
+
+### Shutdown the homeserver
+
+This is to ensure that no new sessions are created whilst the migration is in progress.
+
+### Configure the homeserver
+
+Follow the instructions in the [homeserver configuration guide](homeserver.md) to configure the homeserver to use MAS.
+
+### Do the import
+
+Run `syn2mas` in non-dry-run mode.
+
+```sh
+syn2mas --command migrate --synapseConfigFile homeserver.yaml --masConfigFile config.yaml --dryRun false
+```
+
+### Start up the homeserver
+
+Start up the homeserver again with the new configuration.
+
+### Update or serve the .well-known
+
+The `.well-known/matrix/client` needs to be served as described [here](./well-known.md).

docs/setup/well-known.md

@@ -0,0 +1,23 @@
+# .well-known configuration
+
+A `.well-known/matrix/client` file is required to be served to allow clients to discover the authentication service.
+
+If no `.well-known/matrix/client` file is served currently then this will need to be enabled.
+
+If the homeserver is Synapse and serving this file already then the correct values will already be included when the homeserver is [configured to use MAS](./homeserver.md).
+
+If the .well-known is hosted elsewhere then `org.matrix.msc2965.authentication` entries need to be included similar to the following:
+
+```json
+{
+  "m.homeserver": {
+    "base_url": "https://matrix.example.com"
+  },
+  "org.matrix.msc2965.authentication": {
+    "issuer": "https://example.com/",
+    "account": "https://auth.example.com/account"
+  }
+}
+```
+
+For more context on what the correct values are, see [here](./README.md).