Add guide for configuring ssl

articles/editor/export-files.md

@@ -6,7 +6,7 @@
 
 You can export any files in Stoplight to use as you see fit. Exported files are served up in a unique domain in its raw format. Current exported file formats include: 
 
-### JSON
+### YAML
 - Documentation 
 - Modeling 
 - Testing 

articles/enterprise/components/api.md

@@ -20,6 +20,18 @@ 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
+>
+> If websockets are not supported within your environment, clients will revert
+> to HTTP polling.
 
 > #### Component Dependencies
 >
@@ -156,6 +168,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.

articles/enterprise/components/gitlab.md

@@ -29,7 +29,7 @@ Redis).
 >
 > GitLab must be able to receive incoming connections from the following components:
 >
-> * App
+> * API
 >
 > GitLab must be able to make outgoing connections to the following components:
 >
@@ -106,11 +106,111 @@ 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).
+
+```ruby
+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.
+
+##### ssl
+
+To enable SSL, update the `external_url` setting with a `https://` prefix, which
+will enable SSL connections over port 443. Once updated, set the certificate and
+private key locations using the following configuration:
+
+```ruby
+nginx['ssl_certificate'] = "/etc/gitlab/ssl/gitlab.example.com.crt"
+nginx['ssl_certificate_key'] = "/etc/gitlab/ssl/gitlab.example.com.key"
+```
+
+If you would like to _only_ serve requests over HTTPS, use the following
+configuration:
+
+```ruby
+nginx['redirect_http_to_https'] = true
+```
+
+##### postgresql
+
+To configure GitLab to use an external database (ie, the database _not_ embedded
+within the GitLab package), use the following configuration:
+
+```ruby
+postgresql['enable'] = false
+gitlab_rails['db_database'] = "stoplight"
+gitlab_rails['db_username'] = "dbuser"
+gitlab_rails['db_password'] = "dbpassword"
+gitlab_rails['db_host'] = "postgres.example.com"
+gitlab_rails['db_port'] = 5432
+gitlab_rails['db_sslmode'] = "allow"
+```
+
+##### redis
+
+To configure GitLab to use an external redis (ie, the redis instance _not_
+embedded within the GitLab package), use the following configuration:
+
+```ruby
+redis['enable'] = false
+gitlab_rails['redis_host'] = "HOST"
+gitlab_rails['redis_port'] = PORT
+gitlab_rails['redis_database'] = "stoplight"
+redis['maxclients'] = "10"
+```
+
+##### email
+
+To configure email, update the GitLab configuration with the following entries:
+
+```ruby
+gitlab_rails['gitlab_email_enabled'] = true
+gitlab_rails['gitlab_email_from'] = 'email-from@example.com'
+gitlab_rails['gitlab_email_display_name'] = 'Stoplight'
+gitlab_rails['gitlab_email_reply_to'] = 'email-reply@example.com'
+```
+
+> If you would like for your Stoplight instance to send emails, be sure to
+> update the SMTP settings below in addition to the email settings.
+
+##### smtp
+
+To configure SMTP to enable email notifications, update the GitLab configuration
+with the following entries:
+
+```ruby
+gitlab_rails['smtp_enable'] = true
+gitlab_rails['smtp_address'] = "smtp.example.com"
+gitlab_rails['smtp_port'] = 25
+gitlab_rails['smtp_domain'] = "smtp.example.com"
+```
+
+If the SMTP server requires authentication:
+
+```ruby
+gitlab_rails['smtp_user_name'] = "USER"
+gitlab_rails['smtp_password'] = "PASSWORD"
+gitlab_rails['smtp_authentication'] = "login"
+gitlab_rails['smtp_enable_starttls_auto'] = true
+```
+
+If the SMTP server requires TLS:
+
+```ruby
+gitlab_rails['smtp_tls'] = true
+```
+
 #### Starting the Service
 
 To start GitLab for the first time, run the commands:
@@ -213,3 +313,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

