Add guide for configuring ssl

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).