Great choice!
This repo brings together some tools and self-hostable infrastructure to help guide your users from Slack to their new home on Riot.im.
The tools in this repo will help you to:
- mirror the set of Slack users onto a Matrix.org homeserver
- advertise Riot.im and the migration process to users on Slack (via a Slack bot)
- securely allow Slack users to claim their corresponding Matrix IDs via a simple web interface
The end result is that you can guarantee that @alice from your Slack workspace is the same person as @alice:yourdomain.com in Matrix, providing confidence and continuity of identity and ensuring a streamlined migration.
These tools do not copy or sync rooms, room membership or room history.
In that case you can use a subset of the tools to manage a simpler migration - you might still want to use
scripts/list_slack_users.py
to fetch a list of Slack user email addresses and then use the standard Matrix 'invite by email' feature to guide your users onto Riot.im.
We are going to (not necessarily in this order):
- puppet a Slack bot to pull the necessary details out of Slack to pre-register accounts for users on a Matrix homeserver
- build and deploy a web interface that lets Slack users securely claim their accounts on a Matrix homeserver
- puppet the same Slack bot to advertise a unique link to each of the migrating Slack users
The migration management web interface comprises a static Mithril.js web form and a stateless python Flask API.
These instructions assume you're using AWS to host the static .js page, and the Flask API has been optimised for deployment to AWS lambda using Zappa, but other hosting options are available and it shouldn't be too hard to adapt.
Make sure you have:
- Capacity on your Slack instance for another integration (Slack limits free accounts to 10 integrations)
- An AWS account
- The address of your Matrix homeserver, such as
https://matrix.example.com
- The
registration_shared_secret
from the target homeserverhomeserver.yaml
passgen_secret
- a shared secret to transform Matrix IDs into passwords (can be generated using$ pwgen 80 1
)migration_secret
- a shared secret to validate that a user's account claim token was generated by us (can be generated using$ pwgen 80 1
)- Installed on your local machine:
- aws command line tools installed on your local machine
- Virtualenv installed on your local machine
- Zappa installed on your local machine
- npm installed on your local machine
- Finally: consider posting a public statement on an official channel. Your users will greet a direct message from an unfamiliar Slack bot with skepticism, so make sure you give them enough information that they know it can be trusted 😄
git clone https://github.com/lampholder/concorde.git
cd concorde
~/concorde$ mkdir venv-concorde
~/concorde$ virtualenv venv-concorde
~/concorde$ source venv-concorde/bin/activate
~/concorde$ cd concorde
~/concorde/concorde$ pip install -r requirements.txt
~/concorde/concorde$ python setup.py install
~/concorde/concorde$ cd ..
~/concorde$ cd website/api
~/concorde/website/api$ cp config.example.yaml config.yaml
- Update
config.yaml
to include the address of your target homserver and the generatedpassgen_secret
andmigration_secret
~/concorde/website/api$ zappa init
- Accept Zappa's suggestions for all of the values except for:
What do you want to call this environment (default 'dev'):
- specifyproduction
Where is your app's function?:
- specifyapi.app
~/concorde/website/api$ zappa deploy production
and ** note the generated AWS API gateway URL**~/concorde/website/api$ cd ../..
- Create the S3 bucket:
~/concorde$ aws s3 mb s3://your-bucket-name
~/concorde$ cd website/ui
~/concorde/website/ui$ npm run-script build -- --env.registrationApiUrl <API gateway URL> --env.homeserver <url of homeserver> --env.slackTeam <Slack team name>
~/concorde/website/ui$ aws s3 sync ./dist s3://your-bucket-name/production
- Log into the AWS console and make
/production
publicly accessible - Note the public URL of
/production/index.html
~/concorde/website/ui$ cd ../..
N.B This section might quickly become out of date as Slack changes their UI - please submit a PR if you find any differences as you try to follow these instructions.
- Go to https://api.slack.com/apps
- Register an app
- Click 'Add features and functionality'
- Click 'Bots'
- Click 'Add a bot user'
- Choose a name and avatar that won't startle your users
- Click 'Add bot user'
- Go to 'OAuth and Permissions'
- Install the app to your workspace
- Get the bot user oauth token
~/concorde$ cd scripts
~/concorde/scripts$ ./list_slack_users.py --bot-oauth-token <bot-oauth-token> --fields id username real_name display_name > slack_users.csv
- Register the Slack usernames as Matrix accounts:
~/concorde/scripts$ while read line; do
user=($line)
./register_matrix_user.py --homeserver <homeserver_url> --homeserver-secret <registration_shared_secret> --passgen-secret <passgen_secret> $user[1]
done < slack_users.csv
- Send the invites over Slack DM:
~/concorde/scripts$ while read line; do
user=($line)
link=(./generate_link.py --migration-secret <migration_secret> <S3 public url for index.html> $user[1] --display-name $user[3])
./send_slack_dm.py --bot-oauth-token <bot-oauth-token> $user[0] "Hello $user[3], as you've probably heard we're migrating from Slack to Riot.im - here is your unique link to claim your Riot.im account: $link"
done < slack_users.csv
~/concorde/scripts$ cd ..
~/concorde$ cd website/api
~/concorde/website/api$ zappa tail | grep CONCORDE