articles/enterprise/components/prism.md

@@ -141,18 +141,6 @@ MAX_QUEUE_SIZE=500
 > `MAX_QUEUE_SIZE` should be left as `500` unless instructed otherwise by the
 > Stoplight Support staff.
 
-#### MAX_RUNTIME_POOL_SIZE
-
-The `MAX_RUNTIME_POOL_SIZE` variable denotes the worker pool size used to
-service requests.
-
-```
-MAX_RUNTIME_POOL_SIZE=15
-```
-
-> `MAX_RUNTIME_POOL_SIZE` should be left as `15` unless instructed otherwise by
-> the Stoplight Support staff.
-
 #### MAX_WORKERS
 
 The `MAX_WORKERS` variable denotes the number of worker threads to use when

articles/enterprise/components/tasker.md

@@ -89,7 +89,7 @@ The `TASKER_HTTP_BIND` variable is the bind address and port used for serving
 the Tasker HTTP API.
 
 ```
-TASKER_HTTP_BIND="localhost:9432"
+TASKER_HTTP_BIND="0.0.0.0:9432"
 ```
 
 #### TASKER_MODE
@@ -103,13 +103,13 @@ TASKER_MODE="shell"
 
 > If not specified, Tasker defaults to using `docker` mode.
 
-#### CORE_ROOT
+#### HUB_BUILDER_ROOT
 
-The `CORE_ROOT` denotes the absolute path to the stoplight-hub-builder package
-root.
+The `HUB_BUILDER_ROOT` denotes the absolute path to the stoplight-hub-builder
+package root.
 
 ```
-CORE_ROOT="/opt/stoplight-hub-builder"
+HUB_BUILDER_ROOT="/opt/stoplight-hub-builder"
 ```
 
 > This variable is only required when running in `shell` mode.

articles/enterprise/guides/configuring-ssl.md

