syn2mas: document new tool

docs/setup/migration.md

@@ -18,28 +18,29 @@ There will be tools to help with the migration process itself. But these aren't
 
 The deployment is non-trivial so it is important to read through and understand the steps involved and make a plan before starting.
 
-### Get `syn2mas`
+### Is your setup ready to be migrated?
 
-The easiest way to get `syn2mas` is through [`npm`](https://www.npmjs.com/package/@vector-im/syn2mas):
+#### SAML2 and LDAP Single Sign-On Providers are not supported
 
-```sh
-npm install -g @vector-im/syn2mas
-```
+A deployment which requires SAML or LDAP-based authentication should use a service like [Dex](https://github.com/dexidp/dex) to bridge between the SAML provider and the authentication service.
+MAS is different from Synapse in that it does **not** have built-in support for SAML or LDAP-based providers.
 
-### Run the migration advisor
+#### Custom password providers are not supported
 
-You can use the advisor mode of the `syn2mas` tool to identify extra configuration steps or issues with the configuration of the homeserver.
+If your Synapse homeserver currently uses a custom password provider module, please note that MAS does not support these.
 
-```sh
-syn2mas --command=advisor --synapseConfigFile=homeserver.yaml
-```
+#### SQLite databases are not supported
 
-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.
+It is worth noting that MAS currently only supports PostgreSQL as a database backend.
 
 ### Install and configure MAS alongside your existing homeserver
 
 Follow the instructions in the [installation guide](installation.md) to install MAS alongside your existing homeserver.
 
+You'll need a blank PostgreSQL database for MAS to use; it does not share the database with the homeserver.
+
+Set up a configuration file but don't start MAS, or create any users, yet.
+
 #### Local passwords
 
 Synapse uses bcrypt as its password hashing scheme while MAS defaults to using the newer argon2id.
@@ -51,63 +52,109 @@ Example passwords configuration:
 passwords:
   enabled: true
   schemes:
-  - version: 1
+  - version: 1 # TODO I think v:2 has to come first in this list
     algorithm: bcrypt
   - version: 2
     algorithm: argon2id
 ```
 
+If you have a pepper configured in your Synapse password configuration, you'll need to match that on version 1 of the equivalent MAS configuration.
+
+The migration checker will inform you if this has not been configured properly.
+
 ### 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.
+If you are using an upstream SSO provider, then you will need to configure the upstream provider in MAS manually.
 
-Each upstream provider will need to be given as an `--upstreamProviderMapping` command line option to the import tool.
+MAS does not support SAML or LDAP upstream providers.
+If you are using one of these, you will need to use an adapter such as Dex at this time,
+but we have not yet documented this procedure.
 
-### Prepare the MAS database
+Each upstream provider that was used by at least one user in Synapse will need to be configured in MAS.
 
-Once the database is created, it still needs to have its schema created and synced with the configuration.
-This can be done with the following command:
+Set the `synapse_idp_id` attribute on the provider to:
 
-```sh
-mas-cli config sync
-```
+- `"oidc"` if you used an OIDC provider in Synapse's legacy `oidc_config` configuration section.
+- `"oidc-myprovider"` if you used an OIDC provider in Synapse's `oidc_providers` configuration list,
+  with a `provider` of `"myprovider"`.
+  (This is because Synapse prefixes the provider ID with `oidc-` internally.)
 
-### Do a dry-run of the import to test
+Without the `synapse_idp_id`s being set, syn2mas does not understand which providers
+in Synapse correspond to which provider in MAS.
+
+!!!!!!!!! TODO add an example here
+
+The migration checker will inform you if a provider is missing from MAS' config.
+
+### Run the migration checker
+
+You can use the `check` command of the `syn2mas` tool to identify configuration problems before starting the migration.
+You do not need to stop Synapse to run this command.
 
 ```sh
-syn2mas --command migrate --synapseConfigFile homeserver.yaml --masConfigFile config.yaml --dryRun
+mas-cli --config mas_config.yaml syn2mas --synapse-config homeserver.yaml check
 ```
 
-If no errors are reported then you can proceed to the next step.
+This will either output a list of errors and warnings, or tell you that the check completed with no errors or warnings.
+
+If you have any errors, you must resolve these before starting the migration.
+
+If you have any warnings, please read, understand and possibly resolve them.
+With that said, resolving them is not strictly required before starting the migration.
+
+### Do a dry-run of the import to test
+
+!!!!!!! TODO we don't have an exact dry-run mode exposed at the moment...
 
 ## Doing the migration
 
 Having done the preparation, you can now proceed with the actual migration. Note that this will require downtime for the homeserver and is not easily reversible.
 
-### Backup your data
+### Backup your data and configuration
 
 As with any migration, it is important to backup your data before proceeding.
 
+We also suggest making a backup copy of your homeserver's known good configuration,
+before making any changes to enable MAS integration.
+
 ### Shutdown the homeserver
 
 This is to ensure that no new sessions are created whilst the migration is in progress.
 
-### Configure the homeserver
+### Configure the homeserver to enable MAS integration
 
 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.
+Once the homeserver has been stopped, MAS has been configured (but is not running!)
+and you have a successful migration check,
+run `syn2mas`'s `migrate` command.
+
+Other than the change of command word, the syntax is exactly the same as the `check` command.
 
 ```sh
-syn2mas --command migrate --synapseConfigFile homeserver.yaml --masConfigFile config.yaml --dryRun false
+mas-cli --config mas_config.yaml syn2mas --synapse-config homeserver.yaml migrate
 ```
 
+#### What to do if it goes wrong
+
+If the migration fails with an error:
+
+- You can either try to fix the error and make another attempt by re-running the command; or
+- you can revert your homeserver configuration (so MAS integration is disabled once more)
+  and abort the migration for now. In this case, you should not start MAS up.
+
+Please report migration failures to the developers.
+
 ### Start up the homeserver
 
 Start up the homeserver again with the new configuration.
 
+### Start up MAS
+
+Start up MAS.
+
 ### Update or serve the .well-known
 
 The `.well-known/matrix/client` needs to be served as described [here](./well-known.md).