TerribleDev/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add enterprise docs

Browse Source
This commit is contained in:
Ross McDonald
2018-04-10 17:23:17 -05:00
parent b1149e0b7b
commit a0f661ecad
13 changed files with 1816 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

39
articles/enterprise/authentication/saml.md Normal file
View File

@@ -0,0 +1,39 @@
To configure Stoplight Enterprise to use SAML for user authentication, add the following variable to the Stoplight API configuration or environment:
```bash
SL_SSO_ENTRYPOINT="https://your-saml-server.example.com/..."
```
Where `SL_SSO_ENTRYPOINT` is the full URL to the SAML server providing the SAML assertions.
Once set in the API configuration, restart the API:
```bash
# docker installs
sudo docker restart stoplight-api
# package installs
sudo systemctl restart stoplight-api
```
Once restarted, all login requests will be authenticated via the external SAML service.
> Please note, Stoplight's SAML integration does not currently use SAML assertions for determining group/organization membership. Group/organization membership should be managed through the Stoplight application itself.
### SAML IdP Metadata
To configure Stoplight SAML integration from the SAML server, use the following SAML metadata file:
```xml
<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:ds="http://www.w3.org/2000/09/xmldsig#" entityID="stoplight" ID="stoplight">
<SPSSODescriptor protocolSupportEnumeration="urn:oasis:names:tc:SAML:2.0:protocol">
<NameIDFormat>
urn:oasis:names:tc:SAML:2.0:nameid-format:persistent
</NameIDFormat>
<AssertionConsumerService index="1" isDefault="true" Binding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST" Location="https://stoplight-api.internal.example.com/sso/global/saml/callback"/>
</SPSSODescriptor>
</EntityDescriptor>
```
Be sure to update the `AssertionConsumerService` / `Location` object with the correct callback URL for the Stoplight API.

226
articles/enterprise/components/api-overview.md Normal file
View File

@@ -0,0 +1,226 @@
# The Stoplight API
The __API__ component powers the Stoplight backend, connecting the UI to the datastore and other miscellaneous Stoplight services.
> #### Networking Details
>
> The default port for the API component is TCP port __3030__. The port can be customized using the `PORT` environment variable.
>
> Be sure that the Gitlab component is available __before__ starting the API service.
## Installation
The Stoplight API can be installed with Docker or via RPM package.
> Before starting, be sure to complete the Gitlab installation.
### RPM Package
Prior to installing the RPM package, you will need to:
* Install NodeJS
* Have the Stoplight package repository installed and configured with your user-specific credentials
#### Installing NodeJS
To install NodeJS, please run the following commands:
```bash
# make sure all current versions of nodejs are removed
sudo yum remove nodejs npm -y
# install nodejs
sudo rpm -Uvh https://rpm.nodesource.com/pub_8.x/el/7/x86_64/nodejs-8.9.4-1nodesource.x86_64.rpm
```
Once the installation has completed, verify the version installed with the command:
```bash
$ node --version
v8.9.4
```
If you do not see a version starting `v8.9`, please contact Stoplight support for assistance.
#### Setting up the Package Repository
You can do this by copying-and-pasting the contents below into a terminal:
```bash
# expose credentials to environment first
REPO_USERNAME="myusername"
REPO_PASSWORD="mypassword"
# write credentials to repo file
cat <<EOF | sudo tee /etc/yum.repos.d/stoplight.repo
[stoplight]
name=Stoplight Package Repository
baseurl=https://$REPO_USERNAME:$REPO_PASSWORD@pkg.stoplight.io/rpm
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://pkg.stoplight.io/stoplight.key
EOF
```
> Be sure to set your repository credentials before issuing the `cat` command
#### Installing the API Package
Once the repository is configured properly, you can install the API component using the command:
```bash
sudo yum install stoplight-api -y
```
### Docker Installation
To install the API component with Docker, run the command below:
```bash
docker pull quay.io/stoplight/api
```
> Note, if you have not already authenticated with the Stoplight container registry, you will be prompted for credentials
## Configuring and Running
To configure the Stoplight API component, you will need to provide connection details to the other necessary Stoplight components.
### Package-based Installations
#### Configuring the Service
The Stoplight API configuration is located at the location:
```bash
/etc/stoplight-api/stoplight-api.cfg
```
The above file should contain the following entries:
```bash
# Secret used to encrypt cookies and other secrets used by the Stoplight API.
SIGN_SECRET="CHANGE_ME_TO_SOMETHING_RANDOM"
# Full URL to the Gitlab postgres instance.
POSTGRES_URL="postgres://username:password@example.com:5432"
# Domain that Stoplight is being served from. For example, if
# Stoplight is being served from 'stoplight.example.com', set
# this to 'example.com'.
SL_COOKIE_DOMAIN="example.com"
# SL_APP_HOST is the full URL to the Stoplight app component.
SL_APP_HOST="http://localhost:3030"
# SL_API_HOST is the full URL to this (the Stoplight API) component.
SL_API_HOST="http://localhost:3030"
# SL_EXPORTER_HOST is the full URL to the Stoplight exporter component.
SL_EXPORTER_HOST="http://localhost:3031"
# SL_GITLAB_HOST is the full URL to the Stoplight Gitlab instances HTTP port.
SL_GITLAB_HOST="http://localhost:8080"
# SL_REDIS_URL is the full URL to a Redis instance.
SL_REDIS_URL="redis://:password@exampl.com:6379"
```
> Please note that the `SIGN_SECRET` environment variable must remain static between service restarts
Be sure to customize any variable above as needed.
#### Starting the Service
To start the API server, run the command:
```bash
sudo systemctl start stoplight-api
```
Once started, you can see the status of the service using the command:
```bash
sudo systemctl status stoplight-api
```
### Docker Installations
#### Configuring the Container
The Stoplight API container requires the following environment variables be exposed to the running instance:
```bash
# Secret used to encrypt cookies and other secrets used by the Stoplight API.
SIGN_SECRET="CHANGE_ME_TO_SOMETHING_RANDOM"
# Full URL to the Gitlab postgres instance.
POSTGRES_URL="postgres://username:password@example.com:5432"
# Domain that Stoplight is being served from. For example, if
# Stoplight is being served from 'stoplight.example.com', set
# this to 'example.com'.
SL_COOKIE_DOMAIN="example.com"
# SL_APP_HOST is the full URL to the Stoplight app component.
SL_APP_HOST="http://localhost:3030"
# SL_API_HOST is the full URL to this (the Stoplight API) component.
SL_API_HOST="http://localhost:3030"
# SL_EXPORTER_HOST is the full URL to the Stoplight exporter component.
SL_EXPORTER_HOST="http://localhost:3031"
# SL_GITLAB_HOST is the full URL to the Stoplight Gitlab instances HTTP port.
SL_GITLAB_HOST="http://localhost:8080"
# SL_REDIS_URL is the full URL to a Redis instance.
SL_REDIS_URL="redis://:password@exampl.com:6379"
```
> Please note that the `SIGN_SECRET` environment variable must remain static between service restarts
To expose these to the Docker runtime, either write them to a file and use the `--env-file` argument:
```bash
cat <<EOF>api-env-vars
SL_APP_HOST="..."
...
EOF
docker run --env-file api-env-vars ...
```
Alternatively, you can expose them one at a time with the `-e` flag:
```bash
docker run -e SL_APP_HOST=https://stoplight.example.com ...
```
#### Starting the Container
To start the API container, run the command:
```bash
docker run \
--restart on-failure \
--env-file api-env \
-p 2345:3030 \
quay.io/stoplight/api:latest
```
If started properly, the container should be marked with a healthy status after 30 seconds. Use the `docker ps` command to verify the container was started and is running properly.
## Post-install Validations
Once the API component is running, you can verify the installation was successful issuing an HTTP GET request to the `/health` endpoint:
```bash
# be sure to update the port here to match the installation port
curl -v http://localhost:3030/health
```
If the API was installed and configured properly, you will receive an HTTP 200 response back.

