Add matrix docs

docs/.custom_wordlist.txt

@@ -32,6 +32,8 @@ Ewan
 Fosstodon
 Gobuntu
 gvfs
+homeserver
+homeservers
 Indri
 IPs
 ISOs
@@ -47,6 +49,7 @@ metapackage
 microreleases
 MIRs
 misconfigured
+Mjolnir
 MOTUs
 multiarch
 Mythbuntu

docs/community/contributors/matrix/completing-setup.md

@@ -0,0 +1,51 @@
+(matrix-completing-setup)=
+# Completing your Matrix setup
+
+If you are reading this guide, you most likely completed the {ref}`Getting started with Matrix <matrix-onboarding>` guide.
+This document explains the next steps to complete your Matrix setup.
+While these steps are not required, they are greatly recommended because they will make your long-term experience a lot better.
+
+
+## Backup your encryption keys
+
+Make sure your encryption keys are backed up.
+Without encryption key backups, you might not be able to restore your end-to-end encrypted chats if you log off all your devices.
+
+
+### Recovery key
+
+* Open your Element client, click the "gear" icon, and select {guilabel}`All settings`
+* Select the {guilabel}`Encryption` icon
+* Navigate to the {guilabel}`Recovery` section and select {guilabel}`Set up recovery`
+* Follow the on-screen instructions to generate your unique security key
+* Store your unique security key in a safe place
+* Ensure the button in the {guilabel}`Recovery` section now reads: "Change recovery key"
+
+
+### Export keys
+
+Optionally, you can also manually export your encryption keys:
+
+* Navigate to the {guilabel}`Advanced` section of the {guilabel}`Encryption` settings
+* Select {guilabel}`Export keys`
+* Read the instructions carefully, and enter a passphrase to protect your manual encryption keys
+* Download the export file and store it in a safe place
+
+
+## Advertise your Matrix ID
+
+To make sure people know how to reach you, it's best to advertise your Matrix ID in a prominent place.
+Launchpad now has the option to advertise your Matrix ID on your profile.
+Edit it on [Launchpad](https://launchpad.net/~/).
+
+![Matrix ID|256x88](matrix-id.png)
+
+Make sure to always write the full matrix ID, including the homeserver, in the form `@<username>:<homeserver>`. Just specifying your username is not enough, because different people can have the same username on different homeservers.
+
+
+## Further reading
+
+* Do you have multiple Matrix accounts and want to use them at the same time? {ref}`matrix-multiple-accounts`
+* Do you want to create rooms for your own community? {ref}`matrix-management`
+* Do you want to know who is in charge of moderation and policy-making on our homeserver? {ref}`matrix-council`
+

docs/community/contributors/matrix/index.md

@@ -0,0 +1,33 @@
+(using-matrix)=
+# Using Matrix
+
+Matrix is the platform we use to chat and discuss various topics within the Ubuntu Community.
+
+
+## Getting started
+
+In this section, we'll show you how to join our Matrix community from the federated Matrix network, and how to log in directly on the Ubuntu homeserver. 
+
+```{toctree}
+:maxdepth: 1
+
+onboarding
+completing-setup
+register-ubuntu-com
+multiple-accounts
+```
+
+
+## Reporting issues
+
+In this section, you'll find guides to reporting both bugs and spammers.
+
+```{toctree}
+:maxdepth: 1
+
+matrix-bug-reporting
+matrix-spam
+matrix-abuse-reporting
+matrix-ignore-list
+```
+

docs/community/contributors/matrix/matrix-abuse-reporting.md

@@ -0,0 +1,47 @@
+(matrix-abuse-reporting)=
+# How to report abuse
+
+
+(defenders-contact)=
+## Ask for Defender help
+
+Matrix users that see offensive, inappropriate, or {ref}`CoC-violating <code-of-conduct>` content, can help the Operations team by reporting it.
+Defenders can help with this type of task and they can protect all official Ubuntu rooms.
+If you need a Defender:
+
+* Join the Ubuntu {matrix}`Matrix Ops room <matrix-ops>`
+
+* Send a message in this room asking Defender's help and pointing to the room where action needs to be taken, for example: `!defenders please help in room #discuss:ubuntu.com`
+
+Adding `!defenders` before your message triggers a notification to all the Defenders in the Ubuntu homeserver and can be used in any room.
+
+
+(moderators-contact)=
+## Ask for moderation help and advice
+
+When a Matrix user witnesses behavior that is not obvious spam, inappropriate, or breaching the CoC, a moderator might be needed.
+Moderators observe situations, de-escalate when possible, and intervene when necessary.
+If you need the help of a Moderator:
+
+* Click on the name of the room from the top bar of your Element client.
+* From the dropdown, select {guilabel}`People` and click on it.
+* A panel will open on the right side of your Element client, with a list of users.
+* Look for users that have "Mod" next to their name. If you see none, you can reach out to users that have "Admin" next to their name.
+* Select the moderator or administrator you want to contact, and click on the user name.
+* The panel changes to the particular user; from {guilabel}`Options`, select "Message".
+
+
+## Contact the Matrix Council
+
+If you need to escalate an issue or reach out to the Matrix Council, refer to {ref}`contact-matrix-council`.
+
+
+## Further reading
+
+To learn more about moderation and Matrix in general:
+
+* {ref}`How to manage your ignore list <matrix-ignore-list>`
+* {ref}`matrix-moderation-and-defense`
+* {ref}`matrix-defenders`
+* {ref}`using-matrix`
+

docs/community/contributors/matrix/matrix-bug-reporting.md

@@ -0,0 +1,14 @@
+(matrix-bug-reporting)=
+# Matrix bug reporting
+
+Bug reports and feature requests
+: Report bugs, issues, and feature requests in [this GitHub repository](https://github.com/canonical/synapse-operator/issues). We will review the feedback regularly and use it to resolve issues or consider features to improve interactions between community members and staff.
+
+
+Matrix discussions
+: If you want to take part in the broader discussion about the Ubuntu Matrix project, you can do so in [this Discourse thread](https://discourse.ubuntu.com/t/modern-communication-platforms-call-for-feedback/36763/), or in the {matrix}`matrix-ops` Matrix Ops room. This is where you can discuss issues or bugs, and where you can discuss the Ubuntu Matrix project in general.
+
+
+Known issues
+: The Element web client is not available on the Ubuntu Matrix instance yet. We will send updates once the Element web client is ready to test. You can use `app.element.io` or a Desktop client as noted in the instructions.
+

docs/community/contributors/matrix/matrix-ignore-list.md

@@ -0,0 +1,31 @@
+(matrix-ignore-list)=
+# Matrix ignore list
+
+Matrix has an "Ignore user" feature.
+This feature, when used, prevents a Matrix user from reaching you.
+Please note that this only affects you, and does not block the particular user for other people in your room or Homeserver. 
+
+
+## Add a Matrix user to your ignore list
+
+To ignore a user:
+
+* Select the avatar of the user you want to ignore from a chat room
+
+* A side panel opens on the right side of the Element client
+
+* In the {guilabel}`Options` category, select {guilabel}`Ignore`
+
+
+## Manage your ignore list
+
+To check your ignore list and manage the users on it:
+
+* Select your user avatar on the top left corner of your Element client
+
+* Select the option {guilabel}`Security & Privacy`
+
+* Scroll down to the {guilabel}`Advanced` section
+
+* Check the {guilabel}`Ignored Users` list
+

docs/community/contributors/matrix/matrix-spam.md

@@ -0,0 +1,71 @@
+(matrix-spam)=
+# Dealing with spam
+
+Matrix occasionally has spam waves.
+Sometimes, spammers target specific communities like the Ubuntu community.
+While the Ubuntu Matrix Operators work hard to block the spam before you even see it, they cannot (yet) catch everything.
+However, there are a few things you can do yourself to protect yourself.
+
+
+## Don't engage
+
+The most important rule is to **never engage directly with the spammers**!
+Spammers are trying to get your attention.
+They want you to get upset and want you to respond to them.
+Ignoring them is the best response.
+
+
+## Disable image previews
+
+Many Matrix clients like Element allow you to disable image previews.
+Since some spammers send disturbing images, it's best to turn image previews off.
+This way, you won't see these images before our moderator bot removes them.
+
+To turn image previews off in Element Desktop, select your profile picture in the top left corner of the app, click {guilabel}`All Settings` -> {guilabel}`Preferences`, and turn the following settings off:
+
+* {guilabel}`Autoplay GIFs`
+
+* {guilabel}`Autoplay videos`
+
+* {guilabel}`Show previews/thumbnails for images`
+
+
+## Block invites from banned users
+
+Sometimes, spam comes in the form of rogue invites to problematic rooms.
+By default, banned users can still send you invites, but Element has an experimental feature that allows you to block invites of everyone we ban.
+
+1. In Element Desktop, select your profile picture in the top left corner of the app, click {guilabel}`All Settings` -> {guilabel}`Labs`, and turn on {guilabel}`New ways to ignore people`.
+1. Then, go to {guilabel}`Ignored users` to the section {guilabel}`Subscribed lists` and add `!fTjMjIzNKEsFlUIiru:neko.dev`.
+   This is a community maintained list of spammers.
+
+
+## Ignore invites and users
+
+To avoid spam from rogue invites, you can also ignore the user.
+By doing this, that user will not be able to send you another invite.
+The method to ignore the user is different depending on which app you're using.
+
+* On Element Desktop and Element Web, click on the invite (but don't accept it), and click **{guilabel}`Reject & Ignore user`**.
+* If you're using Element Android, or another client, you need to type **`/ignore @user:example.com`** in the message box in a room and press {guilabel}`Send`.
+  Make sure to change the username in this command to the user inviting you.
+
+You can also ignore users that you are already in a room with you by clicking on the profile picture of the user and clicking {guilabel}`Ignore`.
+
+
+## Contact the Ubuntu Matrix Operators
+
+If you're targeted by spam, please let the Ubuntu Matrix Operators know in the {matrix}`Ubuntu Matrix Ops <matrix-ops>` room.
+We're constantly trying to improve our tooling to block the spam before you even see it.
+We're also working with other communities on Matrix to defend against spam together.
+However, if something slips through the cracks, please let us know.
+
+If you receive spam invites, it can help the Operators if you let us know (in the Matrix Ops room) what the full username and the room ID is of the spammers.
+Certain Matrix clients such as {spellexception}`Neochat` allow you to get a room ID without entering it.
+You can do that by right-clicking, choosing {guilabel}`Room Settings`, and copying the {guilabel}`Room ID`.
+
+
+## Contact your homeserver admins
+
+If you're using a `matrix.org` account, you can report spam invites by sending an email to `[email protected]`.
+

docs/community/contributors/matrix/multiple-accounts.md

@@ -0,0 +1,41 @@
+(matrix-multiple-accounts)=
+# Using multiple Matrix accounts
+
+The Element client does not support logging in with multiple concurrent accounts.
+However, the same result can be achieved indirectly, as outlined below.
+
+
+## Using the Element Desktop app
+
+1. **Install Element Desktop:**
+
+   Install via [snap](https://snapcraft.io/element-desktop) or [deb package](https://element.io/download).
+
+1. **Login with your first account:**
+
+   Start Element Desktop and log in with your first account.
+   This becomes the default login.
+
+1. **Open a second account:**
+
+   Open a console by pressing {kbd}`Ctrl` + {kbd}`Alt` + {kbd}`T`.
+
+   Run `element-desktop --profile <second-account>` -- this opens Element with your second account.
+   If you don't specify your second account, it defaults to the first account.
+
+You can manually start Element with the second account via the CLI, or you can create a Desktop launcher shortcut for it (instructions will vary depending on the Desktop environment you use).
+
+
+## Using Firefox and Element Web
+
+Firefox has a handy feature called ["Multi Account Containers"](https://addons.mozilla.org/en-US/firefox/addon/multi-account-containers/).
+Each container acts as a completely different browser with different accounts.
+If you open Element Web in two different containers, you can log into two accounts at the same time.
+
+
+## Mobile
+
+On mobile, the options are somewhat limited.
+While you can use Element Mobile alongside apps like [SchildiChat](https://schildi.chat/) or [FluffyChat](https://fluffychat.im/), they may not fully support all the features used by the Ubuntu Community, potentially impacting your experience.
+This will become better with time.
+

docs/community/contributors/matrix/onboarding.md

@@ -0,0 +1,57 @@
+(matrix-onboarding)=
+# Getting started with Matrix
+
+This guide will give you more information on how to collaborate with others in the Ubuntu Community using Matrix.
+Matrix is a form of real-time Internet chat, where you can talk to many other community members using Ubuntu, on topics ranging from idle chit-chat, over community improvements, to support with your Ubuntu installation.
+
+Though a channel might have many people in it at any one time, they might not always be at their keyboard; so if no-one responds, just wait around and someone will hopefully answer soon enough.
+
+
+(matrix-get-a-client)=
+## Get a client
+
+To connect to Matrix, you first need a "Client" app.
+**We strongly recommend using Element** since that is the only client that supports all the features used in our community.
+If you already have a Matrix client, you can continue to {ref}`matrix-get-an-account`.
+
+* [Element Web](https://app.element.io/) is the simplest option.
+  It works right inside your browser, so you don't need to install anything!
+
+* You can also install Element on every operating system.
+  On Ubuntu, you can install the [`element-desktop` snap](https://snapcraft.io/element-desktop).
+  For other operating systems, [download Element](https://element.io/download).
+
+
+(matrix-get-an-account)=
+## Get an account
+
+To participate in the conversation, you need to create a Matrix account.
+If you already have one, then you can continue to {ref}`matrix-join-the-ubuntu-space`.
+
+* Regular community members who need a new Matrix account can [register at `matrix.org`](https://matrix.org/docs/chat_basics/matrix-for-im/#creating-a-matrix-account) for free.
+  Alternatively, there are many [other providers](https://servers.joinmatrix.org/) you can choose that work in open federation.
+
+* If you're an [Ubuntu Member](https://ubuntu.com/community/membership) or work at Canonical, you can register an account {ref}`on the :ubuntu.com homeserver <matrix-register-ubuntu-com>`.
+
+
+(matrix-join-the-ubuntu-space)=
+## Join the Ubuntu space
+
+Once you have an account and a client you can join the Ubuntu Space by typing `/join #community:ubuntu.com`, or by {matrix}`following this link <community>`.
+Here you'll get an overview of the most relevant chat rooms in our community.
+
+
+## Follow the Code of Conduct
+
+When participating in the Ubuntu Community, including our Matrix channels, you agree to abide by the {ref}`Code of Conduct <code-of-conduct>`.
+
+If you have an unpleasant experience where someone else is violating the Code of Conduct, report the message using your client.
+In Element Web and Desktop, click on the three dots next to a message and select {guilabel}`Report`.
+Community Moderators will receive your report and take appropriate action.
+
+
+## Next steps
+
+Congratulations, by now you should be ready to chat with the Ubuntu community on Matrix.
+Once you have introduced yourself, check out {ref}`matrix-completing-setup`.
+