Add guide for configuring ssl

* Create export-static-html.md

* Update export-static-html.md

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/hubs/export-static-html.md

@@ -0,0 +1,31 @@
+# Download Static HTML & CSS
+
+![Download Static HTML and CSS](https://github.com/stoplightio/docs/blob/develop/assets/gifs/export-static-html.gif?raw=true)
+
+> 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. 
+
+## 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 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 
+---
+**Related Articles**
+- [Documentation with Hubs](/documentation/introduction)
+- [Routing](/documentation/getting-started/routing)
+- [Headers](/documentation/getting-started/header-footer)
+- [Pages](/documentation/getting-started/pages)
+- [Subpages](/documentation/getting-started/subpages)
+- [Blocks](/documentation/blocks)
+- [Referencing Other Data Sources](/documentation/referencing-other-data-sources)
+- [Publishing](/documentation/publishing)
+- [Theming](/documentation/design/theming)
+- [Custom CSS](/documentation/design/custom-css)
+

changelog-4-25-18.md

@@ -1,15 +1,19 @@
-# Stoplight v4.1.0 — Fair Use Billing, Magic Links, Custom CSS, Landing Pages, Token Generation
-The first major update to Stoplight Next is live! We’ve been hard at work building out a bunch of new exciting features based on all your invaluable feedback. Now let’s dig in!
+# Stoplight v4.1.0 Release
+
+This update includes fair use billing, magic links, custom css, and more.
 
 ## New 🚀
-- **[Fair Use Billing](https://docs.stoplight.io/platform/getting-started/billing)**: We instituted a fair use billing policy because we wanted our users to only pay for what they use. This means that you will only pay for the users actively contributing on your account in any given 30 day billing cycle. Unleash your Engineers! 
-- **Annual Billing**: We enabled a year long billing option that helps you save up to 20%. 
-- **[Magic Invite Links](https://docs.stoplight.io/platform/organizations/invite-people)**: Invite people to your Organization or Project simply by generating a link and sending it. Abra Kadabra. 
+
+- **[Fair Use Billing](https://docs.stoplight.io/platform/getting-started/billing)**: Our paid plans now only count active members that have created a project or updated project files in the past 30 days. This better aligns cost to value, and results in a lower bill in all cases. Now your members will only be added to your bill if and when they start creating content on Stoplight. Unleash your Engineers! 
+- **Annual Billing**: Save up to 20%.
+- **[Magic Invite Links](https://docs.stoplight.io/platform/organizations/invite-people)**: Share it via email, Slack, and other channels to easily onboard members in your organization. Fair use billing means they won’t count until they actually start creating content. Abra Kadabra. 
 - **[Custom CSS](https://docs.stoplight.io/documentation/design/custom-css)**: Add some custom style and flair to your documentation with Custom CSS. 
 - **Custom HTML Landing Pages**: Create beautiful custom landing pages to greet and direct your users. 
-- **[OAuth2 Token Generation in Hub’s Try it Out](https://docs.stoplight.io/documentation/oauth-hubs)**: If your API is protected by OAuth2, you can now generate tokens to enable Try it Out. 
+- **[OAuth2 Token Generation in Hub’s Try it Out](https://docs.stoplight.io/documentation/oauth-hubs)**: If your API is protected by OAuth2, you can now generate tokens in the Try it Out block.
 
 ## Enhancements 💪
-- **IE 11 Support for Published Hubs**: IE 11 now renders documentation created in Hubs. 
+
+- **Relative $refs**: References from one file to another in the same project are now represented with relative URLs. For example, `./models/user.json` instead of `https://exporter.stoplight.io/45/master/models/user.json`. This has a number of benefits, such as increased portability. It also sets the stage for better desktop local file editing and versioning.
+- **Published hubs now support Internet Explorer 11**
 
 Please reach out via chat or support@stoplight.io if you have any questions about the above changes.