Add docs for federation (#1123)

_data/projects.yml

@@ -9,6 +9,7 @@
     Channels: channels/
     Messaging: messaging/
     Managing your Account: managing-your-account/
+    Talking to users from another server: talking-to-users-from-another-server/
 
 -
   name: Installation Guides
@@ -31,6 +32,7 @@
   pages:
     Account Settings: account-settings/
     Email: email/
+    Federation: federation/
     Permissions: permissions/
     Livechat: livechat/
     File Upload: file-upload/

_data/toc.yml

@@ -84,6 +84,7 @@
   - Connecting to a Server
   - Registration
   - Login
+  - Talking to users from another server
   - Channels
   - Messaging
   - Channel Actions
@@ -105,6 +106,7 @@
     - Editing Emails Content
     - Mailer
     - Direct Reply
+  - Federation
   - File Upload:
     - Amazon S3
     - Google Cloud Storage

administrator-guides/README.md

@@ -6,6 +6,7 @@ If you are a server administrator, here are a few guides on how to setup your in
 - [Authentication](authentication/)
 - [Database-Migration](database-migration/)
 - [Email](email/)
+- [Federation](federation/)
 - [File Upload](file-upload/)
 - [Import](import/)
 - [Integrations](integrations/)
@@ -16,4 +17,4 @@ If you are a server administrator, here are a few guides on how to setup your in
 - [Plug-ins](plug-ins/)
 - [Create the First Admin](create-the-first-admin/)
 - [Restoring an Admin](restoring-an-admin/)
-- [Managing Settings Via Environment Variables](settings-via-env-vars/)
+- [Managing Settings Via Environment Variables](settings-via-env-vars/)

administrator-guides/federation/README.md

@@ -0,0 +1,126 @@
+# Federation
+
+## Introduction
+
+Rocket.Chat Federation allows servers to communicate with each other, with no limits on the number of connected servers.
+
+We use industry standards, like DNS records, keeping the process as seamless as possible, seeking the most hassle-free communication between servers.
+
+When enabling federation on your server, your server becames part of the Rocket.Chat Federated Network, which allows it to find and exchange messages and files with other Federation enabled Rocket.Chat servers.
+
+## Features
+
+- **Current**
+    - Inviting users from remote servers;
+    - Direct chats between servers;
+    - Public, private and broadcast rooms with remote users from any number of servers;
+    - Read receipts, notifications and alerts are distributed to remote servers;
+    - Mute/Unmute remote users;
+    - File sharing among servers;
+- **Confirmed next features**
+    - Encrypted rooms;
+    - Whitelist servers to communicate with;
+    - Better federation setup process, with helpers to validate the configuration;
+
+## Configuration
+
+When you open Federation's config screen, you will see this:
+
+![Initial Federation Screen](./initial.png)
+
+Below, a brief explanation of each configuration option:
+
+### Enabled
+
+This determines whether or not Federation is enabled on this server.
+
+### Status
+
+This is the current Federation status, which can be one of the following:
+
+- **Could not enable, settings are not fully set :** Make sure all the options are correctly filled and saved;
+- **Booting... :** federation is initializing;
+- _[HUB Only]_ **Registering with Hub... :** federation is trying to register with the Hub;
+- _[HUB Only]_ **Disabled, could not register with Hub :** federation could not register with the Hub;
+- **Disabled :** federation is disabled
+- **Running :** federation is running and ready to communicate with other servers;
+
+### Domain
+
+Fill this option with your domain name, usually where the Rocket.Chat server is hosted.
+
+### Public Key
+
+All Federation communications are double encrypted, which means messages cannot be delivered by mistake to a wrong peer. This is your public key, which is specially generated for Rocket.Chat and by Rocket.Chat, which will be shared with peers you are communicating with.
+
+The encryption process encrypts the message using the Server A private key, and the Server B public key.
+
+When a server receives the message, it uses the Server B private key and the Server A public key to decrypt it.
+
+So, let's say the message ended up on Server C: this server won't have Server B's private key to decrypt it, so the message can't be read at all.
+
+### Hub URL
+
+This usually remains as is. This is the Hub URL, where your server will register and confirm domain ownership if you are not using DNS discovery method.
+
+### Discovery Method
+
+How are you going to be found in the Rocket.Chat Federated Network? You can choose through DNS or, as a fallback, the Rocket.Chat Hub.
+
+**Important:** We recommend using the DNS method. The Hub is a tool to allow users to easily adopt, try and validate the feature or as a different way to be part of the Rocket.Chat Federated Network until DNS record changes are made. Also, the Hub requires external communication and access to a specific e-mail address owned by your domain, as explained below, which introduces extra configuration steps in some protected internal networks.
+
+## Adding Federation to your server
+
+You have two ways of adding your server to the Rocket.Chat Federated Network:
+
+### Recommended: Configuring your DNS
+
+To add your server to the Federated Network using the DNS, fill all the needed configuration fields (making sure you are picking **true** on the _Enabled_ field), pick the `DNS` _Discovery Method_ option, save and follow the guide below.
+
+Let's suppose we have a domain named `mydomain.com`, and my Rocket.Chat server is hosted at `chat.mydomain.com`, port `80`.
+
+You'll have to add two DNS records:
+
+#### SRV Record
+
+- Service: `_rocketchat`
+- Protocol: `_tcp`
+- Name: `mydomain.com`
+- Weight: `1`
+- Priority: `1`
+- TTL: `1 hour`
+- Target: `chat.mydomain.com`
+- Port: `80`
+
+In Amazon Route 53 it would look something like this:
+![image](https://user-images.githubusercontent.com/51996/53998274-c1496c80-4104-11e9-8571-3288fc7b2cc8.png)
+
+#### TXT Record
+
+- Host: `rocketchat-public-key.mydomain.com`
+- Value: `<my public key, as shown on the configuration screen>`
+
+When both of those entries are added to the DNS records, you should be able to be found by other peers after the propagation.
+
+NOTE: Some DNS providers won't allow the full public key string to be entered so, after saving, we recommend making sure the string is complete, starting as `-----BEGIN PUBLIC KEY-----` and ending as `-----END PUBLIC KEY-----`. If that is not the case, follow your provider's instructions. For example, AWS's Route 53 needs the string to be split in two pieces, like this:
+
+```
+"-----BEGIN PUBLIC KEY-----...."
+"...-----END PUBLIC KEY-----"
+```
+
+### Alternative: registering on Hub
+
+To add your server to the Federated Network using the Hub, fill all the needed configuration fields (making sure you are picking **true** on the _Enabled_ field), pick the `Hub` _Discovery Method_ option, save and follow the guide below.
+
+#### Confirm domain ownership
+
+When you click `Save` on the federation config screen, you will begin the registration process. This process takes a few seconds and if you are not yet registered to the Hub, you should receive an email at `webmaster@mydomain.com`, where `mydomain.com` is the domain address you configured on the `Domain` field.
+
+Make sure the data is correct and confirm the changes.
+
+After that step, you should be able to be found on the Rocket.Chat Federated Network.
+
+## Using Rocket.Chat Federation
+
+Click [here](../../user-guides/talking-to-users-from-another-server/) to learn how to use Rocket.Chat federation.

user-guides/README.md

@@ -7,6 +7,7 @@ Here you'll learn how to use [Rocket.Chat](https://rocket.chat/) as a user.
 - [Connecting to a server](connecting-to-a-server/)
 - [Registration](registration/)
 - [Login](login/)
+- [Talking to users from another server](talking-to-users-from-another-server/)
 - [Using Channels](channels/)
 - [Messaging](messaging/)
 - [Channel Actions](channel-actions/)

user-guides/talking-to-users-from-another-server/README.md

@@ -0,0 +1,32 @@
+# Talking to users from another server
+
+Once you have [added your server to the Federated Network](../../administrator-guides/federation) you can talk to users from server who have done the same.
+
+## Using Rocket.Chat Federation
+
+After enabling federation, you should be able to start chatting with other servers.
+
+## Inviting users from a different server
+
+To do so, you should go to the `Directory` section, `Users` tab, and pick `Every Workspace` from the dropdown menu.
+
+![Directory Search Users](./directory.png)
+
+Then, you should be able to look for users on remote servers, called peers. You can search using a combination of a username and a domain or an e-mail address, like:
+
+- Username: `myfriendsusername@anotherdomain.com`
+- E-mail address: `joseph@remotedomain.com`
+
+If the remote server is within Rocket.Chat Federated Network, you will be able to see the users:
+
+![Directory Search Result](./directory-result.png)
+
+## Inviting remote users and chatting
+
+If you click on one of those listed users, you will invite them to your server without login access. Also, you and everyone else on your server will be able to chat with that new remote user.
+
+![Chat](./chat.png)
+
+From now on, you can invite that user to any other room, public or private. Those channels are going to be replicated to the remote server, without the messages history.
+
+As a reminder, if you invite a remote user to a public channel, this channel will be created as private on the remote server, so you can be sure only invited users will be able to see that channel content.