From 6d8c85030370a96d5fa5a703976ab17fffb0441b Mon Sep 17 00:00:00 2001
From: Ross McDonald <ross@stoplight.io>
Date: Thu, 3 May 2018 14:50:41 -0500
Subject: [PATCH] Update api and gitlab component articles

---
 articles/enterprise/components/api.md    | 14 +++++++++
 articles/enterprise/components/gitlab.md | 36 +++++++++++++++++++++++-
 2 files changed, 49 insertions(+), 1 deletion(-)

diff --git a/articles/enterprise/components/api.md b/articles/enterprise/components/api.md
index 90ed2ca..54d938d 100644
--- a/articles/enterprise/components/api.md
+++ b/articles/enterprise/components/api.md
@@ -20,6 +20,15 @@ datastore and other miscellaneous Stoplight services.
 > * Gitlab
 > * Exporter
 > * Prism
+>
+> In addition, the API makes use of
+> [websocket](https://en.wikipedia.org/wiki/WebSocket) connections for real-time
+> notifications and updates to application users. In particular, websockets are
+> used for:
+>
+> * Displaying editor notifications when multiple users are editing the same file
+> * Displaying build logs while a Hub or spec is being built
+> * Displaying notifications for when a Hub or spec build is completed
 
 > #### Component Dependencies
 >
@@ -156,6 +165,11 @@ SL_COOKIE_DOMAIN="example.com"
 For example, if Stoplight is being served from the `stoplight.example.com`
 domain, set this variable to `example.com`.
 
+> This setting is used for
+> [CORS](https://en.wikipedia.org/wiki/Cross-origin_resource_sharing)
+> verification. If you are unable to make requests to the API from the app, then
+> this is most likely the cause.
+
 #### SL_APP_HOST
 
 The `SL_APP_HOST` variable is the full URL to the Stoplight app component.
diff --git a/articles/enterprise/components/gitlab.md b/articles/enterprise/components/gitlab.md
index d0f0ecc..9449373 100644
--- a/articles/enterprise/components/gitlab.md
+++ b/articles/enterprise/components/gitlab.md
@@ -106,11 +106,24 @@ The Stoplight GitLab configuration is located at:
 /etc/gitlab/gitlab.rb
 ```
 
-The above file encompasses all of the different configuration options exposed by GitLab. This guide only covers those specific to Stoplight.
+The above file encompasses all of the different configuration options exposed by
+GitLab. This guide only covers those specific to Stoplight.
 
 > For documentation on other GitLab configuration options, see the official
 > documentation [here](https://docs.gitlab.com/omnibus/README.html#configuring)
 
+##### external_url
+
+`external_url` is the canonical URL for the Gitlab instance (scheme, hostname,
+and port included).
+
+```
+external_url 'http://stoplight.example.com:8080'
+```
+
+> If you are configuring GitLab to send emails, set the `external_url` to the
+> URL of the **Stoplight App** component, and not GitLab itself.
+
 #### Starting the Service
 
 To start GitLab for the first time, run the commands:
@@ -213,3 +226,24 @@ Once the configuration changes are made, issue a `gitlab-ctl reconfigure` for th
 
 For more information on configuring Redis, see the official GitLab documentation
 [here](https://docs.gitlab.com/omnibus/settings/redis.html).
+
+#### Can I specify GitLab users as administrators?
+
+Yes, GitLab administrators can be selected by editing the user you would like to
+assign as an admin. Administrative rights can be set under the "Access" section
+of the user modification screen in GitLab.
+
+> Please note, GitLab administrators have administrative rights in Stoplight as
+> well. Administrators can see and edit all projects hosted within Stoplight.
+
+#### Can I allow users created in GitLab to have access to Stoplight?
+
+Yes, in order for a GitLab-created user to have access to the Stoplight
+platform, an impersonation token must be created for their account. The
+impersonation token management screen can be found in the user administration
+screen, under the "Impersonation Tokens" tab.
+
+To create a Stoplight access token, make sure:
+
+* The name of the token is equal to `stoplight`
+* The token must have `api` scope