Add docs for #31 and #51 (#4421)

wiki/content/deploy/index.md

@@ -1429,6 +1429,49 @@ The server option `--tls_client_auth` accepts different values that change the s
 
 {{% notice "note" %}}REQUIREANDVERIFY is the most secure but also the most difficult to configure for remote clients. When using this value, the value of `--tls_server_name` is matched against the certificate SANs values and the connection host.{{% /notice %}}
 
+### Using Ratel UI with Client authentication
+
+Ratel UI (and any other JavaScript clients built on top of `dgraph-js-http`)
+connect to Dgraph servers via HTTP, when TLS is enabled servers begin to expect
+HTTPS requests only. Therefore some adjustments need to be made.
+
+If the `--tls_client_auth` option is set to `REQUEST` (default) or
+`VERIFYIFGIVEN`:
+1. Change the connection URL from `http://` to `https://` (e.g. `https://127.0.0.1:8080`).
+2. Install / make trusted the certificate of the Dgraph certificate authority `ca.crt`. Refer to the documentation of your OS / browser for instructions.
+(E.g. on Mac OS this means adding `ca.crt` to the KeyChain and making it trusted
+for `Secure Socket Layer`).
+
+For `REQUIREANY` and `REQUIREANDVERIFY` you need to follow the steps above and
+also need to install client certificate on your OS / browser:
+
+1. Generate a client certificate: `dgraph -c MyLaptop`.
+2. Convert it to a `.p12` file:
+`openssl pkcs12 -export -out MyLaptopCert.p12 -in tls/client.MyLaptop.crt -inkey tls/client.MyLaptop.key`. Use any password you like for export.
+3. Install the generated `MyLaptopCert.p12` file on the client system
+(on Mac OS this means simply double-click the file in Finder).
+4. Next time you use Ratel to connect to an alpha with Client authentication
+enabled the browser will prompt you for a client certificate to use. Select the
+certificate you've just installed in the step above and queries/mutations will
+succeed.
+
+### Troubleshooting Ratel's Client authentication
+
+If you are getting errors in Ratel when server's TLS is enabled try opening
+your alpha URL as a webpage.
+
+Assuming you are running Dgraph on your local machine, opening
+`https://localhost:8080/` in browser should produce a message `Dgraph browser is available for running separately using the dgraph-ratel binary`.
+
+In case you are getting a connection error, try not passing the
+`--tls_client_auth` flag when starting an alpha. If you are still getting an
+error, check that your hostname is correct and the port is open; then make sure
+that "Dgraph Root CA" certificate is installed and trusted correctly.
+
+After that, if things work without `--tls_client_auth` but stop working when
+`REQUIREANY` and `REQUIREANDVERIFY` is set make sure the `.p12` file is
+installed correctly.
+
 ## Cluster Checklist
 
 In setting up a cluster be sure the check the following.
@@ -1891,7 +1934,7 @@ This also works from a browser, provided the HTTP GET is being run from the same
 This triggers an export for all Alpha groups of the cluster. The data is exported from the following Dgraph instances:
 
 1. For the Alpha instance that receives the GET request, the group's export data is stored with this Alpha.
-2. For every other group, its group's export data is stored with the Alpha leader of that group. 
+2. For every other group, its group's export data is stored with the Alpha leader of that group.
 
 It is up to the user to retrieve the right export files from the Alphas in the
 cluster. Dgraph does not copy all files to the Alpha that initiated the export.