221
articles/enterprise/components/app-overview.md Normal file
View File

@@ -0,0 +1,221 @@
# The Stoplight App
The __app__ component powers the Stoplight user interface by connecting users to the Stoplight API and other services.
> ### Requirements
>
> #### Storage
>
> There are no storage requirements for this component.
>
> #### Networking
>
> The default port for the app component is TCP port __3100__. The port can be customized using the `PORT` environment variable.
>
> _Be sure that both API and Gitlab components are available __before__ starting the app service_
## Installation
The Stoplight app can be installed with Docker or via RPM package.
> Before starting, be sure to complete the Gitlab and API installations.
### RPM Package
Prior to installing the RPM package, you will need to:
* Install NodeJS
* Have the Stoplight package repository installed and configured with your user-specific credentials
#### Installing NodeJS
To install NodeJS, please run the following commands:
```bash
# make sure all current versions of nodejs are removed
sudo yum remove nodejs npm -y
# install nodejs
sudo rpm -Uvh https://rpm.nodesource.com/pub_8.x/el/7/x86_64/nodejs-8.9.4-1nodesource.x86_64.rpm
```
Once the installation has completed, verify the version installed with the command:
```bash
$ node --version
v8.9.4
```
If you do not see a version starting `v8.9`, please contact Stoplight support for assistance.
#### Setting up the Package Repository
You can do this by copying-and-pasting the contents below into a terminal:
```bash
# expose credentials to environment first
REPO_USERNAME="myusername"
REPO_PASSWORD="mypassword"
# write credentials to repo file
cat <<EOF | sudo tee /etc/yum.repos.d/stoplight.repo
[stoplight]
name=Stoplight Package Repository
baseurl=https://$REPO_USERNAME:$REPO_PASSWORD@pkg.stoplight.io/rpm
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://pkg.stoplight.io/stoplight.key
EOF
```
> Be sure to set your repository credentials before issuing the `cat` command
#### Installing the App Package
Once the repository is configured properly, you can install the app component using the command:
```bash
sudo yum install stoplight-app -y
```
### Docker Installation
To install the app component with Docker, run the command below:
```bash
docker pull quay.io/stoplight/app
```
> Note, if you have not already authenticated with the Stoplight container registry, you will be prompted for credentials
## Configuring and Running
To configure the Stoplight app component, you will need to provide connection details to the other necessary Stoplight components.
### Package-based Installations
#### Configuring the Service
The Stoplight app configuration is located at the location:
```bash
/etc/stoplight-app/stoplight-app.cfg
```
The above file should contain the following entries:
```bash
# SL_APP_HOST is the public-facing URL for the stoplight application
SL_APP_HOST="https://stoplight.example.com"
# SL_API_HOST is the URL to the Stoplight API
SL_API_HOST="https://stoplight-api.internal.example.com:3030"
# SL_GITLAB_HOST is the full URL to the Stoplight Gitlab instance
SL_GITLAB_HOST="https://gitlab.internal.example.com:8080"
# SL_EXPORTER_HOST is the full URL to the Stoplight Gitlab instance
SL_EXPORTER_HOST="https://stoplight-exporter.internal.example.com"
# SL_PRISM_HOST is the full URL to the Stoplight Prism instance
SL_PRISM_HOST="https://stoplight-prism.internal.example.com"
# SL_PUBS_HOST is the top-level domain used for documentation
SL_PUBS_HOST="docs.example.com"
# SL_PUBS_INGRESS is the URL to the Stoplight Pubs instance admin API
SL_PUBS_INGRESS="https://pubs.example.com:9098"
```
Be sure to customize any variable above as needed.
#### Starting the Service
To start the app server, run the command:
```bash
sudo systemctl start stoplight-app
```
Once started, you can see the status of the service using the command:
```bash
sudo systemctl status stoplight-app
```
### Docker Installations
#### Configuring the Container
The Stoplight app container requires the following environment variables be exposed to the running instance:
```bash
# SL_APP_HOST is the public-facing URL for the stoplight application
SL_APP_HOST="https://stoplight.example.com"
# SL_API_HOST is the URL to the Stoplight API
SL_API_HOST="https://stoplight-api.internal.example.com:3030"
# SL_GITLAB_HOST is the full URL to the Stoplight Gitlab instance
SL_GITLAB_HOST="https://gitlab.internal.example.com:8080"
# SL_EXPORTER_HOST is the full URL to the Stoplight Gitlab instance
SL_EXPORTER_HOST="https://stoplight-exporter.internal.example.com"
# SL_PRISM_HOST is the full URL to the Stoplight Prism instance
SL_PRISM_HOST="https://stoplight-prism.internal.example.com"
# SL_PUBS_HOST is the top-level domain used for documentation
SL_PUBS_HOST="docs.example.com"
# SL_PUBS_INGRESS is the URL to the Stoplight Pubs instance admin API
SL_PUBS_INGRESS="https://pubs.example.com:9098"
```
To expose these to the Docker runtime, either write them to a file and use the `--env-file` argument:
```bash
cat <<EOF>app-env-vars
SL_APP_HOST="..."
...
EOF
docker run --env-file app-env-vars ...
```
Alternatively, you can expose them one at a time with the `-e` flag:
```bash
docker run -e SL_APP_HOST=https://stoplight.example.com ...
```
#### Starting the Container
To start the app container, run the command:
```bash
docker run \
--restart on-failure \
--env-file app-env \
-p 1234:3100 \
quay.io/stoplight/app:latest
```
If started properly, the container should be marked with a healthy status after 30 seconds. Use the `docker ps` command to verify the container was started and is running properly.
## Post-install Validations
Once the app component is running, you can verify the installation was successful by visiting the app hostname and port in a web browser. If the web page loads properly (what you see when visiting the [hosted site](https://next.stoplight.io/login)), then you should be greeted with a login screen, complete with images and styling.
If you would like to verify the app installation from the CLI, use `wget` to search for any broken links:
```
wget -r -l2 –spider -D example.com http://example.com 2>&1 | grep -B1 'broken link!'
```
> Be sure to replace 'example.com' above with the domain used to install the Stoplight application
No broken links reflects that the app was setup successfully.

191
articles/enterprise/components/exporter-overview.md Normal file
View File

@@ -0,0 +1,191 @@
# The Stoplight Exporter
The __Exporter__ component de-references JSON specifications to ensure all referenced files and external data sources are resolved when needed.
> #### Networking Details
>
> The default port for the API component is TCP port __3031__. The port can be customized using the `PORT` environment variable.
>
> The Exporter service is stateless and relies on no other components for operation.
## Installation
The Stoplight Exporter can be installed with Docker or via RPM package.
### RPM Package
Prior to installing the RPM package, you will need to:
* Install NodeJS
* Have the Stoplight package repository installed and configured with your user-specific credentials
#### Installing NodeJS
To install NodeJS, please run the following commands:
```bash
# make sure all current versions of nodejs are removed
sudo yum remove nodejs npm -y
# install nodejs
sudo rpm -Uvh https://rpm.nodesource.com/pub_8.x/el/7/x86_64/nodejs-8.9.4-1nodesource.x86_64.rpm
```
Once the installation has completed, verify the version installed with the command:
```bash
$ node --version
v8.9.4
```
If you do not see a version starting `v8.9`, please contact Stoplight support for assistance.
#### Setting up the Package Repository
You can do this by copying-and-pasting the contents below into a terminal:
```bash
# expose credentials to environment first
REPO_USERNAME="myusername"
REPO_PASSWORD="mypassword"
# write credentials to repo file
cat <<EOF | sudo tee /etc/yum.repos.d/stoplight.repo
[stoplight]
name=Stoplight Package Repository
baseurl=https://$REPO_USERNAME:$REPO_PASSWORD@pkg.stoplight.io/rpm
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://pkg.stoplight.io/stoplight.key
EOF
```
> Be sure to set your repository credentials before issuing the `cat` command
#### Installing the Exporter Package
Once the repository is configured properly, you can install the Exporter component using the command:
```bash
sudo yum install stoplight-exporter -y
```
### Docker Installation
To install the API component with Docker, run the command below:
```bash
docker pull quay.io/stoplight/exporter
```
> Note, if you have not already authenticated with the Stoplight container registry, you will be prompted for credentials
## Configuring and Running
To configure the Stoplight Exporter component, you will need to provide connection details to the other necessary Stoplight components.
### Package-based Installations
#### Configuring the Service
The Stoplight API configuration is located at the location:
```bash
/etc/stoplight-exporter/stoplight-exporter.cfg
```
The above file should contain the following entries:
```bash
# SL_APP_HOST is the public-facing URL for the stoplight application
SL_APP_HOST="https://stoplight.example.com"
# SL_API_HOST is the URL to the Stoplight API
SL_API_HOST="https://stoplight-api.internal.example.com:3030"
# SL_EXPORTER_HOST is the full URL to the Stoplight Gitlab instance
SL_EXPORTER_HOST="https://stoplight-exporter.internal.example.com"
# SL_PREVIEW_HOST is the full URL to the Stoplight Preview instance
SL_PREVIEW_HOST="https://stoplight-preview.internal.example.com"
```
Be sure to customize any variable above as needed.
#### Starting the Service
To start the API server, run the command:
```bash
sudo systemctl start stoplight-exporter
```
Once started, you can see the status of the service using the command:
```bash
sudo systemctl status stoplight-exporter
```
### Docker Installations
#### Configuring the Container
The Stoplight Exporter container requires the following environment variables be exposed to the running instance:
```bash
# SL_APP_HOST is the public-facing URL for the stoplight application
SL_APP_HOST="https://stoplight.example.com"
# SL_API_HOST is the URL to the Stoplight API
SL_API_HOST="https://stoplight-api.internal.example.com:3030"
# SL_EXPORTER_HOST is the full URL to the Stoplight Gitlab instance
SL_EXPORTER_HOST="https://stoplight-exporter.internal.example.com"
# SL_PREVIEW_HOST is the full URL to the Stoplight Preview instance
SL_PREVIEW_HOST="https://stoplight-preview.internal.example.com"
```
To expose these to the Docker runtime, either write them to a file and use the `--env-file` argument:
```bash
cat <<EOF>exporter-env-vars
SL_APP_HOST="..."
...
EOF
docker run --env-file exporter-env-vars ...
```
Alternatively, you can expose them one at a time with the `-e` flag:
```bash
docker run -e SL_APP_HOST=https://stoplight.example.com ...
```
#### Starting the Container
To start the API container, run the command:
```bash
docker run \
--restart on-failure \
--env-file exporter-env \
-p 2345:3031 \
quay.io/stoplight/exporter:latest
```
If started properly, the container should be marked with a healthy status after 30 seconds. Use the `docker ps` command to verify the container was started and is running properly.
## Post-install Validations
Once the Exporter component is running, you can verify the installation was successful issuing an HTTP GET request to the root (`/`) endpoint:
```bash
# be sure to update the port here to match the installation port
curl -v http://localhost:3031/
```
If the Exporter was installed and configured properly, you will receive an HTTP 200 reponse back.

181
articles/enterprise/components/gitlab-overview.md Normal file
View File

@@ -0,0 +1,181 @@
# Gitlab CE
Gitlab CE powers the Stoplight backend, including file storage and database.
> ### Requirements
>
> #### Storage
>
> Gitlab requires persistent storage in order to store Stoplight file data (in git), and optionally PostgreSQL data (when using the omnibus package).
>
> #### Networking
>
> The default port for Gitlab's HTTP API is TCP port 8080. The port can be customized via the Gitlab configuration file. The Gitlab process must also be able to initiate communication to PostgreSQL and Redis.
>
> _If not using the omnibus package, make sure that Redis and PostgreSQL are up and available prior to starting Gitlab_
## Installation
Gitlab can be installed with Docker or via RPM package.
### RPM Package
Prior to installing the RPM package, you will need to have the Stoplight package repository installed and configured with your user-specific credentials.
You can do this by copying-and-pasting the contents below into a terminal:
```bash
# expose credentials to environment first
REPO_USERNAME="myusername"
REPO_PASSWORD="mypassword"
# write credentials to repo file
cat <<EOF | sudo tee /etc/yum.repos.d/stoplight.repo
[stoplight]
name=Stoplight Package Repository
baseurl=https://$REPO_USERNAME:$REPO_PASSWORD@pkg.stoplight.io/rpm
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://pkg.stoplight.io/stoplight.key
EOF
```
> Be sure to set your repository credentials before issuing the `cat` command
Once the repository is configured properly, you can install the Gitlab component using the command:
```bash
sudo yum install stoplight-gitlab -y
```
### Docker Installation
To install the app component with Docker, run the command below:
```bash
docker pull quay.io/stoplight/gitlab
```
> Note, if you have not already authenticated with the Stoplight container registry, you will be prompted for credentials
## Configuring and Running
To configure the Stoplight Gitlab component, you will need to provide connection details to the other necessary components.
### Package-based Installations
#### Configuring the Service
The Stoplight Gitlab configuration is located at:
```bash
/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.
> For documentation on other Gitlab configuration options, please see the official documentation [here](https://docs.gitlab.com/omnibus/README.html#configuring)
#### Starting the Service
To start Gitlab for the first time, run the commands:
```bash
# one-time configuration (needed on new installs and upgrades)
sudo gitlab-ctl reconfigure
# start the services
sudo gitlab-ctl start
```
Once started, you can see the status of the service using the command:
```bash
sudo gitlab-ctl status
```
### Docker Installations
#### Configuring the Container
The Gitlab container should be configured nearly identically to the package installation described above, via file. The easiest way to do this is to mount the Gitlab configuration directory inside the container.
To mount the configuration inside the container, use the `-v` argument to the `docker run` command:
```bash
docker run -v /data/gitlab-config:/etc/gitlab ...
```
Where `/data/gitlab-config` is a directory containing your `gitlab.rb` configuration file.
> See [here](https://docs.gitlab.com/omnibus/README.html#configuring) for more information on how to configure Gitlab
#### Starting the Container
To start the app container, run the command:
```bash
docker run \
--restart on-failure \
-v /my/config:/etc/gitlab \
-p 8080:8080 \
quay.io/stoplight/gitlab:latest
```
If started properly, the container should be marked with a healthy status within 90 seconds (sometimes a little longer on first boot). Use the `docker ps` command to verify the container was started and is running properly.
## Post-install Validations
Once the Gitlab component is running, you can verify the installation was successful by using the methods below.
### Gitlab Environment Check
Gitlab comes with it's own check that can be useful for catching any improperly configured components. To run this check, use the command:
```bash
sudo gitlab-rake gitlab:check RAILS_ENV=production
```
If you are using a from-source installation, the command is modified to:
```bash
sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production
```
### Gitlab UI
If the environment check is successful, then you are ready to load up the Gitlab UI. In a web browser, visit the host and port that you are running Gitlab's HTTP port on.
For example, if you are running Gitlab on host `gitlab.example.com` on port `8080`, you can visit the following URL in a web browser to see the Gitlab UI:
[http://gitlab.example.com:8080/](http://gitlab.example.com:8080/)
If the installation was successful, you will be greeted by a Gitlab-branded login screen similar to what is displayed on their [hosted login screen](https://gitlab.com/users/sign_in).
> If you have enabled SSL, be sure to use `https://` when typing the Gitlab URL.
## FAQ
#### Can I use the embedded Redis or PostgreSQL for other services?
Yes! To expose the embedded Redis instance to the outside world, use the configuration:
```ruby
redis['bind'] = '127.0.0.1'
redis['port'] = 6379
```
Similarly, for PostgreSQL, use the configuration:
```ruby
postgresql['listen_address'] = '127.0.0.1'
postgresql['port'] = 5432
```
Once the configuration changes are made, issue a `gitlab-ctl reconfigure` for the changes to take effect.
> If running Gitlab in Docker, be sure to expose the Redis/PostgreSQL ports with the `-p` command-line option
For more information on configuring Redis, please see the official Gitlab documentation [here](https://docs.gitlab.com/omnibus/settings/redis.html).

101
articles/enterprise/components/hub-builder-overview.md Normal file
View File

@@ -0,0 +1,101 @@
# The Stoplight Hub Builder
The __Hub Builder__ component converts a Stoplight Hub into a standalone static HTML website, suitable for viewing and distribution.
> ### Requirements
>
> #### Storage
>
> The Hub Builder does not have any storage requirements.
>
> #### Networking
>
> The Hub Builder does not have a listening service or external port configurations.
## Installation
The Stoplight Hub Builder can be installed with Docker or via RPM package.
### RPM Package
Prior to installing the RPM package, you will need to:
* Install NodeJS
* Have the Stoplight package repository installed and configured with your user-specific credentials
#### Installing NodeJS
To install NodeJS, please run the following commands:
```bash
# make sure all current versions of nodejs are removed
sudo yum remove nodejs npm -y
# install nodejs
sudo rpm -Uvh https://rpm.nodesource.com/pub_8.x/el/7/x86_64/nodejs-8.9.4-1nodesource.x86_64.rpm
```
Once the installation has completed, verify the version installed with the command:
```bash
$ node --version
v8.9.4
```
If you do not see a version starting `v8.9`, please contact Stoplight support for assistance.
#### Setting up the Package Repository
You can do this by copying-and-pasting the contents below into a terminal:
```bash
# expose credentials to environment first
REPO_USERNAME="myusername"
REPO_PASSWORD="mypassword"
# write credentials to repo file
cat <<EOF | sudo tee /etc/yum.repos.d/stoplight.repo
[stoplight]
name=Stoplight Package Repository
baseurl=https://$REPO_USERNAME:$REPO_PASSWORD@pkg.stoplight.io/rpm
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://pkg.stoplight.io/stoplight.key
EOF
```
> Be sure to set your repository credentials before issuing the `cat` command
#### Installing the Hub Builder Package
Once the repository is configured properly, you can install the Hub Builder component using the command:
```bash
sudo yum install stoplight-hub-builder -y
```
### Docker Installation
To install the API component with Docker, run the command below:
```bash
docker pull quay.io/stoplight/hub-builder
```
> Note, if you have not already authenticated with the Stoplight container registry, you will be prompted for credentials
## Configuring and Running
### Package-based Installations
The Hub Builder component is an ad-hoc processing job, and does not have an associated service. The Tasker component is responsible for running and managing the Hub Builder jobs.
To ensure Tasker is able to run the Hub Builder package correctly, be sure to set Tasker to `shell` mode in the Tasker configuration.
### Docker Installations
The Hub Builder component is an ad-hoc processing job, and does not have an associated service. The Tasker component is responsible for running and managing the Hub Builder jobs.
To ensure Tasker is able to run the Hub Builder container correctly, be sure to set Tasker to `docker` mode in the Tasker configuration.

25
articles/enterprise/components/installation-overview.md Normal file
View File

@@ -0,0 +1,25 @@
# Installation Overview
The Stoplight Enterprise platform provides a fully-functional on-premise API design and documentation toolkit, taking the hassle out of your API strategy.
## Deployment Options
Before beginning with the installation, be sure to prepare all of the necessary systems that will be running Stoplight components. For more information on sizing, disk, and network requirements, please see the [Technical Requirements](/technical-requirements) section.
### Single-server vs. Multi-server Deployments
Stoplight can be deployed on one or many Linux servers (dedicated or virtualized). Single-server deployments run all of the necessary Stoplight components on a single Linux instance. This greatly simplifies the deployment process, as all components do not have to reach over the network to talk to eachother. Despite ease of installation, there are some notable shortcomings to this option:
* If the system is taken down for any reason, all components will be unavailable.
* Any single component can affect the performance of the entire Stoplight platform, leading to service degradation across all components.
Due to the shortcomings listed above, single-server deployments are typically recommended for POC/trial environments or for smaller organizations that do not wish to allocate multiple servers for the Stoplight platform.
Multi-server deployments run different Stoplight Enterprise components on separate Linux instances. This deployment option is much more resilient to system-level issues, though it does require more network configuration.
___Stoplight recommends multi-server deployments for all production environments.___
### Native vs. Docker Deployments
The Stoplight platform can be run either with the Docker container solution or natively on the Linux system. Both options are supported, however Stoplight recommends leveraging Docker for ease-of-use and improved security/sandboxing.

147
articles/enterprise/components/prism-overview.md Normal file
View File

@@ -0,0 +1,147 @@
# Stoplight Prism
The __Prism__ component powers scenarios and API orchestration.
> #### Networking Details
>
> The default port for the Prism component is TCP port __4050__ (HTTP). The port can be configured via configuration (see below).
## Installation
Prism can be installed with Docker or via RPM package.
### RPM Package
Prior to installing the RPM package, you will need to have the Stoplight package repository installed and configured with your user-specific credentials.
You can do this by copying-and-pasting the contents below into a terminal:
```bash
# expose credentials to environment first
REPO_USERNAME="myusername"
REPO_PASSWORD="mypassword"
# write credentials to repo file
cat <<EOF | sudo tee /etc/yum.repos.d/stoplight.repo
[stoplight]
name=Stoplight Package Repository
baseurl=https://$REPO_USERNAME:$REPO_PASSWORD@pkg.stoplight.io/rpm
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://pkg.stoplight.io/stoplight.key
EOF
```
> Be sure to set your repository credentials before issuing the `cat` command
Once the repository is configured properly, you can install the Pubs component using the command:
```bash
sudo yum install prism -y
```
### Docker Installation
To install the Pubs component with Docker, run the command below:
```bash
docker pull quay.io/stoplight/prism-multi
```
> Note, if you have not already authenticated with the Stoplight container registry, you will be prompted for credentials
## Configuring and Running
To configure the Prism component, you will need to provide runtime settings and connection details to the Stoplight App, API, and Exporter.
> Pubs uses the Stoplight API for authentication if using SSO within your published documentation, however it is not required
### Package-based Installations
#### Configuring the Service
The Prism configuration is located at `/etc/prism/prism.cfg`:
```bash
# URL to the Stoplight API
SL_API_HOST="http://localhost:3030"
# URL to the Stoplight App
SL_HOST="http://localhost:3100"
# URL to the Stoplight Exporter
SL_EXPORTER_HOST="http://localhost:3031"
# the following variables should be kept as the
# default unless needed otherwise
ENV_NAME="production"
MAX_QUEUE_SIZE=500
MAX_RUNTIME_POOL_SIZE=15
MAX_WORKERS=25
PRISM_LOG_LEVEL="ERROR"
```
Be sure to customize any variable above as needed.
#### Starting the Service
To start the Prism server, run the command:
```bash
sudo systemctl start prism
```
Once started, you can see the status of the service using the command:
```bash
sudo systemctl status prism
```
### Docker Installations
#### Configuring the Container
The Prism container can be configured either via file (see the package configuration above) or via environment variables. If you would like to configure Prism via environment variable, use the variable names directly from the Prism configuration above.
To expose variables to the Docker runtime, either write them to a file and use the `--env-file` argument:
```bash
cat <<EOF>prism-env-vars
SL_API_HOST="..."
...
EOF
docker run --env-file prism-env-vars ...
```
Alternatively, you can expose them one at a time with the `-e` flag:
```bash
docker run -e SL_API_HOST=api.stoplight.example.com ...
```
#### Starting the Container
To start the Prism container, use the command:
```bash
docker run \
--restart on-failure \
--env-file prism-env-vars \
-p 4050:4050 \
quay.io/stoplight/prism-multi:latest
```
If started properly, the container should be marked with a healthy status after 30 seconds. Use the `docker ps` command to verify the container was started and is running properly.
## Post-install Validations
Once the Prism component is running, you can verify the installation was successful issuing an HTTP GET request to the `/health` URL on the HTTP admin port (set with `admin_bind`):
```bash
$ curl -v localhost:4050/health
Hello!
```
> Be sure to update the URL above to match your local installation
If Prism was installed and configured properly, you will receive an HTTP 200 response back.

176
articles/enterprise/components/pubs-overview.md Normal file
View File

@@ -0,0 +1,176 @@
# Stoplight Pubs
The __Pubs__ component serves and catalogs hubs published through Stoplight.
> #### Networking Details
>
> The default ports for the Pubs component are TCP ports __8080__ (HTTP), __8443__ (HTTPS), and __9098__ (HTTPS optional). All ports can be configured via configuration (see below).
## Installation
Pubs can be installed with Docker or via RPM package.
### RPM Package
Prior to installing the RPM package, you will need to have the Stoplight package repository installed and configured with your user-specific credentials.
You can do this by copying-and-pasting the contents below into a terminal:
```bash
# expose credentials to environment first
REPO_USERNAME="myusername"
REPO_PASSWORD="mypassword"
# write credentials to repo file
cat <<EOF | sudo tee /etc/yum.repos.d/stoplight.repo
[stoplight]
name=Stoplight Package Repository
baseurl=https://$REPO_USERNAME:$REPO_PASSWORD@pkg.stoplight.io/rpm
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://pkg.stoplight.io/stoplight.key
EOF
```
> Be sure to set your repository credentials before issuing the `cat` command
Once the repository is configured properly, you can install the Pubs component using the command:
```bash
sudo yum install pubs -y
```
### Docker Installation
To install the Pubs component with Docker, run the command below:
```bash
docker pull quay.io/stoplight/pubs
```
> Note, if you have not already authenticated with the Stoplight container registry, you will be prompted for credentials
## Configuring and Running
To configure the Pubs component, you will need to provide runtime settings and connection details to the Stoplight Pubs.
> Pubs uses the Stoplight API for authentication if using SSO within your published documentation, however it is not required
### Package-based Installations
#### Configuring the Service
The Pubs configuration is located at:
```bash
/etc/pubs/pubs.yml
```
The above file should contain the following entries:
```bash
# Bind address/port to serve HTTP traffic on
http_bind: "127.0.0.1:8080"
# Bind address/port to serve HTTPS traffic on, if enabled (see below)
https_bind: "127.0.0.1:8443"
# Whether to enable SSL, powered by LetsEncrypt. If true, HTTP serving is
# disabled.
ssl_enabled: yes
# Bind address/port to server admin/management API
admin_bind: "127.0.0.1:9098"
# Whether to enable SSL when serving admin API
admin_ssl_enabled: no
# If SSL is enabled for the management API, a certificate and key must be
# provided
admin_ssl_cert_path:
admin_ssl_key_path:
# If set, only requests with the following IPs will be responded to by the admin
# API
admin_ip_whitelist:
# - 127.0.0.1
# Directory to store builds, build metadata, and dynamically-generated
# certificates
data_dir: /var/lib/pubs
```
Be sure to customize any variable above as needed.
#### Starting the Service
To start the Pubs server, run the command:
```bash
sudo systemctl start pubs
```
Once started, you can see the status of the service using the command:
```bash
sudo systemctl status pubs
```
### Docker Installations
#### Configuring the Container
The Pubs container can be configured either via file (see the package configuration above) or via environment variables. If you would like to configure Pubs via environment variable, use the variable naming conventions from the configuration file above and prepend a `PUBS_` prefix to them.
For example, to set the HTTP bind address through the environment, use the variable:
```
PUBS_HTTP_BIND="localhost:8080"
```
> Be sure to capitalize all letters and prefix environment variables with `PUBS_` (ie, `ssl_enabled` becomes `PUBS_SSL_ENABLED`)
To expose these to the Docker runtime, either write them to a file and use the `--env-file` argument:
```bash
cat <<EOF>pubs-env-vars
PUBS_HTTP_BIND="..."
...
EOF
docker run --env-file pubs-env-vars ...
```
Alternatively, you can expose them one at a time with the `-e` flag:
```bash
docker run -e PUBS_HTTP_BIND=0.0.0.0:80 ...
```
#### Starting the Container
To start the Pubs container, use the command:
```bash
docker run \
--restart on-failure \
--env-file pubs-env-vars \
-p 80:8080 \
-p 443:8443 \
-p 9098:9098 \
quay.io/stoplight/pubs:latest
```
If started properly, the container should be marked with a healthy status after 30 seconds. Use the `docker ps` command to verify the container was started and is running properly.
## Post-install Validations
Once the Pubs component is running, you can verify the installation was successful issuing an HTTP GET request to the `/health` URL on the HTTP admin port (set with `admin_bind`):
```bash
curl -v http://localhost:9098/health
```
> Be sure to update the URL above to match your local installation
If Pubs was installed and configured properly, you will receive an HTTP 200 response back.

174
articles/enterprise/components/tasker-overview.md Normal file
View File

@@ -0,0 +1,174 @@
# Stoplight Tasker
The __Tasker__ component runs scheduled and on-demand tasks for the Stoplight platform.
> #### Networking Details
>
> The default port for the Tasker component is TCP port __9432__.
>
> The port and bind address can be configured via the `TASKER_HTTP_BIND` environment variable or the `--listen` CLI flag.
>
> Tasker requires a Redis instance to be available when starting. Be sure to setup Redis before installing Tasker.
## Installation
Tasker can be installed with Docker or via RPM package.
### RPM Package
Prior to installing the RPM package, you will need to have the Stoplight package repository installed and configured with your user-specific credentials.
You can do this by copying-and-pasting the contents below into a terminal:
```bash
# expose credentials to environment first
REPO_USERNAME="myusername"
REPO_PASSWORD="mypassword"
# write credentials to repo file
cat <<EOF | sudo tee /etc/yum.repos.d/stoplight.repo
[stoplight]
name=Stoplight Package Repository
baseurl=https://$REPO_USERNAME:$REPO_PASSWORD@pkg.stoplight.io/rpm
enabled=1
gpgcheck=1
repo_gpgcheck=1
gpgkey=https://pkg.stoplight.io/stoplight.key
EOF
```
> Be sure to set your repository credentials before issuing the `cat` command
Once the repository is configured properly, you can install the Tasker component using the command:
```bash
sudo yum install tasker -y
```
### Docker Installation
To install the Tasker component with Docker, run the command below:
```bash
docker pull quay.io/stoplight/tasker
```
> Note, if you have not already authenticated with the Stoplight container registry, you will be prompted for credentials
## Configuring and Running
To configure the Tasker component, you will need to provide runtime settings and connection details for a running Redis instance.
### Package-based Installations
#### Configuring the Service
The Tasker configuration is located at:
```bash
/etc/tasker/tasker.cfg
```
The above file should contain the following entries:
```bash
# Tasker HTTP bind address (host:port)
TASKER_HTTP_BIND="localhost:9432"
# Tasker execution mode, either 'shell' or 'docker'
TASKER_MODE="shell"
# If using 'shell' mode, provide path to stoplight-hub-builder package root
CORE_ROOT="/opt/stoplight-hub-builder"
# Redis host:port to connect to (must be available before starting service)
TASKER_REDIS_HOSTPORT="redis:6379"
# Redis password, if any
TASKER_REDIS_PASSWORD=""
# Redis database
TASKER_REDIS_DATABASE="0"
# Redis namespace
TASKER_REDIS_NAMESPACE=""
```
Be sure to customize any variable above as needed.
#### Starting the Service
To start the Tasker server, run the command:
```bash
sudo systemctl start tasker
```
Once started, you can see the status of the service using the command:
```bash
sudo systemctl status tasker
```
### Docker Installations
#### Configuring the Container
The Tasker container can be configured via the following environment variables:
```bash
# Tasker HTTP bind address (host:port)
TASKER_HTTP_BIND="localhost:9432"
# Tasker execution mode, either 'shell' or 'docker'
TASKER_MODE="shell"
# If using 'shell' mode, provide path to stoplight-hub-builder package root
CORE_ROOT="/opt/stoplight-hub-builder"
# Redis host:port to connect to (must be available before starting service)
TASKER_REDIS_HOSTPORT="redis:6379"
# Redis password, if any
TASKER_REDIS_PASSWORD=""
# Redis database
TASKER_REDIS_DATABASE="0"
# Redis namespace
TASKER_REDIS_NAMESPACE=""
```
To expose these to the Docker runtime, either write them to a file and use the `--env-file` argument:
```bash
cat <<EOF>tasker-env-vars
TASKER_HTTP_BIND="..."
...
EOF
docker run --env-file tasker-env-vars ...
```
Alternatively, you can expose them one at a time with the `-e` flag:
```bash
docker run -e TASKER_HTTP_BIND=0.0.0.0:9432 ...
```
#### Starting the Container
To start the Tasker container, use the command:
```bash
docker run \
--restart on-failure \
--env-file tasker-env-vars \
-p 9432:9432 \
quay.io/stoplight/tasker:latest
```
If started properly, the container should be marked with a healthy status after 30 seconds. Use the `docker ps` command to verify the container was started and is running properly.
## Post-install Validations
Once the Tasker component is running, you can verify the installation was successful issuing an HTTP GET request to the `/health` endpoint:
```bash
# be sure to update the port here to match the installation port
curl -v http://localhost:9432/health
```
If Tasker was installed and configured properly, you will receive an HTTP 200 reponse back.

27
articles/enterprise/maintenance/backups.md Normal file
View File

@@ -0,0 +1,27 @@
## Gitlab
Gitlab is a critical piece of the Stoplight Enterprise platform. Stoplight recommends, at a minimum, daily backups of the Gitlab database and filesystem to ensure minimal data loss in the event of a failure.
To run a backup for Gitlab, which includes a snapshot of the filesystem and database, run the command:
```bash
sudo gitlab-rake gitlab:backup:create
```
Backups are in zip format, making them very easy to store in remote or cloud storage. Gitlab also offers built-in capabilities that provide automatic uploads to cloud storage providers when configured.
For more information, please see the official Gitlab backup documentation [here](https://docs.gitlab.com/ee/raketasks/backup_restore.html).
## Pubs
Pubs stores all published hubs created via the Stoplight application. While not critical to the health of the Stoplight Enterprise platform, it is recommended that the pubs data directory is backed up on a regular basis.
To perform a backup of the Pubs data directory, take a tarball snapshot of the Pubs data directory and configuration directory. By default, the Pubs data directory is located at `/var/lib/pubs`, and the configuration directory is located at `/etc/pubs`.
To perform a backup, run the command:
```bash
sudo tar -cvzf pubs-backup.$(date +%s).tar.gz /var/lib/pubs /etc/pubs
```
Once the backup is completed, the tarball output can be stored on redundant or cloud storage.

308
articles/enterprise/technical-requirements.md Normal file
View File

@@ -0,0 +1,308 @@
# Technical Requirements
Stoplight currently supports the following Linux distributions for on-premise installations:
* Ubuntu 16.04 LTS (x86_64)
* CentOS / RedHat Enterprise Linux 7 (x86_64)
A minimum of one server is required to run the Stoplight application, however, for a production installation, we recommend at least four servers (excluding monitoring and backup servers). The system specifications for each server can be found below under each component.
![](https://s3.amazonaws.com/user-content.stoplight.io/1564/1520952929100)
## Prerequisites
### Docker-based Installations
For the recommended Docker-based installation path, the only application requirements are:
- [Nginx](http://nginx.org/) v1.10.3
- [Docker CE](https://www.docker.com/) v17.00
### Package-based Installations
If Docker is not allowed within your operating environment, the application requirements are:
- [Nginx](http://nginx.org/) v1.10.3
- [NodeJS](https://nodejs.org/) v8.9.1
- [PostgreSQL](https://www.postgresql.org/) v9.6 (optionally included with Gitlab)
- [Redis](https://redis.io/) v2.8 (optionally included with Gitlab)
For automation and configuration purposes, [Ansible](https://www.ansible.com/) v2.2 is also recommended. For monitoring purposes, Stoplight recommends the following applications:
- [InfluxDB](https://www.influxdata.com/time-series-platform/influxdb/) v1.3
for metrics storage and aggregation
- [Kapacitor](https://www.influxdata.com/time-series-platform/kapacitor/) v1.3
for alerting and metrics processing
- [Telegraf](https://www.influxdata.com/time-series-platform/telegraf/) v1.4
for metrics collection
- [Mtail](https://github.com/google/mtail) v3.0 for whitebox monitoring of
application logs
Please note that the above recommendations are entirely optional if your organization already has a monitoring and alerting solution in place.
## Stoplight Components
The Stoplight platform is broken up in to seven main components:
1. App
2. API
3. Prism
4. Exporter
5. Jobs Server / Publisher
6. Hubs Server
7. Stoplight's fork of Gitlab CE
Each component is described in detail below.
---
### App
*Required*
The app server serves up the Stoplight UI. This is the primary point of
ingress for most users using Stoplight. It is what they will load in their web
browser, and connect the desktop app to.
#### System Specifications
For app servers, we recommend a minimum of the following system
specifications:
- 2 CPUs
- 2GB Memory
#### Networking
The app service must be able to contact the following components:
- API
- Prism
- Exporter
- Gitlab CE
---
### API
*Required*
The API server is what the App server (described above) connects to to fetch
and persist data.
#### System Specifications
For API servers, we recommend co-locating with Gitlab and using a minimum of
the following system specifications:
- 4 CPUs
- 8GB Memory
#### Networking
The API service must be able to contact the following components:
- App
- Gitlab CE (+ PostgreSQL)
---
### Prism
*Required to run scenarios (testing and orchestration) and mocking servers.*
The Prism server runs scenario collections.
Please note that Prism must be setup with a wildcard subdomain (CNAME DNS
record), for example `*.prism.example.com`. Each Prism instance that is
created gets a unique hostname associated with it, for example
`service1-mock.prism.example.com`. This is preferrable to storing the instance
ID in a path (`prism.example.com/service1-mock`) because it means that you
don't need to change your API code - all you need to do is change your host
variable.
#### System Specifications
For Prism servers, we recommend a minimum of the following system
specifications:
- 2 CPUs
- 4GB Memory
#### Networking
The Prism service must be able to contact the following components:
- Exporter
---
### Exporter
*Required*
The Exporter server dereferences OAS and Swagger files to ensure all
referenced specs and external data sources are resolvable by runtime.
#### System Specifications
For Exporter servers, we recommend a minimum of the following system
specifications:
- 2 CPUs
- 2GB Memory
#### Networking
The Exporter service must be able to contact the following components:
- API
---
### Jobs Server (Tasker)
*Optional. Required to build and publish Hubs (technical documentation).*
The jobs server runs on-demand tasks for the Stoplight platform. The only job
type currently supported is a "publish" task, which converts a Stoplight Hub
into a standalone static site and submits it to the Hubs server.
#### System Specifications
For job servers, we recommend a minimum of the following system
specifications:
- 2 CPUs
- 2GB Memory
#### Networking
The Exporter service must be able to contact the following components:
- API
- Hubs Server
- Redis
---
### Hubs Server (Pubs)
*Optional. Required for publishing and serving documentation.*
The Hubs server runs processes and serves a Hub that has been "published"
(converted into a standalone static site).
#### System Specifications
For Hubs servers, we recommend a minimum of the following system
specifications:
- 2 CPUs
- 2GB Memory
#### Networking
The Exporter service must be able to contact the following components:
- API
- Jobs Server
---
### Gitlab CE
*Required*
Gitlab CE is the backing datastore for all files stored within Stoplight. In
addition to storing files, Gitlab CE is responsible for:
* Interfacing with the Stoplight API
* User-facing notifications (including password reset emails, group/project
invitations, etc)
* Tracking all changes between different files, and storing them within a Git
repository
Packaged within the Gitlab CE is an installation of PostgreSQL v9.6 and Redis
v2.8. These two sub-components can be broken out into external services if
your organization is already familiar with running these (or similar)
services. You may also break out these services if you plan on using a managed
hosting solution, for example Amazon RDS (for PostgreSQL) or Amazon
ElastiCache (for Redis).
#### System Specifications
For Gitlab servers, we recommend co-locating with the API and using a minimum
of the following system specifications:
- 4 CPUs
- 8GB Memory
- SSD-backed redundant storage
#### Networking
The Gitlab service has no outgoing network dependencies unless the Redis or
PostgreSQL sub-components are broken out separately.

1
articles/robbins.md
View File

@@ -1 +0,0 @@