diff options
author | James E. Blair <jim@acmegating.com> | 2021-06-12 13:39:29 -0700 |
---|---|---|
committer | James E. Blair <jim@acmegating.com> | 2021-06-12 13:39:29 -0700 |
commit | 7c618997932651ff0a8222a34ddc47a61b1f2207 (patch) | |
tree | 679e95f2247be9c38076646a0012b3fe074317fb /doc | |
parent | 09eaad4087b2055ac0db8291cb7c8034a2497457 (diff) | |
download | zuul-7c618997932651ff0a8222a34ddc47a61b1f2207.tar.gz |
Add Matrix HOWTO
Add a HOWTO that walks through setting up a Matrix account with
Element and matrix.org, joining #zuul, and some optional additional
steps to save encryption keys and register with a 3pid provider.
Change-Id: I217c44a7270033998113e434f40a49c2dbb6aaef
Diffstat (limited to 'doc')
31 files changed, 246 insertions, 0 deletions
diff --git a/doc/source/howtos/matrix.rst b/doc/source/howtos/matrix.rst new file mode 100644 index 000000000..932061126 --- /dev/null +++ b/doc/source/howtos/matrix.rst @@ -0,0 +1,245 @@ +Chatting with Matrix +==================== + +The Zuul community uses mailing lists for long-form communication and +IRC for real-time (or near real-time) chat. We are working on moving +our chat platform to Matrix. You can start using Matrix now to chat +with us on IRC and when we move, the transition will be seamless. + +This guide will walk you through getting started with Matrix and how +to use it to join communities like Zuul on IRC. + +Familiar with Matrix already and want to jump straight to the room? +Follow this link: https://matrix.to/#/#_oftc_#zuul:matrix.org + +Why Use Matrix? +--------------- + +Matrix has a number of clients available including feature-rich web, +desktop and mobile clients, as well as integration with the popular +text-based weechat client. This provides plenty of choices based on +your own preference. This guide will focus on using the Element web +client. + +Matrix supports persistent presence in "rooms". Once you join a room, +your homeserver will keep you connected to that room and save all of +the messages sent to it, so that if you close your client and return +later, you won't miss anything. You don't need to run your own server +to use Matrix; you are welcome to use the public server at matrix.org. +But if you are a member of an organization that already runs a +homeserver, or you would like to run one yourself, you may do so and +federate with the larger Matrix network. This guide will walk you +through setting up an account on the matrix.org homeserver. + +Matrix is an open (in every sense of the word) federated communication +system. Because of this it's possible to bridge the Matrix network to +other networks (including IRC, slack, etc). That makes it the perfect +system to use to communicate with various communities using a single +interface. + +Create An Account +----------------- + +If you don't already have an account on a Matrix homeserver, go to +https://app.element.io/ to create one, then click `Create Account`. + +.. image:: /images/matrix/account-welcome.png + :align: center + +You can create an account with an email address or one of the +supported authentication providers. + +.. image:: /images/matrix/account-create.png + :align: center + +You'll be asked to accept the terms and conditions of the service. + +.. image:: /images/matrix/account-accept.png + :align: center + +If you are registering an account via email, you will be prompted to +verify your email address. + +.. image:: /images/matrix/account-verify.png + :align: center + +You will receive an email like this: + +.. image:: /images/matrix/account-verify-email.png + :align: center + +Once you click the link in the email, your account will be created. + +.. image:: /images/matrix/account-success.png + :align: center + +You can follow the link to sign in. + +.. image:: /images/matrix/account-signin.png + :align: center + +Join the #zuul Channel +---------------------- + +The ``#zuul`` channel is hosted on the OFTC IRC network, and is +accessible via a bridge run by the Matrix community. To join +``#zuul``, perform the following steps: + +Click the plus icon next to `Rooms` on the left of the screen, then +click `Explore public rooms` in the dropdown that appears. + +.. image:: /images/matrix/account-rooms-dropdown.png + :align: center + +A popup dialog will appear; below the search bar in the dialog, click +the dropdown selector labeled `Matrix rooms (matrix.org)` and change +it to `OFTC rooms (matrix.org)`. Then enter ``#zuul`` into the search +box. + +.. image:: /images/matrix/account-rooms-zuul.png + :align: center + +It will display `No results for "#zuul"` which is an unfortunate +consequence of one of the anti-spam measures that is necessary on IRC. +Disregard that and hit `enter` or click `Join`, and you will join the +room. + +If this is your first time joining an OFTC channel, you will also +receive an invitation to join the `OFTC IRC Bridge status` room. + +.. image:: /images/matrix/account-rooms-invite.png + :align: center + +Accept the invitation. + +.. image:: /images/matrix/account-rooms-accept.png + :align: center + +This is a private control channel between you and the system that +operates the OFTC bridge. Here you can perform some IRC commands such +as changing your nickname and setting up nick registration. That is +out of scope for this HOWTO, but advanced IRC users may be interested +in doing so. + +You may repeat this procedure for any other IRC channels on the OFTC, +Freenode, or libera.chat networks. + +Click the `#zuul` room name on the left of the screen to return the +Zuul room. + +Go ahead and say hi, introduce yourself, and let us know what you're +working on or any questions you have. Keep in mind that the Zuul +community is world-wide and we may be away from our desks when you +join. Because Matrix keeps a message history, we'll see your message +and you'll see any responses, even if you close your browser and log +in later. + +Optional: Save Encryption Keys +------------------------------ + +The Matrix protocol supports end-to-end encryption. We don't have +this enabled for the ``#zuul`` room (there's little point as it's a +public room), but if you start direct chats with other Matrix users, +your communication will be encrypted by default. Since it's +*end-to-end* encryption, that means your encryption keys are stored on +your client, and the server has no way to decrypt those messages. But +that also means that if you sign out of your client or switch +browsers, you will lose your encryption keys along with access to any +old messages that were encrypted with them. To avoid this, you can +back up your keys to the server (in an encrypted form, of course) so +that if you log in from another session, you can restore those keys +and pick up where you left off. To set this up, open the User Menu by +clicking on your name at the top left of the screen. + +.. image:: /images/matrix/user-menu.png + :align: center + +Click the `Security & privacy` menu item in the dropdown. + +.. image:: /images/matrix/user-menu-dropdown.png + :align: center + +Click the `Set up` button under `Encryption` / `Secure Backup` in the +dialog that pops up. + +.. image:: /images/matrix/user-encryption.png + :align: center + +Follow the prompts to back up your encryption keys. + +Optional: Register with an Identity Provider +-------------------------------------------- + +By default, there is no public link between your Matrix account and +any identifying information such as your email address. However, you +may wish people to be able to find your Matrix ID by looking up your +email address or phone number. We also have plans to add additional +functionality to our bots if they are able to look up contributors by +email addresses. If you wish to make your account discoverable in +this way, you may perform the following steps to list your account in +one of the public third-party identifier services. Note that these +services are designed to only return results for someone who already +knows your email address or phone number; they take care to ensure +that it is not possible (or nearly so) to "scrape" their data sets to +obtain lists of users. + +To get started, open the User Menu and click `All settings`. Under +the `General` section, find `Email addresses`. If you followed the +instructions above, you should already have an email address listed +here. If you don't, enter your address, click `Add`, and follow the +instructions to verify your address. The dialog should look like this +when complete: + +.. image:: /images/matrix/id-email-complete.png + :align: center + +To make your account discoverable by email, scroll down to the +`Discovery` section. + +.. image:: /images/matrix/id-disc.png + :align: center + +Read the privacy notice and click the checkbox +next to `Accept`. That will enable the `Continue` button; click that +to proceed. + +.. image:: /images/matrix/id-disc-accept.png + :align: center + +The `Discovery` section will be replaced with the email address you +registered above. + +.. image:: /images/matrix/id-disc-accept.png + :align: center + +Click the `Share` button next to the address. The system will send an +email to you, and meanwhile the dialog will show this: + +.. image:: /images/matrix/id-disc-verify-wait.png + :align: center + +You will receive an email like this: + +.. image:: /images/matrix/id-disc-verify-email.png + :align: center + +Follow the link in the email to verify it really is you making the +request. + +.. image:: /images/matrix/id-disc-verify-success.png + :align: center + +Then return to the settings page and click the `Complete` button. + +.. image:: /images/matrix/id-disc-verify-wait.png + :align: center + +Once everything is finished, the complete button should change to read +`Revoke`. + +.. image:: /images/matrix/id-disc-verify-complete.png + :align: center + +If you see that, you're all done. If you change your mind and don't +want your account to be discoverable via email, you can click the +`Revoke` button at any time. diff --git a/doc/source/howtos/user.rst b/doc/source/howtos/user.rst index 55f3d7cd9..bd7a11c77 100644 --- a/doc/source/howtos/user.rst +++ b/doc/source/howtos/user.rst @@ -7,3 +7,4 @@ User How-to Guides cross-project-gating pti badges + matrix diff --git a/doc/source/images/matrix/account-accept.png b/doc/source/images/matrix/account-accept.png Binary files differnew file mode 100644 index 000000000..504477fcc --- /dev/null +++ b/doc/source/images/matrix/account-accept.png diff --git a/doc/source/images/matrix/account-create.png b/doc/source/images/matrix/account-create.png Binary files differnew file mode 100644 index 000000000..31fa08f6d --- /dev/null +++ b/doc/source/images/matrix/account-create.png diff --git a/doc/source/images/matrix/account-rooms-accept.png b/doc/source/images/matrix/account-rooms-accept.png Binary files differnew file mode 100644 index 000000000..b7e96d156 --- /dev/null +++ b/doc/source/images/matrix/account-rooms-accept.png diff --git a/doc/source/images/matrix/account-rooms-dropdown.png b/doc/source/images/matrix/account-rooms-dropdown.png Binary files differnew file mode 100644 index 000000000..58236816e --- /dev/null +++ b/doc/source/images/matrix/account-rooms-dropdown.png diff --git a/doc/source/images/matrix/account-rooms-invite.png b/doc/source/images/matrix/account-rooms-invite.png Binary files differnew file mode 100644 index 000000000..bb9457a25 --- /dev/null +++ b/doc/source/images/matrix/account-rooms-invite.png diff --git a/doc/source/images/matrix/account-rooms-zuul.png b/doc/source/images/matrix/account-rooms-zuul.png Binary files differnew file mode 100644 index 000000000..0e30a292d --- /dev/null +++ b/doc/source/images/matrix/account-rooms-zuul.png diff --git a/doc/source/images/matrix/account-rooms.png b/doc/source/images/matrix/account-rooms.png Binary files differnew file mode 100644 index 000000000..bcf9d9a3e --- /dev/null +++ b/doc/source/images/matrix/account-rooms.png diff --git a/doc/source/images/matrix/account-signin.png b/doc/source/images/matrix/account-signin.png Binary files differnew file mode 100644 index 000000000..4e2fdded0 --- /dev/null +++ b/doc/source/images/matrix/account-signin.png diff --git a/doc/source/images/matrix/account-success.png b/doc/source/images/matrix/account-success.png Binary files differnew file mode 100644 index 000000000..d7f16999f --- /dev/null +++ b/doc/source/images/matrix/account-success.png diff --git a/doc/source/images/matrix/account-verify-email.png b/doc/source/images/matrix/account-verify-email.png Binary files differnew file mode 100644 index 000000000..c628873da --- /dev/null +++ b/doc/source/images/matrix/account-verify-email.png diff --git a/doc/source/images/matrix/account-verify.png b/doc/source/images/matrix/account-verify.png Binary files differnew file mode 100644 index 000000000..5cc519d52 --- /dev/null +++ b/doc/source/images/matrix/account-verify.png diff --git a/doc/source/images/matrix/account-welcome.png b/doc/source/images/matrix/account-welcome.png Binary files differnew file mode 100644 index 000000000..d9ee8ec6f --- /dev/null +++ b/doc/source/images/matrix/account-welcome.png diff --git a/doc/source/images/matrix/id-disc-accept.png b/doc/source/images/matrix/id-disc-accept.png Binary files differnew file mode 100644 index 000000000..2423042b0 --- /dev/null +++ b/doc/source/images/matrix/id-disc-accept.png diff --git a/doc/source/images/matrix/id-disc-share.png b/doc/source/images/matrix/id-disc-share.png Binary files differnew file mode 100644 index 000000000..46fab5445 --- /dev/null +++ b/doc/source/images/matrix/id-disc-share.png diff --git a/doc/source/images/matrix/id-disc-verify-complete.png b/doc/source/images/matrix/id-disc-verify-complete.png Binary files differnew file mode 100644 index 000000000..4d3211a25 --- /dev/null +++ b/doc/source/images/matrix/id-disc-verify-complete.png diff --git a/doc/source/images/matrix/id-disc-verify-email.png b/doc/source/images/matrix/id-disc-verify-email.png Binary files differnew file mode 100644 index 000000000..ffe0a3c44 --- /dev/null +++ b/doc/source/images/matrix/id-disc-verify-email.png diff --git a/doc/source/images/matrix/id-disc-verify-success.png b/doc/source/images/matrix/id-disc-verify-success.png Binary files differnew file mode 100644 index 000000000..0de00faeb --- /dev/null +++ b/doc/source/images/matrix/id-disc-verify-success.png diff --git a/doc/source/images/matrix/id-disc-verify-wait.png b/doc/source/images/matrix/id-disc-verify-wait.png Binary files differnew file mode 100644 index 000000000..6ea2e225c --- /dev/null +++ b/doc/source/images/matrix/id-disc-verify-wait.png diff --git a/doc/source/images/matrix/id-disc.png b/doc/source/images/matrix/id-disc.png Binary files differnew file mode 100644 index 000000000..d5c8715fe --- /dev/null +++ b/doc/source/images/matrix/id-disc.png diff --git a/doc/source/images/matrix/id-email-add.png b/doc/source/images/matrix/id-email-add.png Binary files differnew file mode 100644 index 000000000..c0c086e1d --- /dev/null +++ b/doc/source/images/matrix/id-email-add.png diff --git a/doc/source/images/matrix/id-email-complete.png b/doc/source/images/matrix/id-email-complete.png Binary files differnew file mode 100644 index 000000000..54779c9b2 --- /dev/null +++ b/doc/source/images/matrix/id-email-complete.png diff --git a/doc/source/images/matrix/id-email-password.png b/doc/source/images/matrix/id-email-password.png Binary files differnew file mode 100644 index 000000000..2c7874eef --- /dev/null +++ b/doc/source/images/matrix/id-email-password.png diff --git a/doc/source/images/matrix/id-email-verified.png b/doc/source/images/matrix/id-email-verified.png Binary files differnew file mode 100644 index 000000000..fa15bc328 --- /dev/null +++ b/doc/source/images/matrix/id-email-verified.png diff --git a/doc/source/images/matrix/id-email-verify-email.png b/doc/source/images/matrix/id-email-verify-email.png Binary files differnew file mode 100644 index 000000000..5842f9b01 --- /dev/null +++ b/doc/source/images/matrix/id-email-verify-email.png diff --git a/doc/source/images/matrix/id-email.png b/doc/source/images/matrix/id-email.png Binary files differnew file mode 100644 index 000000000..c42baf05f --- /dev/null +++ b/doc/source/images/matrix/id-email.png diff --git a/doc/source/images/matrix/id-general.png b/doc/source/images/matrix/id-general.png Binary files differnew file mode 100644 index 000000000..53bc1651c --- /dev/null +++ b/doc/source/images/matrix/id-general.png diff --git a/doc/source/images/matrix/user-encryption.png b/doc/source/images/matrix/user-encryption.png Binary files differnew file mode 100644 index 000000000..48c603ce5 --- /dev/null +++ b/doc/source/images/matrix/user-encryption.png diff --git a/doc/source/images/matrix/user-menu-dropdown.png b/doc/source/images/matrix/user-menu-dropdown.png Binary files differnew file mode 100644 index 000000000..fa0c2c4da --- /dev/null +++ b/doc/source/images/matrix/user-menu-dropdown.png diff --git a/doc/source/images/matrix/user-menu.png b/doc/source/images/matrix/user-menu.png Binary files differnew file mode 100644 index 000000000..b9917e767 --- /dev/null +++ b/doc/source/images/matrix/user-menu.png |