@@ -0,0 +1,154 @@
+# Configuring SSL
+
+This guide covers how to protect network communication for the Stoplight
+platform using SSL.
+
+## Prerequisites
+
+In order to configure the Stoplight platform to use SSL, you will need:
+
+* A method for generating (one or many) SSL private keys and certificates for
+  each component.
+* A method for having the certificates above signed by a trusted [Certificate
+  Authority](https://en.wikipedia.org/wiki/Certificate_authority) (or CA),
+  either internal or external to your organization.
+* If you are using self-signed certificates or certificates signed by an
+  internal CA, you will need a method for establishing trust on the component
+  and client systems.
+
+> Please note, this guide _does not_ cover the details of creating, signing, or
+> establishing trust of certificates on component or client systems. If you are
+> unsure of how to perform any of the prerequisite items, please consult with
+> your internal IT team.
+
+## Components
+
+The method for configuring SSL varies by component. Please see the component
+sections below to get started.
+
+### App, API, Exporter, Prism, Tasker
+
+In order to configure SSL for the **App**, **API**, **Exporter**, **Prism**, and
+**Tasker** components, you must use a [reverse
+proxy](https://en.wikipedia.org/wiki/Reverse_proxy) for HTTPS/SSL termination.
+This means that the component itself will not communicate over SSL, but a proxy
+sitting in front of the component will. For more information on SSL termination,
+please see [here](https://en.wikipedia.org/wiki/TLS_termination_proxy).
+
+If you do not already have a reverse proxy application chosen, Stoplight uses
+and recommends [NGINX](http://nginx.org/). See the section below for an example
+configuration.
+
+#### Configuring NGINX
+
+To configure NGINX to use SSL, Stoplight recommends using the following
+configuration:
+
+```nginx
+server {
+    # optional, but required if serving multiple components from same proxy
+    server_name component.example.com;
+    server_tokens off;
+
+    listen 443 ssl http2 default_server;
+
+    ssl on;
+    # customize pased on local filesystem
+    ssl_certificate     /path/to/ssl/cert;
+    ssl_certificate_key /path/to/ssl/key;
+
+    ssl_session_cache         shared:SSL:20m;
+    ssl_session_timeout       60m;
+    ssl_protocols             TLSv1 TLSv1.1 TLSv1.2;
+    ssl_prefer_server_ciphers on;
+    ssl_ciphers               ECDH+AESGCM:ECDH+AES256:ECDH+AES128:DH+3DES:!ADH:!AECDH:!MD5;
+    add_header                Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
+
+    location / {
+        # customize the port and IP per component being served
+        proxy_pass http://127.0.0.1:PORT;
+
+        client_max_body_size 0;
+        gzip off;
+        proxy_http_version 1.1;
+        proxy_read_timeout 300;
+        proxy_connect_timeout 300;
+        proxy_redirect off;
+
+        proxy_set_header    Upgrade $http_upgrade;
+        proxy_set_header    Connection "upgrade";
+        proxy_set_header    Host                $http_host;
+        proxy_set_header    X-Real-IP           $remote_addr;
+        proxy_set_header    X-Forwarded-Ssl     on;
+        proxy_set_header    X-Forwarded-For     $proxy_add_x_forwarded_for;
+        proxy_set_header    X-Forwarded-Proto   $scheme;
+        proxy_set_header    X-Frame-Options     SAMEORIGIN;
+    }
+
+}
+```
+
+To automatically redirect HTTP to HTTPS, add the following section to the nginx
+configuration:
+
+```nginx
+server {
+    # optional, but required if serving multiple components from same proxy
+    server_name              component.example.com;
+    server_tokens off;
+
+    listen                   80;
+    listen                   [::]:80;
+
+    return                   301 https://$server_name$request_uri;
+}
+```
+
+### Pubs
+
+To configure the Pubs component to use HTTPS, update the configuration with
+following entries:
+
+```yaml
+# Whether to enable SSL when serving admin API (protecting communication
+# between the API and Pubs)
+admin_ssl_enabled: yes
+admin_ssl_cert_path: "/path/to/ssl/cert"
+admin_ssl_key_path: "/path/to/ssl/key"
+
+# Whether to enable SSL when serving published docs
+ssl_enabled: yes
+https_bind: "0.0.0.0:443"
+static_ssl_domains:
+  # must match the any domains docs are published under. can specify many.
+  - domain: "*.docs.example.com"
+    cert-path: "/path/to/docs.example.com/certificate"
+    key-path: "/path/to/docs.example.com/key"
+```
+
+> Remember to update the path elements above to match the filesystem path to the
+> SSL keys and certificates
+
+All SSL certificates must match the hostnames (ie, domain names) they are served
+from.
+
+### GitLab
+
+Configuring GitLab to use SSL varies depending on the installation type. Please
+see below for more information.
+
+> If you are unsure of your installation type, please contact [Stoplight
+> Support](mailto:support@stoplight.io) for assistance.
+
+#### Omnibus Installations (default)
+
+For Omnibus installations, please see the official GitLab documentation below:
+
+* [Configuring the embedded NGINX process to use SSL](https://docs.gitlab.com/omnibus/settings/nginx.html)
+
+* [General information on how GitLab SSL settings work](https://docs.gitlab.com/omnibus/settings/ssl.html)
+
+#### From-Source Installations
+
+For from-source installations, please see
+[here](https://github.com/stoplightio/docker-gitlab#ssl).

articles/getting-started/permissions-overview.md

@@ -2,7 +2,7 @@
 
 ## Organizations 
 
-| **Organization Actions**        | **Reader** | **Contributor** | **Administrator** | **Owner** |
+| **Organization Actions**        | **Reader** | **Creator** | **Administrator** | **Owner** |
 |---------------------------------|:----------:|:-----------:|:-----------------:|:---------:|
 | Read Public Projects            |     X     |      X     |         X         |     X     |
 | View Organization Collaborators |           |      X     |         X         |     X     |

articles/hubs/auth0-integration.md

@@ -1,48 +0,0 @@
-# Auth0 Integration 
-
-## What 
-Auth0 allows you to add a login form with user access management to your documentation. 
-
-## How 
-1. Create an account or login to [Auth0](https://auth0.com/)
-2. Select **Applications** in the Auth0 menu
-
-![Auth0 Dashboard](https://github.com/stoplightio/docs/blob/develop/assets/images/auth0-dashboard.png?raw=true)
-
-3. Click **+ Create Application**
-
-![Create Application](https://github.com/stoplightio/docs/blob/develop/assets/images/create-application.png?raw=true)
-
-4. Input a **Name** for your application
-
-![Create Application Details](https://github.com/stoplightio/docs/blob/develop/assets/images/application-create.png?raw=true)
-
-5. Select **Regular Web Applications**
-6. Click **Create** 
-7. Select **Application Settings**
-
-![Auth0 Settings](https://github.com/stoplightio/docs/blob/develop/assets/images/auth0-new-settings.png?raw=true)
-
-8. Copy the **Domain** and paste it in **Hosted Login Page** 
-9. Input a **?client=** at the end of the pasted **Domain** from above 
-10. Copy the **Client ID** and paste it after the **?client=** in  **Hosted Login Page** from above 
-
-> Example Hosted Login Page: robertwallach.auth0.com?client=XwYWVMLp7rJOkJ6iU51MwJHm2w2AAfGl
-
-11. Copy the **Client Secret** and paste it in **Client Secrets** in Hubs 
-
-![Hubs Authorizations](https://github.com/stoplightio/docs/blob/develop/assets/images/hubs-authorization.png?raw=true)
-
-12. Copy the **Callback URL** generated by Hubs in **Authorizations** and paste it in **Allowed Callback URLs** in Auth0
-
-> Make sure the callbacks start with https instead of http and that they match 
-
-![Allowed Callback URL](https://github.com/stoplightio/docs/blob/develop/assets/images/callback-urls.png?raw=true)
-
-13. Select **Hosted Pages** in the Auth0 menu 
-
->  Make sure **Customize Login Page** is turned on 
-
-14. Click on **Build** to start the Publishing process 
-
-> To login to your Hub with Auth0, make sure you add users in the Auth0 Dashboard 

articles/hubs/export-static-html.md

@@ -4,25 +4,18 @@
 
 > Requires a Pro Docs plan 
 
-## What?
-If you would rather host your documentation outside of Stoplight's hosted servers, you can download a built version of your Hub. Downloading a build will produce a `.zip` containing all of the minified assets necessary to load your Hub. These assets will include HTML, JavaScript, CSS, and JSON files. You will need an HTTP File Server in order to properly view and navigate your downloaded Hub. Any authorizations (Auth0, SAML, etc) you have added will not work, since they require a backend server.
+## What 
+If you would rather host your documentation outside of Stoplight's hosted servers, you can download a built version of your Hub. Downloading a build will produce a `.zip` containing all of the minified assets necessary to load your Hub. These assets will include HTML, JAvascript, CSS, and JSON files. 
 
-## How to download
+## How to Download
 1. Click the **Publish** icon on the far left toolbar 
 2. Select or create a **domain**
-3. Choose a **Hub** or **OAS** file
-4. Click the **Build** button to start the build process
+3. Choose a **Hub** or **OAS** file to create a build from 
+4. Click the **Build** button to start the build process. 
 
-> If this is your first build, it will also publish to your selected domain
-
-5. Once your **Hub** has finished building, it will appear in the **Builds** section. Click the download icon to the right of the build
-6. Unzip the downloaded `.zip` to view all of the assets. It will most likely be located in your Downloads folder
-
-## How to serve locally on your computer (Mac)
-1. Open Terminal and `cd` into the root of your build folder
-2. Start your favorite file server (Ex. `python -m SimpleHTTPServer`)
-3. Open a web browser and navigate to the file server's local url (Ex `http://localhost:3000`)
+> If this is your first build, it will also publish to your selected domain 
 
+5. Once your **Hub** has finished building, it will appear in the **Builds** section. Click the download icon to the right of the build 
 ---
 **Related Articles**
 - [Documentation with Hubs](/documentation/introduction)

articles/hubs/oauth.md

@@ -1,10 +1,10 @@
-# OAuth 2.0
+# OAuth for Hubs 
 
 ## What 
 
 OAuth provides a level of security to your documentation to restrict access to it. If your API is protected by OAuth, you will need to enable it for Try It Out. Enabling OAuth for Try It Out can be accomplished through two different methods: via Modeling or directly into the Hubs code.
 
-> OAuth 2.0 works explicitly for accessCode workflow 
+> Stoplight supports OAuth 1.0 and 2.0 
 
 ## How 
 

articles/hubs/ref-other-sources-hubs.md

@@ -17,10 +17,12 @@ Hubs allows you to reference other sources to automatically populate your Hub wi
 
 1. Select the Hub you wish to modify 
 2. Select **Design** view
-3. Select the **page** or **subpage** you wish to power
-4. Under Page Type, select **Markdown**(for markdown files) or **OpenAPI** (for JSON or YAML files)
-5. Input the specific data source or select from the drop-down menu
-6. Click **Confirm**  
+3. Click on **Page Settings & TOC** at the top of the page
+    1. Select the **page** or **subpage** you wish to power
+    2. Under Page Type, select **Markdown**(for markdown files) or **OpenAPI** (for JSON or YAML files)
+    3. Input the specific data source or select from the drop-down menu
+    4. Input an inner data source (optional)  
+4. Click **Confirm**  
 
 >Try it Out! Power a Subpage with an API Spec from the same project.
 

articles/modeling/grouping-tagging.md

@@ -1,16 +0,0 @@
-# Grouping & Tagging Endpoints in OpenAPI
-
-![Tagging and Grouping Endpoints](https://github.com/stoplightio/docs/blob/develop/assets/gifs/modeling-tagging.gif?raw=true)
-
-## What
-
-Use tags to group API endpoints and provide an additional layer of organization in your OpenAPI files. When rendering your OpenAPI in read view, Stoplight will group API endpoints by their first tag.
-
-## How
-
-1. Click **Tag** in the top Modeling toolbar 
-2. Input a **Name** 
-3. Input a **Tag description** (optional) 
-4. Select the endpoint you want to tag 
-5. Open the **tags** dropdown, and select the tag that you just created
-6. Switch to read view and you should see the endpoint grouped under that tag in the sidebar

articles/organizations/managing-people.md

@@ -20,13 +20,13 @@ Adding people to your Organization is the first step towards collaboration withi
 
 ### Magic Link 
 
-> Magic Link grants either Contributor or Reader Permissions. Set accordingly 
+> Magic Link grants either Creator or Reader Permissions. Set accordingly 
 
 #### Generating and Sending Magic Link 
 1. Select the **Organization** you wish to invite people to 
 2. Select the **People** tab 
 3. Click **Invite Member**
-4. Select a role, either **Contributor** or **Reader**
+4. Select a role, either **Creator** or **Reader**
 5. Click **Generate Link**
 6. Send link to invitee 
 
@@ -34,7 +34,7 @@ Adding people to your Organization is the first step towards collaboration withi
 1. Click on the **magic link** 
 2. If new to Stoplight, click **Register**
 3. If you already have an account, **Login** 
-4. You now have Contributor or Reader access to that Organization 
+4. You now have Creator or Reader access to that Organization 
 
 ---
 **Related Articles**

articles/organizations/roles.md

@@ -10,7 +10,7 @@ Roles and Permissions for members of Organizations can be managed and modified w
         * Has access to Billing and Organization Settings
     * **Administrator** 
         * Admins can update the org, its connections, and its members 
-    * **Contributor** 
+    * **Creator** 
          * Creators can update the org and its connections. They can view its members 
 
 ## Who