From a0f661ecad383e881a32fd0aefd2e89cc954250d Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Tue, 10 Apr 2018 17:23:17 -0500 Subject: [PATCH 01/30] Add enterprise docs --- articles/enterprise/authentication/saml.md | 39 +++ .../enterprise/components/api-overview.md | 226 +++++++++++++ .../enterprise/components/app-overview.md | 221 +++++++++++++ .../components/exporter-overview.md | 191 +++++++++++ .../enterprise/components/gitlab-overview.md | 181 ++++++++++ .../components/hub-builder-overview.md | 101 ++++++ .../components/installation-overview.md | 25 ++ .../enterprise/components/prism-overview.md | 147 +++++++++ .../enterprise/components/pubs-overview.md | 176 ++++++++++ .../enterprise/components/tasker-overview.md | 174 ++++++++++ articles/enterprise/maintenance/backups.md | 27 ++ articles/enterprise/technical-requirements.md | 308 ++++++++++++++++++ articles/robbins.md | 1 - 13 files changed, 1816 insertions(+), 1 deletion(-) create mode 100644 articles/enterprise/authentication/saml.md create mode 100644 articles/enterprise/components/api-overview.md create mode 100644 articles/enterprise/components/app-overview.md create mode 100644 articles/enterprise/components/exporter-overview.md create mode 100644 articles/enterprise/components/gitlab-overview.md create mode 100644 articles/enterprise/components/hub-builder-overview.md create mode 100644 articles/enterprise/components/installation-overview.md create mode 100644 articles/enterprise/components/prism-overview.md create mode 100644 articles/enterprise/components/pubs-overview.md create mode 100644 articles/enterprise/components/tasker-overview.md create mode 100644 articles/enterprise/maintenance/backups.md create mode 100644 articles/enterprise/technical-requirements.md delete mode 100644 articles/robbins.md diff --git a/articles/enterprise/authentication/saml.md b/articles/enterprise/authentication/saml.md new file mode 100644 index 0000000..1013f46 --- /dev/null +++ b/articles/enterprise/authentication/saml.md @@ -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 + + + +urn:oasis:names:tc:SAML:2.0:nameid-format:persistent + + + + +``` + +Be sure to update the `AssertionConsumerService` / `Location` object with the correct callback URL for the Stoplight API. \ No newline at end of file diff --git a/articles/enterprise/components/api-overview.md b/articles/enterprise/components/api-overview.md new file mode 100644 index 0000000..9166bef --- /dev/null +++ b/articles/enterprise/components/api-overview.md @@ -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 < 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 <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. \ No newline at end of file diff --git a/articles/enterprise/components/app-overview.md b/articles/enterprise/components/app-overview.md new file mode 100644 index 0000000..505cea4 --- /dev/null +++ b/articles/enterprise/components/app-overview.md @@ -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 < 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 <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. diff --git a/articles/enterprise/components/exporter-overview.md b/articles/enterprise/components/exporter-overview.md new file mode 100644 index 0000000..7de61bd --- /dev/null +++ b/articles/enterprise/components/exporter-overview.md @@ -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 < 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 <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. \ No newline at end of file diff --git a/articles/enterprise/components/gitlab-overview.md b/articles/enterprise/components/gitlab-overview.md new file mode 100644 index 0000000..82c930f --- /dev/null +++ b/articles/enterprise/components/gitlab-overview.md @@ -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 < 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). diff --git a/articles/enterprise/components/hub-builder-overview.md b/articles/enterprise/components/hub-builder-overview.md new file mode 100644 index 0000000..9cce0d7 --- /dev/null +++ b/articles/enterprise/components/hub-builder-overview.md @@ -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 < 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. \ No newline at end of file diff --git a/articles/enterprise/components/installation-overview.md b/articles/enterprise/components/installation-overview.md new file mode 100644 index 0000000..657e5a2 --- /dev/null +++ b/articles/enterprise/components/installation-overview.md @@ -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. diff --git a/articles/enterprise/components/prism-overview.md b/articles/enterprise/components/prism-overview.md new file mode 100644 index 0000000..49a948b --- /dev/null +++ b/articles/enterprise/components/prism-overview.md @@ -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 < 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 <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. \ No newline at end of file diff --git a/articles/enterprise/components/pubs-overview.md b/articles/enterprise/components/pubs-overview.md new file mode 100644 index 0000000..52e6da6 --- /dev/null +++ b/articles/enterprise/components/pubs-overview.md @@ -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 < 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 <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. \ No newline at end of file diff --git a/articles/enterprise/components/tasker-overview.md b/articles/enterprise/components/tasker-overview.md new file mode 100644 index 0000000..0d03588 --- /dev/null +++ b/articles/enterprise/components/tasker-overview.md @@ -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 < 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 <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. \ No newline at end of file diff --git a/articles/enterprise/maintenance/backups.md b/articles/enterprise/maintenance/backups.md new file mode 100644 index 0000000..eee6ef5 --- /dev/null +++ b/articles/enterprise/maintenance/backups.md @@ -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. \ No newline at end of file diff --git a/articles/enterprise/technical-requirements.md b/articles/enterprise/technical-requirements.md new file mode 100644 index 0000000..afd1848 --- /dev/null +++ b/articles/enterprise/technical-requirements.md @@ -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. diff --git a/articles/robbins.md b/articles/robbins.md deleted file mode 100644 index 8b13789..0000000 --- a/articles/robbins.md +++ /dev/null @@ -1 +0,0 @@ - From 919f479d685be7435b54255a875edc57750ae9bf Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Tue, 10 Apr 2018 17:25:30 -0500 Subject: [PATCH 02/30] Small update to saml doc --- articles/enterprise/authentication/saml.md | 23 +++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/articles/enterprise/authentication/saml.md b/articles/enterprise/authentication/saml.md index 1013f46..cd4c713 100644 --- a/articles/enterprise/authentication/saml.md +++ b/articles/enterprise/authentication/saml.md @@ -1,10 +1,15 @@ -To configure Stoplight Enterprise to use SAML for user authentication, add the following variable to the Stoplight API configuration or environment: +# Configuring SAML Authentication + +To configure Stoplight Enterprise to use SAML for user authentication, +add the following variable to the Stoplight API +configuration/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. +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: @@ -16,12 +21,15 @@ sudo docker restart stoplight-api sudo systemctl restart stoplight-api ``` +Once restarted, all login requests will be authenticated via the +external SAML service. -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. -> 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 +## SAML IdP Metadata To configure Stoplight SAML integration from the SAML server, use the following SAML metadata file: @@ -36,4 +44,5 @@ urn:oasis:names:tc:SAML:2.0:nameid-format:persistent ``` -Be sure to update the `AssertionConsumerService` / `Location` object with the correct callback URL for the Stoplight API. \ No newline at end of file +Be sure to update the `AssertionConsumerService` / `Location` object +with the correct callback URL for the Stoplight API. \ No newline at end of file From b6cb92440bf78bdb56042216cf1a6f6a2d7ab318 Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Thu, 12 Apr 2018 12:24:51 -0500 Subject: [PATCH 03/30] Move installation-overview out of components directory. Minor updates and formatting fixes based on feedback. --- .../enterprise/components/api-overview.md | 26 +- .../enterprise/components/app-overview.md | 27 +- .../components/exporter-overview.md | 14 +- .../enterprise/components/gitlab-overview.md | 61 ++-- .../components/installation-overview.md | 25 -- .../enterprise/components/prism-overview.md | 12 +- .../enterprise/components/pubs-overview.md | 14 +- .../enterprise/components/tasker-overview.md | 14 +- articles/enterprise/installation-overview.md | 44 +++ articles/enterprise/maintenance/backups.md | 34 +- articles/enterprise/technical-requirements.md | 335 +++++++----------- 11 files changed, 288 insertions(+), 318 deletions(-) delete mode 100644 articles/enterprise/components/installation-overview.md create mode 100644 articles/enterprise/installation-overview.md diff --git a/articles/enterprise/components/api-overview.md b/articles/enterprise/components/api-overview.md index 9166bef..0b4ee28 100644 --- a/articles/enterprise/components/api-overview.md +++ b/articles/enterprise/components/api-overview.md @@ -1,18 +1,18 @@ # The Stoplight API -The __API__ component powers the Stoplight backend, connecting the UI to the datastore and other miscellaneous Stoplight services. +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. +> The default port for the API component is TCP port **3030**. The port can be customized using the `PORT` environment variable. +> +> Make 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. +> Before starting, be sure to complete the GitLab installation. ### RPM Package @@ -36,7 +36,6 @@ sudo rpm -Uvh https://rpm.nodesource.com/pub_8.x/el/7/x86_64/nodejs-8.9.4-1nodes Once the installation has completed, verify the version installed with the command: - ```bash $ node --version v8.9.4 @@ -83,7 +82,8 @@ To install the API component with Docker, run the command below: docker pull quay.io/stoplight/api ``` -> Note, if you have not already authenticated with the Stoplight container registry, you will be prompted for credentials +> Note, if the system you are using has not already authenticated with the +> Stoplight container registry, you will be prompted for credentials ## Configuring and Running @@ -105,7 +105,7 @@ The above file should contain the following entries: # 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. +# 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 @@ -122,7 +122,7 @@ 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 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. @@ -131,7 +131,7 @@ 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. +Be sure to customize any of the variables above as needed. #### Starting the Service @@ -157,7 +157,7 @@ The Stoplight API container requires the following environment variables be expo # 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. +# 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 @@ -174,7 +174,7 @@ 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 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. @@ -223,4 +223,4 @@ Once the API component is running, you can verify the installation was successfu curl -v http://localhost:3030/health ``` -If the API was installed and configured properly, you will receive an HTTP 200 response back. \ No newline at end of file +If the API was installed and configured properly, you will receive an HTTP 200 response back. diff --git a/articles/enterprise/components/app-overview.md b/articles/enterprise/components/app-overview.md index 505cea4..e64afee 100644 --- a/articles/enterprise/components/app-overview.md +++ b/articles/enterprise/components/app-overview.md @@ -1,24 +1,24 @@ # The Stoplight App -The __app__ component powers the Stoplight user interface by connecting users to the Stoplight API and other services. +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_ +> 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. +> Before starting, be sure to complete the GitLab and API installations. ### RPM Package @@ -42,7 +42,6 @@ sudo rpm -Uvh https://rpm.nodesource.com/pub_8.x/el/7/x86_64/nodejs-8.9.4-1nodes Once the installation has completed, verify the version installed with the command: - ```bash $ node --version v8.9.4 @@ -114,10 +113,10 @@ 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 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 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 @@ -130,7 +129,7 @@ SL_PUBS_HOST="docs.example.com" SL_PUBS_INGRESS="https://pubs.example.com:9098" ``` -Be sure to customize any variable above as needed. +Be sure to customize any of the variables above as needed. #### Starting the Service @@ -159,10 +158,10 @@ 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 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 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 diff --git a/articles/enterprise/components/exporter-overview.md b/articles/enterprise/components/exporter-overview.md index 7de61bd..7e6e0d1 100644 --- a/articles/enterprise/components/exporter-overview.md +++ b/articles/enterprise/components/exporter-overview.md @@ -1,11 +1,11 @@ # The Stoplight Exporter -The __Exporter__ component de-references JSON specifications to ensure all referenced files and external data sources are resolved when needed. +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 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 @@ -105,14 +105,14 @@ 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 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. +Be sure to customize any of the variables above as needed. #### Starting the Service @@ -141,7 +141,7 @@ 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 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 @@ -188,4 +188,4 @@ Once the Exporter component is running, you can verify the installation was succ curl -v http://localhost:3031/ ``` -If the Exporter was installed and configured properly, you will receive an HTTP 200 reponse back. \ No newline at end of file +If the Exporter was installed and configured properly, you will receive an HTTP 200 reponse back. diff --git a/articles/enterprise/components/gitlab-overview.md b/articles/enterprise/components/gitlab-overview.md index 82c930f..6583ae8 100644 --- a/articles/enterprise/components/gitlab-overview.md +++ b/articles/enterprise/components/gitlab-overview.md @@ -1,26 +1,26 @@ -# Gitlab CE +# GitLab CE -Gitlab CE powers the Stoplight backend, including file storage and database. +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). -> +> +> 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_ +> 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. +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. +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: @@ -41,9 +41,9 @@ gpgkey=https://pkg.stoplight.io/stoplight.key EOF ``` -> Be sure to set your repository credentials before issuing the `cat` command +> Make sure that the repository credentials are set before issuing the `cat` command -Once the repository is configured properly, you can install the Gitlab component using the command: +Once the repository is configured properly, you can install the GitLab component using the command: ```bash sudo yum install stoplight-gitlab -y @@ -61,25 +61,25 @@ docker pull quay.io/stoplight/gitlab ## Configuring and Running -To configure the Stoplight Gitlab component, you will need to provide connection details to the other necessary components. +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: +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. +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) +> 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: +To start GitLab for the first time, run the commands: ```bash # one-time configuration (needed on new installs and upgrades) @@ -99,7 +99,7 @@ sudo gitlab-ctl status #### 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. +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: @@ -109,7 +109,7 @@ 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 +> See [here](https://docs.gitlab.com/omnibus/README.html#configuring) for more information on how to configure GitLab #### Starting the Container @@ -127,11 +127,11 @@ If started properly, the container should be marked with a healthy status within ## Post-install Validations -Once the Gitlab component is running, you can verify the installation was successful by using the methods below. +Once the GitLab component is running, you can verify the installation was successful by using the methods below. -### Gitlab Environment Check +### 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: +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 @@ -143,21 +143,20 @@ If you are using a from-source installation, the command is modified to: sudo -u git -H bundle exec rake gitlab:check RAILS_ENV=production ``` -### Gitlab UI +### 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. +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: +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 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. +> If you have enabled SSL, make 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: @@ -176,6 +175,6 @@ 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 +> 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). +For more information on configuring Redis, please see the official GitLab documentation [here](https://docs.gitlab.com/omnibus/settings/redis.html). diff --git a/articles/enterprise/components/installation-overview.md b/articles/enterprise/components/installation-overview.md deleted file mode 100644 index 657e5a2..0000000 --- a/articles/enterprise/components/installation-overview.md +++ /dev/null @@ -1,25 +0,0 @@ -# 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. diff --git a/articles/enterprise/components/prism-overview.md b/articles/enterprise/components/prism-overview.md index 49a948b..7908758 100644 --- a/articles/enterprise/components/prism-overview.md +++ b/articles/enterprise/components/prism-overview.md @@ -1,10 +1,10 @@ # Stoplight Prism -The __Prism__ component powers scenarios and API orchestration. +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). +> The default port for the Prism component is TCP port **4050** (HTTP). The port can be configured via configuration (see below). ## Installation @@ -12,7 +12,7 @@ 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. +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: @@ -71,7 +71,7 @@ SL_HOST="http://localhost:3100" # URL to the Stoplight Exporter SL_EXPORTER_HOST="http://localhost:3031" -# the following variables should be kept as the +# the following variables should be kept as the # default unless needed otherwise ENV_NAME="production" MAX_QUEUE_SIZE=500 @@ -80,7 +80,7 @@ MAX_WORKERS=25 PRISM_LOG_LEVEL="ERROR" ``` -Be sure to customize any variable above as needed. +Be sure to customize any of the variables above as needed. #### Starting the Service @@ -144,4 +144,4 @@ 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. \ No newline at end of file +If Prism was installed and configured properly, you will receive an HTTP 200 response back. diff --git a/articles/enterprise/components/pubs-overview.md b/articles/enterprise/components/pubs-overview.md index 52e6da6..87be4e6 100644 --- a/articles/enterprise/components/pubs-overview.md +++ b/articles/enterprise/components/pubs-overview.md @@ -1,10 +1,10 @@ # Stoplight Pubs -The __Pubs__ component serves and catalogs hubs published through Stoplight. +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). +> 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 @@ -12,7 +12,7 @@ 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. +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: @@ -87,8 +87,8 @@ admin_bind: "127.0.0.1:9098" 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: +admin_ssl_cert_path: +admin_ssl_key_path: # If set, only requests with the following IPs will be responded to by the admin # API @@ -100,7 +100,7 @@ admin_ip_whitelist: data_dir: /var/lib/pubs ``` -Be sure to customize any variable above as needed. +Be sure to customize any of the variables above as needed. #### Starting the Service @@ -173,4 +173,4 @@ 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. \ No newline at end of file +If Pubs was installed and configured properly, you will receive an HTTP 200 response back. diff --git a/articles/enterprise/components/tasker-overview.md b/articles/enterprise/components/tasker-overview.md index 0d03588..f5bce8d 100644 --- a/articles/enterprise/components/tasker-overview.md +++ b/articles/enterprise/components/tasker-overview.md @@ -1,13 +1,13 @@ # Stoplight Tasker -The __Tasker__ component runs scheduled and on-demand tasks for the Stoplight platform. +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 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 @@ -16,7 +16,7 @@ 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. +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: @@ -90,7 +90,7 @@ TASKER_REDIS_DATABASE="0" TASKER_REDIS_NAMESPACE="" ``` -Be sure to customize any variable above as needed. +Be sure to customize any of the variables above as needed. #### Starting the Service @@ -171,4 +171,4 @@ Once the Tasker component is running, you can verify the installation was succes curl -v http://localhost:9432/health ``` -If Tasker was installed and configured properly, you will receive an HTTP 200 reponse back. \ No newline at end of file +If Tasker was installed and configured properly, you will receive an HTTP 200 reponse back. diff --git a/articles/enterprise/installation-overview.md b/articles/enterprise/installation-overview.md new file mode 100644 index 0000000..97340a1 --- /dev/null +++ b/articles/enterprise/installation-overview.md @@ -0,0 +1,44 @@ +# Installation Overview + +The Stoplight Enterprise platform provides a fully-functional on-premise API +design, test, 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** 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 one +another. 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. Container-based Deployments + +The Stoplight platform can be run either with a container solution (Docker) or +natively on the Linux system. Both options are supported, however Stoplight +recommends leveraging containers where possible for ease-of-use and improved +security/sandboxing. diff --git a/articles/enterprise/maintenance/backups.md b/articles/enterprise/maintenance/backups.md index eee6ef5..5c65c4a 100644 --- a/articles/enterprise/maintenance/backups.md +++ b/articles/enterprise/maintenance/backups.md @@ -1,22 +1,37 @@ -## Gitlab +# GitLab Backup Procedures -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. +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: +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. +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). +> If you do not use the built-in backup utility, it is critical that _both_ the +> PostgreSQL database and filesystem data (including data directories and +> configuration directories) be recorded. -## Pubs +For more information, please see the official GitLab backup documentation +[here](https://docs.gitlab.com/ce/raketasks/backup_restore.html). -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. +# Pubs Backup Procedures -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`. +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: @@ -24,4 +39,5 @@ To perform a backup, run the command: 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. \ No newline at end of file +Once the backup is completed, the tarball output can be stored on redundant or +cloud storage. diff --git a/articles/enterprise/technical-requirements.md b/articles/enterprise/technical-requirements.md index afd1848..85e6fbc 100644 --- a/articles/enterprise/technical-requirements.md +++ b/articles/enterprise/technical-requirements.md @@ -2,8 +2,8 @@ Stoplight currently supports the following Linux distributions for on-premise installations: - * Ubuntu 16.04 LTS (x86_64) - * CentOS / RedHat Enterprise Linux 7 (x86_64) +* 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. @@ -15,27 +15,27 @@ A minimum of one server is required to run the Stoplight application, however, f 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 +* [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) +* [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 +* [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 +* [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 +* [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 +* [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. @@ -44,265 +44,202 @@ Please note that the above recommendations are entirely optional if your organiz 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 +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. +Each component is described in detail below. - --- +--- - ### App +### App +_Required_ - *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 - 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. +For app servers, we recommend a minimum of the following system +specifications: +* 2 CPUs +* 2GB Memory - #### System Specifications +#### Networking +The app service must be able to contact the following components: - For app servers, we recommend a minimum of the following system - specifications: +* API +* Prism +* Exporter +* GitLab CE +--- - - 2 CPUs - - 2GB Memory +### API +_Required_ - #### Networking +The API server is what the App server (described above) connects to to fetch +and persist data. +#### System Specifications - The app service must be able to contact the following components: +For API servers, we recommend co-locating with GitLab and using a minimum of +the following system specifications: +* 4 CPUs +* 8GB Memory - - API - - Prism - - Exporter - - Gitlab CE +#### Networking - --- +The API service must be able to contact the following components: +* App +* GitLab CE (+ PostgreSQL) - ### API +--- +### Prism - *Required* +_Required to run scenarios (testing and orchestration) and mocking servers._ +The Prism server runs scenario collections. - The API server is what the App server (described above) connects to to fetch - and persist data. +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 - #### System Specifications +For Prism servers, we recommend a minimum of the following system +specifications: +* 2 CPUs +* 4GB Memory - For API servers, we recommend co-locating with Gitlab and using a minimum of - the following system specifications: +#### Networking +The Prism service must be able to contact the following components: - - 4 CPUs - - 8GB Memory +* Exporter - #### Networking +--- +### Exporter - The API service must be able to contact the following components: +_Required_ +The Exporter server dereferences OAS and Swagger files to ensure all +referenced specs and external data sources are resolvable by runtime. - - App - - Gitlab CE (+ PostgreSQL) +#### System Specifications - --- +For Exporter servers, we recommend a minimum of the following system +specifications: +* 2 CPUs +* 2GB Memory - ### Prism +#### Networking +The Exporter service must be able to contact the following components: - *Required to run scenarios (testing and orchestration) and mocking servers.* +* API +--- - The Prism server runs scenario collections. +### Jobs Server (Tasker) +_Optional. Required to build and publish Hubs (technical documentation)._ - 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. +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 - #### System Specifications +For job servers, we recommend a minimum of the following system +specifications: +* 2 CPUs +* 2GB Memory - For Prism servers, we recommend a minimum of the following system - specifications: +#### Networking +The Exporter service must be able to contact the following components: - - 2 CPUs - - 4GB Memory +* API +* Hubs Server +* Redis - #### Networking +--- +### Hubs Server (Pubs) - The Prism service must be able to contact the following components: +_Optional. Required for publishing and serving documentation._ - - Exporter +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: - ### Exporter +* 2 CPUs +* 2GB Memory +#### Networking - *Required* +The Exporter service must be able to contact the following components: +* API +* Jobs Server - The Exporter server dereferences OAS and Swagger files to ensure all - referenced specs and external data sources are resolvable by runtime. +--- +### GitLab CE - #### System Specifications +_Required_ +GitLab CE is the backing datastore for all files stored within Stoplight. In +addition to storing files, GitLab CE is responsible for: - 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 +* 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 +* 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). - 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: - #### System Specifications +* 4 CPUs +* 8GB Memory +* SSD-backed redundant storage +#### Networking - 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. +The GitLab service has no outgoing network dependencies unless the Redis or +PostgreSQL sub-components are broken out separately. From 631f64e17525acfaf91777c23f78f65dcba7f11c Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Thu, 12 Apr 2018 12:32:26 -0500 Subject: [PATCH 04/30] Update API documentation with new feature flag. Fix tasker redis host-port variable config. --- articles/enterprise/components/api-overview.md | 16 ++++++++++++++++ .../enterprise/components/tasker-overview.md | 4 ++-- 2 files changed, 18 insertions(+), 2 deletions(-) diff --git a/articles/enterprise/components/api-overview.md b/articles/enterprise/components/api-overview.md index 0b4ee28..765ae0d 100644 --- a/articles/enterprise/components/api-overview.md +++ b/articles/enterprise/components/api-overview.md @@ -224,3 +224,19 @@ curl -v http://localhost:3030/health ``` If the API was installed and configured properly, you will receive an HTTP 200 response back. + +## Other Configuration Options + +### Disabling Registration + +New users can be prevented from registering with Stoplight by exposing a +`DISABLE_REGISTRATION=true` variable either through the environment or +configuration. + +If this option is enabled, new user registration requests will receive the +following error when attempting to register: + +> User registration has been temporarily disabled. Please contact your administrator. + +_Please note_, enabling this feature does not prevent existing users from +inviting new users. diff --git a/articles/enterprise/components/tasker-overview.md b/articles/enterprise/components/tasker-overview.md index f5bce8d..a6eb063 100644 --- a/articles/enterprise/components/tasker-overview.md +++ b/articles/enterprise/components/tasker-overview.md @@ -81,7 +81,7 @@ TASKER_MODE="shell" CORE_ROOT="/opt/stoplight-hub-builder" # Redis host:port to connect to (must be available before starting service) -TASKER_REDIS_HOSTPORT="redis:6379" +TASKER_REDIS_HOSTPORT="redis://redis:6379" # Redis password, if any TASKER_REDIS_PASSWORD="" # Redis database @@ -122,7 +122,7 @@ TASKER_MODE="shell" CORE_ROOT="/opt/stoplight-hub-builder" # Redis host:port to connect to (must be available before starting service) -TASKER_REDIS_HOSTPORT="redis:6379" +TASKER_REDIS_HOSTPORT="redis://redis:6379" # Redis password, if any TASKER_REDIS_PASSWORD="" # Redis database From 2c75bdb1bbae91061f1c5dcec5ae92cc25944ad4 Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Wed, 18 Apr 2018 11:16:50 -0500 Subject: [PATCH 05/30] Restructure API component documentation. --- .../enterprise/components/api-overview.md | 287 +++++++++++------- 1 file changed, 169 insertions(+), 118 deletions(-) diff --git a/articles/enterprise/components/api-overview.md b/articles/enterprise/components/api-overview.md index 765ae0d..a1a171c 100644 --- a/articles/enterprise/components/api-overview.md +++ b/articles/enterprise/components/api-overview.md @@ -1,12 +1,34 @@ # The Stoplight API -The **API** component powers the Stoplight backend, connecting the UI to the datastore and other miscellaneous Stoplight services. +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. +> The default port for the API component is TCP port **3030**. The port can be +> customized using the `PORT` configuration variable. > -> Make sure that the GitLab component is available **before** starting the API service. +> The API must be able to receive incoming connections from the following components: +> +> * User Clients (web browser or desktop application) +> * App +> +> The API must be able to make outgoing connections to the following components: +> +> * PostgreSQL +> * Redis +> * Gitlab +> * Exporter +> * Prism + +> #### Component Dependencies +> +> Make sure the following components are available **before** starting the API +> service: +> +> * PostgreSQL +> * Redis +> * Gitlab ## Installation @@ -45,7 +67,8 @@ If you do not see a version starting `v8.9`, please contact Stoplight support fo #### Setting up the Package Repository -You can do this by copying-and-pasting the contents below into a terminal: +You can setup the Stoplight package repo by copying-and-pasting the contents +below into a terminal: ```bash # expose credentials to environment first @@ -68,13 +91,14 @@ EOF #### Installing the API Package -Once the repository is configured properly, you can install the API component using the command: +Once the repository is configured properly, you can install the API component +using the command: ```bash sudo yum install stoplight-api -y ``` -### Docker Installation +### Docker To install the API component with Docker, run the command below: @@ -83,57 +107,148 @@ docker pull quay.io/stoplight/api ``` > Note, if the system you are using has not already authenticated with the -> Stoplight container registry, you will be prompted for credentials +> Stoplight container registry, you will be prompted for credentials. -## Configuring and Running +## Configuration -To configure the Stoplight API component, you will need to provide connection details to the other necessary Stoplight components. +To configure the Stoplight API component, you will need to provide runtime +values and connection details to the other necessary Stoplight components. The +API can be configured either by configuration file or through the environment. -### Package-based Installations +> The same configuration variables can be used regardless of installation type +> (container or package-based). -#### Configuring the Service +### RPM Package -The Stoplight API configuration is located at the location: +The Stoplight API configuration file is located at the location: ```bash /etc/stoplight-api/stoplight-api.cfg ``` -The above file should contain the following entries: +Be sure to customize any variables as needed to match your environment before +starting the API service. + +> Any changes to the API configuration require a service restart in order to +> take effect. + +### Docker + +To expose configuration variables to the Docker runtime, either write them to a +file and use the `--env-file` argument: ```bash -# Secret used to encrypt cookies and other secrets used by the Stoplight API. -SIGN_SECRET="CHANGE_ME_TO_SOMETHING_RANDOM" +cat <api-env-vars +SL_APP_HOST="..." +... +EOF -# 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" +docker run --env-file api-env-vars ... ``` -> Please note that the `SIGN_SECRET` environment variable must remain static between service restarts +Or you can expose them one at a time with the `-e` flag: -Be sure to customize any of the variables above as needed. +```bash +docker run -e SL_APP_HOST=https://stoplight.example.com ... +``` -#### Starting the Service +### Variables + +#### SIGN_SECRET + +The `SIGN_SECRET` variable is used to encrypt session cookies and other secrets +used by the Stoplight API. + +``` +SIGN_SECRET="CHANGE_ME_TO_SOMETHING_RANDOM" +``` + +There is no minimum or maximum character requirement, however Stoplight +recommends using a random string more than 32 characters in length for +production environments. + +> Please note that the `SIGN_SECRET` configuration variable must remain static +> between service restarts + +#### POSTGRES_URL + +The `POSTGRES_URL` variable is the connection URI for the PostgreSQL database +shared with Gitlab. + +``` +POSTGRES_URL="postgres://username:password@example.com:5432/database_name" +``` + +#### SL_COOKIE_DOMAIN + +The `SL_COOKIE_DOMAIN` variable is the name of the top-level domain that +Stoplight is being served from. + +``` +SL_COOKIE_DOMAIN="example.com" +``` + +For example, if Stoplight is being served from the `stoplight.example.com` +domain, set this variable to `example.com`. + +#### SL_APP_HOST + +The `SL_APP_HOST` variable is the full URL to the Stoplight app component. + +``` +SL_APP_HOST="http://localhost:3030" +``` + +#### SL_API_HOST + +The `SL_API_HOST` variable is the full URL to this (the Stoplight API) component. + +``` +SL_API_HOST="http://localhost:3030" +``` + +#### SL_EXPORTER_HOST + +The `SL_EXPORTER_HOST` variable is the full URL to the Stoplight exporter component. + +``` +SL_EXPORTER_HOST="http://localhost:3031" +``` + +#### SL_GITLAB_HOST + +The `SL_GITLAB_HOST` variable is the full URL to the Stoplight GitLab instances HTTP port. + +``` +SL_GITLAB_HOST="http://localhost:8080" +``` + +#### SL_REDIS_URL + +The `SL_REDIS_URL` variable is the full URL to a Redis instance. + +``` +SL_REDIS_URL="redis://:password@example.com:6379" +``` + +#### DISABLE_REGISTRATION + +The `DISABLE_REGISTRATION` variable can be used to prevent new users from +registering with Stoplight. Enabling this feature does not prevent existing +users from inviting new users. + +``` +DISABLE_REGISTRATION=false +``` + +If this option is set to `true`, new user registration requests will receive the +following error when attempting to register: + +> User registration has been temporarily disabled. Please contact your administrator. + +## Running + +### RPM Package To start the API server, run the command: @@ -147,96 +262,32 @@ Once started, you can see the status of the service using the command: 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 <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 +### Docker 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 + --restart on-failure \ + -p 3030: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. +> Remember to set any necessary environment variables + +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: +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 +# remember to update the scheme, host, and port here to match your installation curl -v http://localhost:3030/health ``` -If the API was installed and configured properly, you will receive an HTTP 200 response back. - -## Other Configuration Options - -### Disabling Registration - -New users can be prevented from registering with Stoplight by exposing a -`DISABLE_REGISTRATION=true` variable either through the environment or -configuration. - -If this option is enabled, new user registration requests will receive the -following error when attempting to register: - -> User registration has been temporarily disabled. Please contact your administrator. - -_Please note_, enabling this feature does not prevent existing users from -inviting new users. +If the API was installed and configured properly, you will receive an `HTTP 200` +response back. From fc9bcb0551e15cfae529a4347c8fc194c4972533 Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Wed, 18 Apr 2018 11:30:08 -0500 Subject: [PATCH 06/30] Update app with latest changes. --- .../enterprise/components/api-overview.md | 4 +- .../enterprise/components/app-overview.md | 200 ++++++++++-------- 2 files changed, 116 insertions(+), 88 deletions(-) diff --git a/articles/enterprise/components/api-overview.md b/articles/enterprise/components/api-overview.md index a1a171c..02bdf7d 100644 --- a/articles/enterprise/components/api-overview.md +++ b/articles/enterprise/components/api-overview.md @@ -32,9 +32,7 @@ datastore and other miscellaneous Stoplight services. ## Installation -The Stoplight API can be installed with Docker or via RPM package. - -> Before starting, be sure to complete the GitLab installation. +The Stoplight API can be installed with Docker or RPM package. ### RPM Package diff --git a/articles/enterprise/components/app-overview.md b/articles/enterprise/components/app-overview.md index e64afee..2ada5cb 100644 --- a/articles/enterprise/components/app-overview.md +++ b/articles/enterprise/components/app-overview.md @@ -1,24 +1,32 @@ # The Stoplight App -The **app** component powers the Stoplight user interface by connecting users to the Stoplight API and other services. +The **App** component powers the Stoplight user interface by connecting users to the Stoplight API and other services. -> ### Requirements +> #### Networking Details > -> #### Storage +> The default port for the App component is TCP port **3100**. The port can be +> customized using the `PORT` configuration variable. > -> There are no storage requirements for this component. +> The App must be able to receive **incoming** connections from the following components: > -> #### Networking +> * User Clients (web browser or desktop application) > -> The default port for the app component is TCP port **3100**. The port can be customized using the `PORT` environment variable. +> The App must be able to make **outgoing** connections to the following components: > -> _Be sure that both API and GitLab components are available **before** starting the app service_ +> * API +> * Prism +> * Exporter + +> #### Component Dependencies +> +> Make sure the following components are available **before** starting the App +> service: +> +> * API ## Installation -The Stoplight app can be installed with Docker or via RPM package. - -> Before starting, be sure to complete the GitLab and API installations. +The Stoplight App can be installed with Docker or RPM package. ### RPM Package @@ -80,7 +88,7 @@ Once the repository is configured properly, you can install the app component us sudo yum install stoplight-app -y ``` -### Docker Installation +### Docker To install the app component with Docker, run the command below: @@ -90,50 +98,112 @@ 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 +## Configuration -To configure the Stoplight app component, you will need to provide connection details to the other necessary Stoplight components. +To configure the Stoplight App component, you will need to provide connection +details to the other necessary Stoplight components. The API can be configured +either by configuration file or through the environment. -### Package-based Installations +> The same configuration variables can be used regardless of installation type +> (container or package-based). -#### Configuring the Service +### RPM Package -The Stoplight app configuration is located at the location: +The Stoplight App configuration is located at the location: ```bash /etc/stoplight-app/stoplight-app.cfg ``` -The above file should contain the following entries: +Be sure to customize any variables as needed to match your environment before +starting the API service. + +> Any changes to the API configuration require a service restart in order to +> take effect. + +### Docker + +To expose configuration variables to the Docker runtime, either write them to a +file and use the `--env-file` argument: ```bash -# SL_APP_HOST is the public-facing URL for the stoplight application +cat <app-env-vars +SL_API_HOST="..." +... +EOF + +docker run --env-file app-env-vars ... +``` + +Or you can expose them one at a time with the `-e` flag: + +```bash +docker run -e SL_API_HOST=https://stoplight-api.example.com ... +``` + +### Variables + +#### SL_APP_HOST + +The `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 + +The `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 + +The `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 + +The `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 + +The `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 + +The `SL_PUBS_HOST` variable 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 + +The `SL_PUBS_INGRESS` variable is the URL to the Stoplight Pubs instance admin API: + +``` SL_PUBS_INGRESS="https://pubs.example.com:9098" ``` -Be sure to customize any of the variables above as needed. +## Running -#### Starting the Service +### RPM Package -To start the app server, run the command: +To start the App server, run the command: ```bash sudo systemctl start stoplight-app @@ -145,76 +215,36 @@ Once started, you can see the status of the service using the command: sudo systemctl status stoplight-app ``` -### Docker Installations +### Docker -#### 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 <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: +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 + --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. +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. +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: +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. +> Remember to replace 'example.com' above with the domain used to install the +> Stoplight application From fe830a22c337bc4776d4f69cc8def53a6921a8bc Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Wed, 18 Apr 2018 12:51:22 -0500 Subject: [PATCH 07/30] Update exporter --- .../components/exporter-overview.md | 157 ++++++++++-------- 1 file changed, 88 insertions(+), 69 deletions(-) diff --git a/articles/enterprise/components/exporter-overview.md b/articles/enterprise/components/exporter-overview.md index 7e6e0d1..d706096 100644 --- a/articles/enterprise/components/exporter-overview.md +++ b/articles/enterprise/components/exporter-overview.md @@ -1,12 +1,27 @@ # The Stoplight Exporter -The **Exporter** component de-references JSON specifications to ensure all referenced files and external data sources are resolved when needed. +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 default port for the Exporter component is TCP port **3031**. The port can +> be customized using the `PORT` configuration variable. > -> The Exporter service is stateless and relies on no other components for operation. +> The Exporter must be able to receive incoming connections from the following components: +> +> * User Clients (web browser or desktop application) +> * App +> * API +> * Prism +> +> The Exporter must be able to make outgoing connections to the following components: +> +> * API + +> #### Component Dependencies +> +> The Exporter is stateless, and has no component dependencies. ## Installation @@ -72,7 +87,7 @@ Once the repository is configured properly, you can install the Exporter compone sudo yum install stoplight-exporter -y ``` -### Docker Installation +### Docker To install the API component with Docker, run the command below: @@ -80,73 +95,34 @@ To install the API component with Docker, run the command below: docker pull quay.io/stoplight/exporter ``` -> Note, if you have not already authenticated with the Stoplight container registry, you will be prompted for credentials +> Note, if you have not already authenticated with the Stoplight container +> registry, you will be prompted for credentials -## Configuring and Running +## Configuration -To configure the Stoplight Exporter component, you will need to provide connection details to the other necessary Stoplight components. +To configure the Stoplight Exporter component, you will need to provide runtime +values and connection details to the other necessary Stoplight components. The +Exporter can be configured either by configuration file or through the +environment. -### Package-based Installations +> The same configuration variables can be used regardless of installation type +> (container or package-based). -#### Configuring the Service +### RPM Package -The Stoplight API configuration is located at the location: +The Stoplight Exporter configuration is located at the location: ```bash /etc/stoplight-exporter/stoplight-exporter.cfg ``` -The above file should contain the following entries: +Be sure to customize any variables as needed to match your environment before +starting the API service. -```bash -# SL_APP_HOST is the public-facing URL for the stoplight application -SL_APP_HOST="https://stoplight.example.com" +> Any changes to the API configuration require a service restart in order to +> take effect. -# 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 of the variables 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" -``` +### Docker To expose these to the Docker runtime, either write them to a file and use the `--env-file` argument: @@ -165,27 +141,70 @@ Alternatively, you can expose them one at a time with the `-e` flag: docker run -e SL_APP_HOST=https://stoplight.example.com ... ``` -#### Starting the Container +### Variables -To start the API container, run the command: +#### SL_APP_HOST + +The `SL_APP_HOST` is the public-facing URL for the Stoplight App. + +``` +SL_APP_HOST="https://stoplight.example.com" +``` + +#### SL_API_HOST + +The `SL_API_HOST` variable is the URL to the Stoplight API. + +``` +SL_API_HOST="https://stoplight-api.internal.example.com:3030" +``` + +#### SL_EXPORTER_HOST + +The `SL_EXPORTER_HOST` variable is the full URL to the Stoplight Exporter instance. + +SL_EXPORTER_HOST="https://stoplight-exporter.internal.example.com" + +## Running + +### RPM Package + +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 + +To start the Exporter container, run the command: ```bash docker run \ - --restart on-failure \ - --env-file exporter-env \ - -p 2345:3031 \ - quay.io/stoplight/exporter:latest + --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. +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: +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 +# be sure to update the scheme, host, and port 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. +If the Exporter was installed and configured properly, you will receive an `HTTP 200` reponse back. From 2d7dfed5c769bf51063131d35b0485a42e24156e Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Wed, 18 Apr 2018 13:00:03 -0500 Subject: [PATCH 08/30] Fix some typos. Update configuration layout. --- .../enterprise/components/api-overview.md | 68 +++++++++--------- .../enterprise/components/app-overview.md | 68 +++++++++--------- .../components/exporter-overview.md | 72 ++++++++++--------- 3 files changed, 105 insertions(+), 103 deletions(-) diff --git a/articles/enterprise/components/api-overview.md b/articles/enterprise/components/api-overview.md index 02bdf7d..f3d4a7e 100644 --- a/articles/enterprise/components/api-overview.md +++ b/articles/enterprise/components/api-overview.md @@ -116,40 +116,6 @@ API can be configured either by configuration file or through the environment. > The same configuration variables can be used regardless of installation type > (container or package-based). -### RPM Package - -The Stoplight API configuration file is located at the location: - -```bash -/etc/stoplight-api/stoplight-api.cfg -``` - -Be sure to customize any variables as needed to match your environment before -starting the API service. - -> Any changes to the API configuration require a service restart in order to -> take effect. - -### Docker - -To expose configuration variables to the Docker runtime, either write them to a -file and use the `--env-file` argument: - -```bash -cat <api-env-vars -SL_APP_HOST="..." -... -EOF - -docker run --env-file api-env-vars ... -``` - -Or you can expose them one at a time with the `-e` flag: - -```bash -docker run -e SL_APP_HOST=https://stoplight.example.com ... -``` - ### Variables #### SIGN_SECRET @@ -244,6 +210,40 @@ following error when attempting to register: > User registration has been temporarily disabled. Please contact your administrator. +### RPM Package + +The Stoplight API configuration file is located at the location: + +```bash +/etc/stoplight-api/stoplight-api.cfg +``` + +Be sure to customize any variables as needed to match your environment before +starting the API service. + +> Any changes to the API configuration require a service restart in order to +> take effect. + +### Docker + +To expose configuration variables to the Docker runtime, either write them to a +file and use the `--env-file` argument: + +```bash +cat <api-env-vars +SL_APP_HOST="..." +... +EOF + +docker run --env-file api-env-vars ... +``` + +Or you can expose them one at a time with the `-e` flag: + +```bash +docker run -e SL_APP_HOST=https://stoplight.example.com ... +``` + ## Running ### RPM Package diff --git a/articles/enterprise/components/app-overview.md b/articles/enterprise/components/app-overview.md index 2ada5cb..6c6d645 100644 --- a/articles/enterprise/components/app-overview.md +++ b/articles/enterprise/components/app-overview.md @@ -107,40 +107,6 @@ either by configuration file or through the environment. > The same configuration variables can be used regardless of installation type > (container or package-based). -### RPM Package - -The Stoplight App configuration is located at the location: - -```bash -/etc/stoplight-app/stoplight-app.cfg -``` - -Be sure to customize any variables as needed to match your environment before -starting the API service. - -> Any changes to the API configuration require a service restart in order to -> take effect. - -### Docker - -To expose configuration variables to the Docker runtime, either write them to a -file and use the `--env-file` argument: - -```bash -cat <app-env-vars -SL_API_HOST="..." -... -EOF - -docker run --env-file app-env-vars ... -``` - -Or you can expose them one at a time with the `-e` flag: - -```bash -docker run -e SL_API_HOST=https://stoplight-api.example.com ... -``` - ### Variables #### SL_APP_HOST @@ -199,6 +165,40 @@ The `SL_PUBS_INGRESS` variable is the URL to the Stoplight Pubs instance admin A SL_PUBS_INGRESS="https://pubs.example.com:9098" ``` +### RPM Package + +The Stoplight App configuration is located at the location: + +```bash +/etc/stoplight-app/stoplight-app.cfg +``` + +Be sure to customize any variables as needed to match your environment before +starting the API service. + +> Any changes to the API configuration require a service restart in order to +> take effect. + +### Docker + +To expose configuration variables to the Docker runtime, either write them to a +file and use the `--env-file` argument: + +```bash +cat <app-env-vars +SL_API_HOST="..." +... +EOF + +docker run --env-file app-env-vars ... +``` + +Or you can expose them one at a time with the `-e` flag: + +```bash +docker run -e SL_API_HOST=https://stoplight-api.example.com ... +``` + ## Running ### RPM Package diff --git a/articles/enterprise/components/exporter-overview.md b/articles/enterprise/components/exporter-overview.md index d706096..26137e5 100644 --- a/articles/enterprise/components/exporter-overview.md +++ b/articles/enterprise/components/exporter-overview.md @@ -89,7 +89,7 @@ sudo yum install stoplight-exporter -y ### Docker -To install the API component with Docker, run the command below: +To install the Exporter component with Docker, run the command below: ```bash docker pull quay.io/stoplight/exporter @@ -108,39 +108,6 @@ environment. > The same configuration variables can be used regardless of installation type > (container or package-based). -### RPM Package - -The Stoplight Exporter configuration is located at the location: - -```bash -/etc/stoplight-exporter/stoplight-exporter.cfg -``` - -Be sure to customize any variables as needed to match your environment before -starting the API service. - -> Any changes to the API configuration require a service restart in order to -> take effect. - -### Docker - -To expose these to the Docker runtime, either write them to a file and use the `--env-file` argument: - -```bash -cat <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 ... -``` - ### Variables #### SL_APP_HOST @@ -163,13 +130,48 @@ SL_API_HOST="https://stoplight-api.internal.example.com:3030" The `SL_EXPORTER_HOST` variable is the full URL to the Stoplight Exporter instance. +``` SL_EXPORTER_HOST="https://stoplight-exporter.internal.example.com" +``` + +### RPM Package + +The Stoplight Exporter configuration is located at the location: + +```bash +/etc/stoplight-exporter/stoplight-exporter.cfg +``` + +Be sure to customize any variables as needed to match your environment before +starting the Exporter service. + +> Any changes to the Exporter configuration require a service restart in order +> to take effect. + +### Docker + +To expose these to the Docker runtime, either write them to a file and use the `--env-file` argument: + +```bash +cat <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 ... +``` ## Running ### RPM Package -To start the API server, run the command: +To start the Exporter server, run the command: ```bash sudo systemctl start stoplight-exporter From 012fff8fc6169ed997e605986a7e8eccbcc3c644 Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Wed, 18 Apr 2018 13:04:56 -0500 Subject: [PATCH 09/30] Update hub builder page --- .../components/hub-builder-overview.md | 48 +++++++++++-------- 1 file changed, 29 insertions(+), 19 deletions(-) diff --git a/articles/enterprise/components/hub-builder-overview.md b/articles/enterprise/components/hub-builder-overview.md index 9cce0d7..044ec3d 100644 --- a/articles/enterprise/components/hub-builder-overview.md +++ b/articles/enterprise/components/hub-builder-overview.md @@ -1,17 +1,16 @@ # The Stoplight Hub Builder -The __Hub Builder__ component converts a Stoplight Hub into a standalone static HTML website, suitable for viewing and distribution. +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 +> #### Networking Details > > The Hub Builder does not have a listening service or external port configurations. +> #### Component Dependencies +> +> The Hub Builder is started in an ad-hoc manner by **Tasker**, and does not have +> any component dependencies. + ## Installation The Stoplight Hub Builder can be installed with Docker or via RPM package. @@ -70,32 +69,43 @@ EOF #### Installing the Hub Builder Package -Once the repository is configured properly, you can install the Hub Builder component using the command: +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 +### Docker -To install the API component with Docker, run the command below: +To install the Hub Builder 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 +> Note, if you have not already authenticated with the Stoplight container +> registry, you will be prompted for credentials -## Configuring and Running +## Configuration -### Package-based Installations +The Hub Builder component is an ad-hoc processing job, and does not have any +required configuration that is not provided by the parent process (typically +Tasker). -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. +## Running -To ensure Tasker is able to run the Hub Builder package correctly, be sure to set Tasker to `shell` mode in the Tasker configuration. +## RPM Package -### 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. -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. -To ensure Tasker is able to run the Hub Builder container correctly, be sure to set Tasker to `docker` mode in the Tasker configuration. \ No newline at end of file +### Docker + +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 container. From 0793b26295ec3fa3e2f637924b602aa225071407 Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Wed, 18 Apr 2018 13:17:47 -0500 Subject: [PATCH 10/30] Update prism article --- .../enterprise/components/prism-overview.md | 186 ++++++++++++++---- 1 file changed, 146 insertions(+), 40 deletions(-) diff --git a/articles/enterprise/components/prism-overview.md b/articles/enterprise/components/prism-overview.md index 7908758..e0e2d1f 100644 --- a/articles/enterprise/components/prism-overview.md +++ b/articles/enterprise/components/prism-overview.md @@ -1,10 +1,29 @@ -# Stoplight Prism +# 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). +> +> Prism must be able to receive incoming connections from the following components: +> +> * User Clients (web browser or desktop application) +> * App +> * API +> +> Prism must be able to make outgoing connections to the following components: +> +> * Exporter + +> #### Component Dependencies +> +> Make sure the following components are available **before** starting the API +> service: +> +> * PostgreSQL +> * Redis +> * Gitlab ## Installation @@ -12,9 +31,13 @@ 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. +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: +#### Setting up the Package Repository + +You can setup the Stoplight package repo by copying-and-pasting the contents +below into a terminal: ```bash # expose credentials to environment first @@ -35,13 +58,15 @@ EOF > Be sure to set your repository credentials before issuing the `cat` command +#### Installing the Prism Package + Once the repository is configured properly, you can install the Pubs component using the command: ```bash sudo yum install prism -y ``` -### Docker Installation +### Docker To install the Pubs component with Docker, run the command below: @@ -49,58 +74,118 @@ To install the Pubs component with Docker, run the command below: 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 +> Note, if you have not already authenticated with the Stoplight container +> registry, you will be prompted for credentials. -## Configuring and Running +## Configuration -To configure the Prism component, you will need to provide runtime settings and connection details to the Stoplight App, API, and Exporter. +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 +### Variables -### Package-based Installations +#### SL_API_HOST -#### Configuring the Service +The `SL_API_HOST` variable is the full URL to the Stoplight API. -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 +#### SL_HOST + +The `SL_HOST` variable is the full URL to the Stoplight App. + +``` +SL_HOST="http://localhost:3100" +``` + +#### SL_EXPORTER_HOST + +The `SL_EXPORTER_HOST` variable is the URL to the Stoplight Exporter. + +``` +SL_EXPORTER_HOST="http://localhost:3031" +``` + +#### ENV_NAME + +The `ENV_NAME` variable is a flag noting the environment level. + +``` ENV_NAME="production" +``` + +> `ENV_NAME` should be left as `production` unless instructed otherwise by the +> Stoplight Support staff. + +#### MAX_QUEUE_SIZE + +The `MAX_QUEUE_SIZE` variable denotes the internal queue size used to service +requests. + +``` 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 +servicing requests. + +``` MAX_WORKERS=25 +``` + +> `MAX_WORKERS` should be left as `25` unless instructed otherwise by the +> Stoplight Support staff. + +#### PRISM_LOG_LEVEL + +The `PRISM_LOG_LEVEL` variable denotes the log level of the Prism process. + +``` PRISM_LOG_LEVEL="ERROR" ``` -Be sure to customize any of the variables above as needed. +> `PRISM_LOG_LEVEL` should be left as `ERROR` unless instructed otherwise by the +> Stoplight Support staff. -#### Starting the Service +### RPM Package -To start the Prism server, run the command: +The Prism configuration file is located at the location: ```bash -sudo systemctl start prism +/etc/prism/prism.cfg ``` -Once started, you can see the status of the service using the command: +Be sure to customize any variables as needed to match your environment before +starting the Prism service. -```bash -sudo systemctl status prism -``` +> Any changes to the Prism configuration require a service restart in order to +> take effect. -### Docker Installations +### Docker -#### 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. +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: @@ -119,23 +204,43 @@ Alternatively, you can expose them one at a time with the `-e` flag: docker run -e SL_API_HOST=api.stoplight.example.com ... ``` -#### Starting the Container +## Running + +### RPM Package + +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 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 + --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. +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`): +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 @@ -144,4 +249,5 @@ 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. +If Prism was installed and configured properly, you will receive an `HTTP 200` +response back. From b99a75e162ebe01ce3edf1fb4e9f80b92030c344 Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Wed, 18 Apr 2018 14:18:58 -0500 Subject: [PATCH 11/30] Update pubs --- .../enterprise/components/pubs-overview.md | 258 ++++++++++++------ 1 file changed, 175 insertions(+), 83 deletions(-) diff --git a/articles/enterprise/components/pubs-overview.md b/articles/enterprise/components/pubs-overview.md index 87be4e6..de3bda1 100644 --- a/articles/enterprise/components/pubs-overview.md +++ b/articles/enterprise/components/pubs-overview.md @@ -1,10 +1,24 @@ -# Stoplight Pubs +# 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). +> The default ports for the Pubs component are TCP ports **8080** (HTTP), +> **8443** (HTTPS), and **9098** (HTTPS optional). All ports can be customized. +> +> Pubs must be able to receive incoming connections from the following components: +> +> * User Clients (on the public-facing ports, which default to 8080 and 8443) +> * API (on the private admin port, which defaults to 9098) +> +> Pubs must be able to make outgoing connections to the following components: +> +> * API + +> #### Component Dependencies +> +> Pubs has no component dependencies. ## Installation @@ -12,9 +26,13 @@ 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. +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: +#### Setting up the Package Repository + +You can setup the Stoplight package repo by copying-and-pasting the contents +below into a terminal: ```bash # expose credentials to environment first @@ -35,7 +53,10 @@ 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: +#### Installing the Pubs Package + +Once the repository is configured properly, you can install the Pubs component +using the command: ```bash sudo yum install pubs -y @@ -49,60 +70,157 @@ To install the Pubs component with Docker, run the command below: docker pull quay.io/stoplight/pubs ``` -> Note, if you have not already authenticated with the Stoplight container registry, you will be prompted for credentials +> Note, if you have not already authenticated with the Stoplight container +> registry, you will be prompted for credentials -## Configuring and Running +## Configuration -To configure the Pubs component, you will need to provide runtime settings and connection details to the Stoplight Pubs. +To configure the Pubs component, you will need to provide connection details and +runtime settings. -> Pubs uses the Stoplight API for authentication if using SSO within your published documentation, however it is not required +### Variables -### Package-based Installations +#### http_bind -#### Configuring the Service +The `http_bind` variable denotes the bind address/port to use when serving HTTP +traffic. -The Pubs configuration is located at: +```yaml +http_bind: "127.0.0.1:8080" +``` + +#### https_bind + +The `https_bind` variable denotes the bind address/port to use when serving +HTTPS traffic. + +```yaml +https_bind: "127.0.0.1:8443" +``` + +#### ssl_enabled + +The `ssl_enabled` variable denotes whether SSL should be enabled when serving +hub requests. + +```yaml +ssl_enabled: yes +``` + +> If `ssl_enabled` is set to `true`, then HTTP requests will automatically be +> redirected to HTTPS. + +#### admin_bind + +The `admin_bind` variable denotes the address/port to bind to when serving the +admin API. + +```yaml +admin_bind: "127.0.0.1:9098" +``` + +#### admin_ssl_enabled + +The `admin_ssl_enabled` variable denotes whether the admin API should accept +connections over HTTPS (as opposed to HTTP). + +```yaml +admin_ssl_enabled: no +``` + +#### admin_ssl_cert_path + +The `admin_ssl_cert_path` variable is the path to the SSL certificate to use +when serving TLS over the admin API. + +```yaml +admin_ssl_cert_path: /path/to/cert +``` + +> This configuration option has no effect if `admin_ssl_enabled` is not set to +> `true` + +#### admin_ssl_key_path + +The `admin_ssl_key_path` variable is the path to the SSL key (matching the +`admin_ssl_cert_path` option) to use when serving TLS over the admin API. + +```yaml +admin_ssl_key_path: /path/to/key +``` + +> This configuration option has no effect if `admin_ssl_enabled` is not set to +> `true` + +#### admin_ip_whitelist + +The `admin_ip_whitelist` variable is a list representing IP addresses that +should be allowed to connect to the admin API. + +```yaml +admin_ip_whitelist: + - 127.0.0.1 +``` + +> If `admin_ip_whitelist` is not set, all IP addresses will be allowed to +> connect to the API. + +#### data_dir + +The `data_dir` variable is the directory to use when storing builds, build +metadata, and the pubs sqlite database. + +```yaml +data_dir: /var/lib/pubs +``` + +#### static_ssl_domains + +The `static_ssl_domains` variable can be used to serve static SSL certificates +for specific domain requests. + +```yaml +static_ssl_domains: + - domain: "*.example.com" + cert-path: /path/to/example_com/certificate + key-path: /path/to/example_com/key +``` + +> Include a leading star (`*`) in the domain if the certificate is wildcarded +> (ie, `*.example.com` for a wildcard certificate on the `example.com` domain). + +### RPM Package + +The Pubs default configuration is located at the path: ```bash /etc/pubs/pubs.yml ``` -The above file should contain the following entries: +Be sure to customize any variables as needed to match your environment before +starting the Pubs service. + +> Any changes to the Pubs configuration require a service restart in order to +> take effect. + +### Docker + +The Pubs configuration can be mounted into a Docker container. As an example, if +a Pubs configuration file is located on the host system at the path: ```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 +/data/pubs.yml ``` -Be sure to customize any of the variables above as needed. +This file can be mounted into the running Pubs container using the `-v` argument. -#### Starting the Service +```bash +docker run -v /data/pubs.yml:/etc/pubs/pubs.yml ... +``` + +## Running + +### RPM Package To start the Pubs server, run the command: @@ -118,54 +236,27 @@ 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 <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 + --restart on-failure \ + -v /path/to/pubs.yml:/etc/pubs/pubs.yml \ + -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. +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`): +Once the Pubs service 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 @@ -173,4 +264,5 @@ 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. +If Pubs was installed and configured properly, you will receive an `HTTP 200` +response back. From ff09e05e5658e3a2cf2d1884b9a65b748d5b9607 Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Wed, 18 Apr 2018 14:33:40 -0500 Subject: [PATCH 12/30] Update tasker --- .../enterprise/components/api-overview.md | 2 +- .../enterprise/components/tasker-overview.md | 219 +++++++++++------- 2 files changed, 142 insertions(+), 79 deletions(-) diff --git a/articles/enterprise/components/api-overview.md b/articles/enterprise/components/api-overview.md index f3d4a7e..ddef664 100644 --- a/articles/enterprise/components/api-overview.md +++ b/articles/enterprise/components/api-overview.md @@ -212,7 +212,7 @@ following error when attempting to register: ### RPM Package -The Stoplight API configuration file is located at the location: +The Stoplight API configuration file is located at the path: ```bash /etc/stoplight-api/stoplight-api.cfg diff --git a/articles/enterprise/components/tasker-overview.md b/articles/enterprise/components/tasker-overview.md index a6eb063..8fa70f2 100644 --- a/articles/enterprise/components/tasker-overview.md +++ b/articles/enterprise/components/tasker-overview.md @@ -1,4 +1,4 @@ -# Stoplight Tasker +# Tasker The **Tasker** component runs scheduled and on-demand tasks for the Stoplight platform. @@ -10,15 +10,40 @@ The **Tasker** component runs scheduled and on-demand tasks for the Stoplight pl > > Tasker requires a Redis instance to be available when starting. Be sure to setup Redis before installing Tasker. +> #### Networking Details +> +> The default port for the Tasker component is TCP port **9432**. This port can +> be customzied via configuration variable. +> +> Tasker must be able to receive incoming connections from the following components: +> +> * API +> +> Tasker must be able to make outgoing connections to the following components: +> +> * API +> * Redis + +> #### Component Dependencies +> +> Make sure the following components are available **before** starting the Tasker +> service: +> +> * Redis + ## 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. +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: +#### Setting up the Package Repository + +You can setup the Stoplight package repo by copying-and-pasting the contents +below into a terminal: ```bash # expose credentials to environment first @@ -39,13 +64,15 @@ EOF > Be sure to set your repository credentials before issuing the `cat` command +#### Installing the Tasker Package + Once the repository is configured properly, you can install the Tasker component using the command: ```bash sudo yum install tasker -y ``` -### Docker Installation +### Docker To install the Tasker component with Docker, run the command below: @@ -53,15 +80,84 @@ To install the Tasker component with Docker, run the command below: docker pull quay.io/stoplight/tasker ``` -> Note, if you have not already authenticated with the Stoplight container registry, you will be prompted for credentials +> Note, if you have not already authenticated with the Stoplight container +> registry, you will be prompted for credentials. -## Configuring and Running +## Configuration -To configure the Tasker component, you will need to provide runtime settings and connection details for a running Redis instance. +To configure the Tasker component, you will need to provide runtime settings and +connection details for a running Redis instance. -### Package-based Installations +### Variables -#### Configuring the Service +#### TASKER_HTTP_BIND + +The `TASKER_HTTP_BIND` variable is the bind address and port used for serving +the Tasker HTTP API. + +``` +TASKER_HTTP_BIND="localhost:9432" +``` + +#### TASKER_MODE + +The `TASKER_MODE` variable is the operation mode that Tasker should use when +executing jobs. Valid values for `TASKER_MODE` are `docker` and `shell`. + +``` +TASKER_MODE="shell" +``` + +> If not specified, Tasker defaults to using `docker` mode. + +#### CORE_ROOT + +The `CORE_ROOT` denotes the absolutel path to stoplight-hub-builder package root. + +``` +CORE_ROOT="/opt/stoplight-hub-builder" +``` + +> This variable is only required when running in `shell` mode. + +#### TASKER_REDIS_HOSTPORT + +The `TASKER_REDIS_HOSTPORT` variable denotes the Redis instance host:port to connect to. + +``` +TASKER_REDIS_HOSTPORT="redis://redis:6379" +``` + +> Redis must be available before starting service. + +#### TASKER_REDIS_PASSWORD + +The `TASKER_REDIS_PASSWORD` variable is an optional password to use when +connecting to the Redis instance. + +``` +TASKER_REDIS_PASSWORD="" +``` + +#### TASKER_REDIS_DATABASE + +The `TASKER_REDIS_DATABASE` variable is the Redis database used by Tasker for +storing job state. + +``` +TASKER_REDIS_DATABASE="0" +``` + +#### TASKER_REDIS_NAMESPACE + +The `TASKER_REDIS_NAMESPACE` variable is the Redis namespace used by Tasker for +storing job state. + +``` +TASKER_REDIS_NAMESPACE="tasker" +``` + +### RPM Package The Tasker configuration is located at: @@ -69,69 +165,16 @@ The Tasker configuration is located at: /etc/tasker/tasker.cfg ``` -The above file should contain the following entries: +Be sure to customize any variables as needed to match your environment before +starting the Tasker service. -```bash -# Tasker HTTP bind address (host:port) -TASKER_HTTP_BIND="localhost:9432" +> Any changes to the Tasker configuration require a service restart in order to +> take effect. -# 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" +### Docker -# Redis host:port to connect to (must be available before starting service) -TASKER_REDIS_HOSTPORT="redis://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 of the variables 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://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: +To expose these to the Docker runtime, either write them to a file and use the +`--env-file` argument: ```bash cat <tasker-env-vars @@ -148,27 +191,47 @@ Alternatively, you can expose them one at a time with the `-e` flag: docker run -e TASKER_HTTP_BIND=0.0.0.0:9432 ... ``` -#### Starting the Container +## Running + +### RPM Package + +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 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 + --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. +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: +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 +# remember to update the scheme, host, and port here to match your installation curl -v http://localhost:9432/health ``` -If Tasker was installed and configured properly, you will receive an HTTP 200 reponse back. +If Tasker was installed and configured properly, you will receive an `HTTP 200` +reponse back. From eb53cf838f137929dd3cb30fb7884f5de3989c2a Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Wed, 18 Apr 2018 14:34:31 -0500 Subject: [PATCH 13/30] Remove extra networking section --- articles/enterprise/components/tasker-overview.md | 8 -------- 1 file changed, 8 deletions(-) diff --git a/articles/enterprise/components/tasker-overview.md b/articles/enterprise/components/tasker-overview.md index 8fa70f2..d090557 100644 --- a/articles/enterprise/components/tasker-overview.md +++ b/articles/enterprise/components/tasker-overview.md @@ -2,14 +2,6 @@ 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. - > #### Networking Details > > The default port for the Tasker component is TCP port **9432**. This port can From d1980710e227f8e8c7a57185d96d0b158acb63dc Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Wed, 18 Apr 2018 14:51:29 -0500 Subject: [PATCH 14/30] Remove component information from tech requirements section. Reorganize tech requirements article. --- .../enterprise/components/app-overview.md | 5 +- .../enterprise/components/gitlab-overview.md | 14 + .../enterprise/components/prism-overview.md | 5 + .../enterprise/components/pubs-overview.md | 3 +- .../enterprise/components/tasker-overview.md | 3 +- articles/enterprise/technical-requirements.md | 256 +++--------------- 6 files changed, 62 insertions(+), 224 deletions(-) diff --git a/articles/enterprise/components/app-overview.md b/articles/enterprise/components/app-overview.md index 6c6d645..378fb6f 100644 --- a/articles/enterprise/components/app-overview.md +++ b/articles/enterprise/components/app-overview.md @@ -1,6 +1,9 @@ # The Stoplight App -The **App** component powers the Stoplight user interface by connecting users to the Stoplight API and other services. +The **App** component powers the Stoplight user interface by connecting users to +the Stoplight API and other services. 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. > #### Networking Details > diff --git a/articles/enterprise/components/gitlab-overview.md b/articles/enterprise/components/gitlab-overview.md index 6583ae8..fb6ef51 100644 --- a/articles/enterprise/components/gitlab-overview.md +++ b/articles/enterprise/components/gitlab-overview.md @@ -1,6 +1,20 @@ # GitLab CE GitLab CE powers the Stoplight backend, including file storage and database. +GitLab is the backing datastore for all files stored within Stoplight. In +addition to storing files, GitLab 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 and Redis. 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). > ### Requirements > diff --git a/articles/enterprise/components/prism-overview.md b/articles/enterprise/components/prism-overview.md index e0e2d1f..b9b7500 100644 --- a/articles/enterprise/components/prism-overview.md +++ b/articles/enterprise/components/prism-overview.md @@ -15,6 +15,11 @@ The **Prism** component powers scenarios and API orchestration. > Prism must be able to make outgoing connections to the following components: > > * Exporter +> +> In addition to the above requirements, 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`. > #### Component Dependencies > diff --git a/articles/enterprise/components/pubs-overview.md b/articles/enterprise/components/pubs-overview.md index de3bda1..9474d7e 100644 --- a/articles/enterprise/components/pubs-overview.md +++ b/articles/enterprise/components/pubs-overview.md @@ -1,4 +1,4 @@ -# Pubs +# Pubs (Hubs Server) The **Pubs** component serves and catalogs hubs published through Stoplight. @@ -11,6 +11,7 @@ The **Pubs** component serves and catalogs hubs published through Stoplight. > > * User Clients (on the public-facing ports, which default to 8080 and 8443) > * API (on the private admin port, which defaults to 9098) +> * Tasker (on the private admin port, which defaults to 9098) > > Pubs must be able to make outgoing connections to the following components: > diff --git a/articles/enterprise/components/tasker-overview.md b/articles/enterprise/components/tasker-overview.md index d090557..3a57cae 100644 --- a/articles/enterprise/components/tasker-overview.md +++ b/articles/enterprise/components/tasker-overview.md @@ -1,4 +1,4 @@ -# Tasker +# Tasker (Jobs Server) The **Tasker** component runs scheduled and on-demand tasks for the Stoplight platform. @@ -15,6 +15,7 @@ The **Tasker** component runs scheduled and on-demand tasks for the Stoplight pl > > * API > * Redis +> * Pubs > #### Component Dependencies > diff --git a/articles/enterprise/technical-requirements.md b/articles/enterprise/technical-requirements.md index 85e6fbc..860cae1 100644 --- a/articles/enterprise/technical-requirements.md +++ b/articles/enterprise/technical-requirements.md @@ -1,33 +1,50 @@ -# Technical Requirements +# Requirements + +## Prerequisites 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. +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 +### Docker 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 +* [Docker CE](https://www.docker.com/) v18.00+ -### Package-based Installations +### RPM Installations -If Docker is not allowed within your operating environment, the application requirements are: +For RPM-based installations, 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) +* [NodeJS](https://nodejs.org/) v8.9.4 +* [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: +## Stoplight Components + +![](https://s3.amazonaws.com/user-content.stoplight.io/1564/1520952929100) + +The Stoplight platform is broken up in to seven main components: + +1. [Stoplight App](/enterprise/components/app) +2. [Stoplight API](/enterprise/components/api) +3. [Stoplight Exporter](/enterprise/components/exporter) +4. [Prism](/enterprise/components/prism) +5. [Tasker (Jobs Server)](/enterprise/components/tasker) + * [Hub Builder](/enterprise/components/hub-builder) +6. [Pubs (Hubs Server)](/enterprise/components/pubs) +7. [GitLab CE - Stoplight Fork](/enterprise/components/gitlab) + +## Monitoring + +For monitoring purposes, Stoplight runs and recommends the following +applications: * [InfluxDB](https://www.influxdata.com/time-series-platform/influxdb/) v1.3 for metrics storage and aggregation @@ -38,208 +55,5 @@ For automation and configuration purposes, [Ansible](https://www.ansible.com/) v * [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. +Please note that the above recommendations are entirely optional if your +organization already has a monitoring and alerting solution in place. From 6ae11b37920c9c46a75bc5de9b036a70970b4591 Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Wed, 18 Apr 2018 14:52:50 -0500 Subject: [PATCH 15/30] Remove overview from component article names --- articles/enterprise/components/{api-overview.md => api.md} | 0 articles/enterprise/components/{app-overview.md => app.md} | 0 .../enterprise/components/{exporter-overview.md => exporter.md} | 0 articles/enterprise/components/{gitlab-overview.md => gitlab.md} | 0 .../components/{hub-builder-overview.md => hub-builder.md} | 0 articles/enterprise/components/{prism-overview.md => prism.md} | 0 articles/enterprise/components/{pubs-overview.md => pubs.md} | 0 articles/enterprise/components/{tasker-overview.md => tasker.md} | 0 8 files changed, 0 insertions(+), 0 deletions(-) rename articles/enterprise/components/{api-overview.md => api.md} (100%) rename articles/enterprise/components/{app-overview.md => app.md} (100%) rename articles/enterprise/components/{exporter-overview.md => exporter.md} (100%) rename articles/enterprise/components/{gitlab-overview.md => gitlab.md} (100%) rename articles/enterprise/components/{hub-builder-overview.md => hub-builder.md} (100%) rename articles/enterprise/components/{prism-overview.md => prism.md} (100%) rename articles/enterprise/components/{pubs-overview.md => pubs.md} (100%) rename articles/enterprise/components/{tasker-overview.md => tasker.md} (100%) diff --git a/articles/enterprise/components/api-overview.md b/articles/enterprise/components/api.md similarity index 100% rename from articles/enterprise/components/api-overview.md rename to articles/enterprise/components/api.md diff --git a/articles/enterprise/components/app-overview.md b/articles/enterprise/components/app.md similarity index 100% rename from articles/enterprise/components/app-overview.md rename to articles/enterprise/components/app.md diff --git a/articles/enterprise/components/exporter-overview.md b/articles/enterprise/components/exporter.md similarity index 100% rename from articles/enterprise/components/exporter-overview.md rename to articles/enterprise/components/exporter.md diff --git a/articles/enterprise/components/gitlab-overview.md b/articles/enterprise/components/gitlab.md similarity index 100% rename from articles/enterprise/components/gitlab-overview.md rename to articles/enterprise/components/gitlab.md diff --git a/articles/enterprise/components/hub-builder-overview.md b/articles/enterprise/components/hub-builder.md similarity index 100% rename from articles/enterprise/components/hub-builder-overview.md rename to articles/enterprise/components/hub-builder.md diff --git a/articles/enterprise/components/prism-overview.md b/articles/enterprise/components/prism.md similarity index 100% rename from articles/enterprise/components/prism-overview.md rename to articles/enterprise/components/prism.md diff --git a/articles/enterprise/components/pubs-overview.md b/articles/enterprise/components/pubs.md similarity index 100% rename from articles/enterprise/components/pubs-overview.md rename to articles/enterprise/components/pubs.md diff --git a/articles/enterprise/components/tasker-overview.md b/articles/enterprise/components/tasker.md similarity index 100% rename from articles/enterprise/components/tasker-overview.md rename to articles/enterprise/components/tasker.md From 19796b961c19ac5c56811dfd25dbba9d3c06215b Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Wed, 18 Apr 2018 15:08:09 -0500 Subject: [PATCH 16/30] Consolidate installation-overview and technical-requirements into new overview page --- articles/enterprise/installation-overview.md | 44 -------- articles/enterprise/overview.md | 100 ++++++++++++++++++ articles/enterprise/technical-requirements.md | 59 ----------- 3 files changed, 100 insertions(+), 103 deletions(-) delete mode 100644 articles/enterprise/installation-overview.md create mode 100644 articles/enterprise/overview.md delete mode 100644 articles/enterprise/technical-requirements.md diff --git a/articles/enterprise/installation-overview.md b/articles/enterprise/installation-overview.md deleted file mode 100644 index 97340a1..0000000 --- a/articles/enterprise/installation-overview.md +++ /dev/null @@ -1,44 +0,0 @@ -# Installation Overview - -The Stoplight Enterprise platform provides a fully-functional on-premise API -design, test, 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** 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 one -another. 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. Container-based Deployments - -The Stoplight platform can be run either with a container solution (Docker) or -natively on the Linux system. Both options are supported, however Stoplight -recommends leveraging containers where possible for ease-of-use and improved -security/sandboxing. diff --git a/articles/enterprise/overview.md b/articles/enterprise/overview.md new file mode 100644 index 0000000..8ebd62a --- /dev/null +++ b/articles/enterprise/overview.md @@ -0,0 +1,100 @@ +# Stoplight Enterprise + +The Stoplight Enterprise platform provides a fully-functional on-premise API +design, test, and documentation tool-kit, taking the hassle out of your API +strategy. + +## Deployment Options + +Stoplight can be deployed on one or many Linux servers (dedicated or +virtualized). + +### Single-Server + +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 one another. + +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 these shortcomings, single-server deployments are only recommended for +POC, pilot, or trial environments. + +### Multi-Server + +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-facing +installations. + +### Native vs. Container-based Deployments + +The Stoplight platform can be run either with a container solution (Docker) or +natively on the Linux system via RPM package installation. Both options are +fully supported, however Stoplight recommends leveraging containers where +possible for ease-of-use and improved security/sandboxing. + +## System 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. + +### Docker Installations + +For the recommended Docker-based installation path, Stoplight recommends [Docker +CE](https://www.docker.com/) v18.00+. + +### RPM Installations + +For RPM-based installations, the application requirements vary by component and +are addressed in the component pages referenced below. + +## Stoplight Components + +![](https://s3.amazonaws.com/user-content.stoplight.io/1564/1520952929100) + +The Stoplight platform is broken up in to seven main components: + +1. [Stoplight App](/enterprise/components/app) +2. [Stoplight API](/enterprise/components/api) +3. [Stoplight Exporter](/enterprise/components/exporter) +4. [Prism](/enterprise/components/prism) +5. [Tasker (Jobs Server)](/enterprise/components/tasker) + * [Hub Builder](/enterprise/components/hub-builder) +6. [Pubs (Hubs Server)](/enterprise/components/pubs) +7. [GitLab CE - Stoplight Fork](/enterprise/components/gitlab) + +Please review each of the component pages prior to the installation. + +## Monitoring + +For monitoring purposes, Stoplight runs and 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. diff --git a/articles/enterprise/technical-requirements.md b/articles/enterprise/technical-requirements.md deleted file mode 100644 index 860cae1..0000000 --- a/articles/enterprise/technical-requirements.md +++ /dev/null @@ -1,59 +0,0 @@ -# Requirements - -## Prerequisites - -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. - -### Docker Installations - -For the recommended Docker-based installation path, the only application requirements are: - -* [Docker CE](https://www.docker.com/) v18.00+ - -### RPM Installations - -For RPM-based installations, the application requirements are: - -* [NodeJS](https://nodejs.org/) v8.9.4 -* [PostgreSQL](https://www.postgresql.org/) v9.6+ (optionally included with GitLab) -* [Redis](https://redis.io/) v2.8+ (optionally included with GitLab) - -## Stoplight Components - -![](https://s3.amazonaws.com/user-content.stoplight.io/1564/1520952929100) - -The Stoplight platform is broken up in to seven main components: - -1. [Stoplight App](/enterprise/components/app) -2. [Stoplight API](/enterprise/components/api) -3. [Stoplight Exporter](/enterprise/components/exporter) -4. [Prism](/enterprise/components/prism) -5. [Tasker (Jobs Server)](/enterprise/components/tasker) - * [Hub Builder](/enterprise/components/hub-builder) -6. [Pubs (Hubs Server)](/enterprise/components/pubs) -7. [GitLab CE - Stoplight Fork](/enterprise/components/gitlab) - -## Monitoring - -For monitoring purposes, Stoplight runs and 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. From c7b1f05a44a6cadc063a80681d9174f600b7e275 Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Wed, 18 Apr 2018 16:29:29 -0500 Subject: [PATCH 17/30] Feedback --- articles/enterprise/components/api.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/articles/enterprise/components/api.md b/articles/enterprise/components/api.md index ddef664..b4777a8 100644 --- a/articles/enterprise/components/api.md +++ b/articles/enterprise/components/api.md @@ -44,7 +44,7 @@ Prior to installing the RPM package, you will need to: #### Installing NodeJS -To install NodeJS, please run the following commands: +To install NodeJS, run the following commands: ```bash # make sure all current versions of nodejs are removed @@ -61,7 +61,7 @@ $ node --version v8.9.4 ``` -If you do not see a version starting `v8.9`, please contact Stoplight support for assistance. +If you do not see a version starting `v8.9`, contact Stoplight support for assistance. #### Setting up the Package Repository @@ -111,7 +111,8 @@ docker pull quay.io/stoplight/api To configure the Stoplight API component, you will need to provide runtime values and connection details to the other necessary Stoplight components. The -API can be configured either by configuration file or through the environment. +API can be configured either by the configuration file or through the +environment. > The same configuration variables can be used regardless of installation type > (container or package-based). @@ -131,8 +132,8 @@ There is no minimum or maximum character requirement, however Stoplight recommends using a random string more than 32 characters in length for production environments. -> Please note that the `SIGN_SECRET` configuration variable must remain static -> between service restarts +> Note that the `SIGN_SECRET` configuration variable must remain static between +> service restarts #### POSTGRES_URL From c1ba9f5f9a53301d7f5a6194b1448a83ff632932 Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Wed, 18 Apr 2018 16:30:48 -0500 Subject: [PATCH 18/30] Remove all pleases. --- articles/enterprise/components/app.md | 4 ++-- articles/enterprise/components/exporter.md | 4 ++-- articles/enterprise/components/gitlab.md | 6 ++++-- articles/enterprise/components/hub-builder.md | 4 ++-- 4 files changed, 10 insertions(+), 8 deletions(-) diff --git a/articles/enterprise/components/app.md b/articles/enterprise/components/app.md index 378fb6f..85e4f97 100644 --- a/articles/enterprise/components/app.md +++ b/articles/enterprise/components/app.md @@ -41,7 +41,7 @@ Prior to installing the RPM package, you will need to: #### Installing NodeJS -To install NodeJS, please run the following commands: +To install NodeJS, run the following commands: ```bash # make sure all current versions of nodejs are removed @@ -58,7 +58,7 @@ $ node --version v8.9.4 ``` -If you do not see a version starting `v8.9`, please contact Stoplight support for assistance. +If you do not see a version starting `v8.9`, contact Stoplight support for assistance. #### Setting up the Package Repository diff --git a/articles/enterprise/components/exporter.md b/articles/enterprise/components/exporter.md index 26137e5..0acb69a 100644 --- a/articles/enterprise/components/exporter.md +++ b/articles/enterprise/components/exporter.md @@ -37,7 +37,7 @@ Prior to installing the RPM package, you will need to: #### Installing NodeJS -To install NodeJS, please run the following commands: +To install NodeJS, run the following commands: ```bash # make sure all current versions of nodejs are removed @@ -54,7 +54,7 @@ $ node --version v8.9.4 ``` -If you do not see a version starting `v8.9`, please contact Stoplight support for assistance. +If you do not see a version starting `v8.9`, contact Stoplight support for assistance. #### Setting up the Package Repository diff --git a/articles/enterprise/components/gitlab.md b/articles/enterprise/components/gitlab.md index fb6ef51..924fcf1 100644 --- a/articles/enterprise/components/gitlab.md +++ b/articles/enterprise/components/gitlab.md @@ -89,7 +89,8 @@ The Stoplight GitLab configuration is located at: 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) +> For documentation on other GitLab configuration options, see the official +> documentation [here](https://docs.gitlab.com/omnibus/README.html#configuring) #### Starting the Service @@ -191,4 +192,5 @@ Once the configuration changes are made, issue a `gitlab-ctl reconfigure` for th > 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). +For more information on configuring Redis, see the official GitLab documentation +[here](https://docs.gitlab.com/omnibus/settings/redis.html). diff --git a/articles/enterprise/components/hub-builder.md b/articles/enterprise/components/hub-builder.md index 044ec3d..e93bc05 100644 --- a/articles/enterprise/components/hub-builder.md +++ b/articles/enterprise/components/hub-builder.md @@ -25,7 +25,7 @@ Prior to installing the RPM package, you will need to: #### Installing NodeJS -To install NodeJS, please run the following commands: +To install NodeJS, run the following commands: ```bash # make sure all current versions of nodejs are removed @@ -42,7 +42,7 @@ $ node --version v8.9.4 ``` -If you do not see a version starting `v8.9`, please contact Stoplight support for assistance. +If you do not see a version starting `v8.9`, contact Stoplight support for assistance. #### Setting up the Package Repository From 0e8ff26dcec5fb80e6386cfb2731bf38eedd8968 Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Wed, 18 Apr 2018 16:31:45 -0500 Subject: [PATCH 19/30] Add 'the' to the other articles. --- articles/enterprise/components/app.md | 2 +- articles/enterprise/components/exporter.md | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/articles/enterprise/components/app.md b/articles/enterprise/components/app.md index 85e4f97..0996c1c 100644 --- a/articles/enterprise/components/app.md +++ b/articles/enterprise/components/app.md @@ -105,7 +105,7 @@ docker pull quay.io/stoplight/app To configure the Stoplight App component, you will need to provide connection details to the other necessary Stoplight components. The API can be configured -either by configuration file or through the environment. +either by the configuration file or through the environment. > The same configuration variables can be used regardless of installation type > (container or package-based). diff --git a/articles/enterprise/components/exporter.md b/articles/enterprise/components/exporter.md index 0acb69a..dd7a9e4 100644 --- a/articles/enterprise/components/exporter.md +++ b/articles/enterprise/components/exporter.md @@ -102,7 +102,7 @@ docker pull quay.io/stoplight/exporter To configure the Stoplight Exporter component, you will need to provide runtime values and connection details to the other necessary Stoplight components. The -Exporter can be configured either by configuration file or through the +Exporter can be configured either by the configuration file or through the environment. > The same configuration variables can be used regardless of installation type From 4bb08345473bb2b382ea6e2e03cf5b087ea4413e Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Wed, 18 Apr 2018 16:45:11 -0500 Subject: [PATCH 20/30] Update backups article. --- articles/enterprise/maintenance/backups.md | 27 +++++++++++++++++----- 1 file changed, 21 insertions(+), 6 deletions(-) diff --git a/articles/enterprise/maintenance/backups.md b/articles/enterprise/maintenance/backups.md index 5c65c4a..593f9ae 100644 --- a/articles/enterprise/maintenance/backups.md +++ b/articles/enterprise/maintenance/backups.md @@ -1,8 +1,22 @@ -# GitLab Backup Procedures +# Backups -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. +Backups are a critical component to ensuring the health of the Stoplight +platform. When creating a backup and restore strategy for your on-premise +installation, be sure to include the following locations: + +* The **GitLab data directory**, which includes the raw filesystem data backing each projects git repository. +* The **GitLab configuration directory**, which includes randomly-generated secrets and keys necessary for securing the GitLab runtime. +* The **GitLab PostgreSQL database**, which includes user, group, permissions, and other relational data not included in the git repositories. +* The **Pubs data directory**, which includes published hubs and their corresponding configurations. + +Backing up all locations above will ensure you can properly restore a Stoplight +installation without data loss. + +## GitLab Backup Procedures + +GitLab is a critical piece of the Stoplight 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: @@ -22,7 +36,7 @@ to cloud storage providers when configured. For more information, please see the official GitLab backup documentation [here](https://docs.gitlab.com/ce/raketasks/backup_restore.html). -# Pubs Backup Procedures +## Pubs Backup Procedures Pubs stores all published hubs created via the Stoplight application. While not critical to the health of the Stoplight Enterprise platform, it is recommended @@ -40,4 +54,5 @@ 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. +cloud storage. To ensure you have a recent backup available at all times, +Stoplight recommends taking a backup daily. From 732f29be9f649a8854c295465f9481092da2a37b Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Wed, 18 Apr 2018 16:46:03 -0500 Subject: [PATCH 21/30] Capitalize Stoplight. --- articles/enterprise/components/app.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/enterprise/components/app.md b/articles/enterprise/components/app.md index 0996c1c..d7b6a0d 100644 --- a/articles/enterprise/components/app.md +++ b/articles/enterprise/components/app.md @@ -114,7 +114,7 @@ either by the configuration file or through the environment. #### SL_APP_HOST -The `SL_APP_HOST` is the public-facing URL for the stoplight application. +The `SL_APP_HOST` is the public-facing URL for the Stoplight application. ``` SL_APP_HOST="https://stoplight.example.com" From 5b7d44bfbcbdd17deb9e51166f8d74cb85697401 Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Wed, 18 Apr 2018 16:53:58 -0500 Subject: [PATCH 22/30] Correct git -> Git --- articles/enterprise/components/gitlab.md | 4 ++-- articles/enterprise/maintenance/backups.md | 4 ++-- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/articles/enterprise/components/gitlab.md b/articles/enterprise/components/gitlab.md index 924fcf1..a253b66 100644 --- a/articles/enterprise/components/gitlab.md +++ b/articles/enterprise/components/gitlab.md @@ -13,14 +13,14 @@ addition to storing files, GitLab is responsible for: Packaged within the GitLab CE is an installation of PostgreSQL and Redis. 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 +out these services if you plan on using a managed hosting solution, for example, Amazon RDS (for PostgreSQL) or Amazon ElastiCache (for Redis). > ### Requirements > > #### Storage > -> GitLab requires persistent storage in order to store Stoplight file data (in git), and optionally PostgreSQL data (when using the omnibus package). +> GitLab requires persistent storage in order to store Stoplight file data (in Git), and optionally PostgreSQL data (when using the omnibus package). > > #### Networking > diff --git a/articles/enterprise/maintenance/backups.md b/articles/enterprise/maintenance/backups.md index 593f9ae..68d3819 100644 --- a/articles/enterprise/maintenance/backups.md +++ b/articles/enterprise/maintenance/backups.md @@ -4,9 +4,9 @@ Backups are a critical component to ensuring the health of the Stoplight platform. When creating a backup and restore strategy for your on-premise installation, be sure to include the following locations: -* The **GitLab data directory**, which includes the raw filesystem data backing each projects git repository. +* The **GitLab data directory**, which includes the raw filesystem data backing each projects Git repository. * The **GitLab configuration directory**, which includes randomly-generated secrets and keys necessary for securing the GitLab runtime. -* The **GitLab PostgreSQL database**, which includes user, group, permissions, and other relational data not included in the git repositories. +* The **GitLab PostgreSQL database**, which includes user, group, permissions, and other relational data not included in the Git repositories. * The **Pubs data directory**, which includes published hubs and their corresponding configurations. Backing up all locations above will ensure you can properly restore a Stoplight From bea00ab07ea70b255f98dc309f14d380b3a8fcec Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Wed, 18 Apr 2018 17:03:41 -0500 Subject: [PATCH 23/30] Update Gitlab networking section --- articles/enterprise/components/gitlab.md | 41 +++++++++++++++++------- 1 file changed, 30 insertions(+), 11 deletions(-) diff --git a/articles/enterprise/components/gitlab.md b/articles/enterprise/components/gitlab.md index a253b66..8dc8003 100644 --- a/articles/enterprise/components/gitlab.md +++ b/articles/enterprise/components/gitlab.md @@ -10,23 +10,42 @@ addition to storing files, GitLab is responsible for: * Tracking all changes between different files, and storing them within a Git repository -Packaged within the GitLab CE is an installation of PostgreSQL and Redis. 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). +Packaged within the GitLab CE is an embedded installation of PostgreSQL and +Redis. 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). -> ### Requirements +> #### Storage 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 Details > -> GitLab requires persistent storage in order to store Stoplight file data (in Git), and optionally PostgreSQL data (when using the omnibus package). +> The default GitLab ports are 80 (HTTP) and 443 (HTTPS). These ports can be +> customized via the `gitlab.rb` configuration file (discussed below). > -> #### Networking +> GitLab must be able to receive incoming connections from the following components: > -> 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. +> * App > -> _If not using the omnibus package, make sure that Redis and PostgreSQL are up and available prior to starting GitLab_ +> GitLab must be able to make outgoing connections to the following components: +> +> * PostgreSQL +> * Redis + +> #### Component Dependencies +> +> Make sure the following components are available **before** starting the GitLab +> service: +> +> * PostgreSQL +> * Redis +> +> _Note, for Omnibus users using the embedded PostgreSQL and Redis instances, +> these services will be started by the GitLab process._ ## Installation From f72f9889b72eb9cd573d02b59cf3cc3a5dcd9c05 Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Wed, 18 Apr 2018 17:04:24 -0500 Subject: [PATCH 24/30] Feedback --- articles/enterprise/components/gitlab.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/articles/enterprise/components/gitlab.md b/articles/enterprise/components/gitlab.md index 8dc8003..3d66099 100644 --- a/articles/enterprise/components/gitlab.md +++ b/articles/enterprise/components/gitlab.md @@ -133,7 +133,7 @@ sudo gitlab-ctl status #### 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. +The GitLab container should be configured nearly identically to the package installation described above. 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: From c11c9f646fbf8b4871070521eed4489ca4edc4e1 Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Thu, 19 Apr 2018 10:50:34 -0500 Subject: [PATCH 25/30] Clarify cat command. Capitalize hub. Reword ending of prism article. --- articles/enterprise/components/api.md | 2 +- articles/enterprise/components/app.md | 2 +- articles/enterprise/components/exporter.md | 2 +- articles/enterprise/components/gitlab.md | 2 +- articles/enterprise/components/hub-builder.md | 2 +- articles/enterprise/components/prism.md | 8 +++----- articles/enterprise/components/pubs.md | 6 +++--- articles/enterprise/components/tasker.md | 2 +- 8 files changed, 12 insertions(+), 14 deletions(-) diff --git a/articles/enterprise/components/api.md b/articles/enterprise/components/api.md index b4777a8..b49f357 100644 --- a/articles/enterprise/components/api.md +++ b/articles/enterprise/components/api.md @@ -85,7 +85,7 @@ gpgkey=https://pkg.stoplight.io/stoplight.key EOF ``` -> Be sure to set your repository credentials before issuing the `cat` command +> Make sure that the repository credentials are set before issuing the `cat` command above. #### Installing the API Package diff --git a/articles/enterprise/components/app.md b/articles/enterprise/components/app.md index d7b6a0d..4ed95c1 100644 --- a/articles/enterprise/components/app.md +++ b/articles/enterprise/components/app.md @@ -81,7 +81,7 @@ gpgkey=https://pkg.stoplight.io/stoplight.key EOF ``` -> Be sure to set your repository credentials before issuing the `cat` command +> Make sure that the repository credentials are set before issuing the `cat` command above. #### Installing the App Package diff --git a/articles/enterprise/components/exporter.md b/articles/enterprise/components/exporter.md index dd7a9e4..64a7c01 100644 --- a/articles/enterprise/components/exporter.md +++ b/articles/enterprise/components/exporter.md @@ -77,7 +77,7 @@ gpgkey=https://pkg.stoplight.io/stoplight.key EOF ``` -> Be sure to set your repository credentials before issuing the `cat` command +> Make sure that the repository credentials are set before issuing the `cat` command above. #### Installing the Exporter Package diff --git a/articles/enterprise/components/gitlab.md b/articles/enterprise/components/gitlab.md index 3d66099..d0f0ecc 100644 --- a/articles/enterprise/components/gitlab.md +++ b/articles/enterprise/components/gitlab.md @@ -74,7 +74,7 @@ gpgkey=https://pkg.stoplight.io/stoplight.key EOF ``` -> Make sure that the repository credentials are set before issuing the `cat` command +> Make sure that the repository credentials are set before issuing the `cat` command above. Once the repository is configured properly, you can install the GitLab component using the command: diff --git a/articles/enterprise/components/hub-builder.md b/articles/enterprise/components/hub-builder.md index e93bc05..0797dfd 100644 --- a/articles/enterprise/components/hub-builder.md +++ b/articles/enterprise/components/hub-builder.md @@ -65,7 +65,7 @@ gpgkey=https://pkg.stoplight.io/stoplight.key EOF ``` -> Be sure to set your repository credentials before issuing the `cat` command +> Make sure that the repository credentials are set before issuing the `cat` command above. #### Installing the Hub Builder Package diff --git a/articles/enterprise/components/prism.md b/articles/enterprise/components/prism.md index b9b7500..965351a 100644 --- a/articles/enterprise/components/prism.md +++ b/articles/enterprise/components/prism.md @@ -61,7 +61,7 @@ gpgkey=https://pkg.stoplight.io/stoplight.key EOF ``` -> Be sure to set your repository credentials before issuing the `cat` command +> Make sure that the repository credentials are set before issuing the `cat` command above. #### Installing the Prism Package @@ -244,12 +244,10 @@ 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`): +successful by issuing an `HTTP GET` request to the `/health` endpoint: ```bash -$ curl -v localhost:4050/health -Hello! +curl -v localhost:4050/health ``` > Be sure to update the URL above to match your local installation diff --git a/articles/enterprise/components/pubs.md b/articles/enterprise/components/pubs.md index 9474d7e..6e08205 100644 --- a/articles/enterprise/components/pubs.md +++ b/articles/enterprise/components/pubs.md @@ -1,6 +1,6 @@ # Pubs (Hubs Server) -The **Pubs** component serves and catalogs hubs published through Stoplight. +The **Pubs** component serves and catalogs Hubs published through Stoplight. > #### Networking Details > @@ -52,7 +52,7 @@ gpgkey=https://pkg.stoplight.io/stoplight.key EOF ``` -> Be sure to set your repository credentials before issuing the `cat` command +> Make sure that the repository credentials are set before issuing the `cat` command above. #### Installing the Pubs Package @@ -102,7 +102,7 @@ https_bind: "127.0.0.1:8443" #### ssl_enabled The `ssl_enabled` variable denotes whether SSL should be enabled when serving -hub requests. +Hub requests. ```yaml ssl_enabled: yes diff --git a/articles/enterprise/components/tasker.md b/articles/enterprise/components/tasker.md index 3a57cae..80d800f 100644 --- a/articles/enterprise/components/tasker.md +++ b/articles/enterprise/components/tasker.md @@ -55,7 +55,7 @@ gpgkey=https://pkg.stoplight.io/stoplight.key EOF ``` -> Be sure to set your repository credentials before issuing the `cat` command +> Make sure that the repository credentials are set before issuing the `cat` command above. #### Installing the Tasker Package From d5cedffeee0f67bd5d7f73d6aeeffbceb9a56e84 Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Thu, 19 Apr 2018 10:57:59 -0500 Subject: [PATCH 26/30] require -> requires --- articles/enterprise/components/api.md | 2 +- articles/enterprise/components/app.md | 2 +- articles/enterprise/components/exporter.md | 2 +- articles/enterprise/components/prism.md | 2 +- articles/enterprise/components/pubs.md | 2 +- articles/enterprise/components/tasker.md | 2 +- 6 files changed, 6 insertions(+), 6 deletions(-) diff --git a/articles/enterprise/components/api.md b/articles/enterprise/components/api.md index b49f357..0ff1f29 100644 --- a/articles/enterprise/components/api.md +++ b/articles/enterprise/components/api.md @@ -222,7 +222,7 @@ The Stoplight API configuration file is located at the path: Be sure to customize any variables as needed to match your environment before starting the API service. -> Any changes to the API configuration require a service restart in order to +> Any changes to the API configuration requires a service restart in order to > take effect. ### Docker diff --git a/articles/enterprise/components/app.md b/articles/enterprise/components/app.md index 4ed95c1..1db5ceb 100644 --- a/articles/enterprise/components/app.md +++ b/articles/enterprise/components/app.md @@ -179,7 +179,7 @@ The Stoplight App configuration is located at the location: Be sure to customize any variables as needed to match your environment before starting the API service. -> Any changes to the API configuration require a service restart in order to +> Any changes to the API configuration requires a service restart in order to > take effect. ### Docker diff --git a/articles/enterprise/components/exporter.md b/articles/enterprise/components/exporter.md index 64a7c01..6d70dc8 100644 --- a/articles/enterprise/components/exporter.md +++ b/articles/enterprise/components/exporter.md @@ -145,7 +145,7 @@ The Stoplight Exporter configuration is located at the location: Be sure to customize any variables as needed to match your environment before starting the Exporter service. -> Any changes to the Exporter configuration require a service restart in order +> Any changes to the Exporter configuration requires a service restart in order > to take effect. ### Docker diff --git a/articles/enterprise/components/prism.md b/articles/enterprise/components/prism.md index 965351a..f564ba0 100644 --- a/articles/enterprise/components/prism.md +++ b/articles/enterprise/components/prism.md @@ -182,7 +182,7 @@ The Prism configuration file is located at the location: Be sure to customize any variables as needed to match your environment before starting the Prism service. -> Any changes to the Prism configuration require a service restart in order to +> Any changes to the Prism configuration requires a service restart in order to > take effect. ### Docker diff --git a/articles/enterprise/components/pubs.md b/articles/enterprise/components/pubs.md index 6e08205..fd33bc6 100644 --- a/articles/enterprise/components/pubs.md +++ b/articles/enterprise/components/pubs.md @@ -201,7 +201,7 @@ The Pubs default configuration is located at the path: Be sure to customize any variables as needed to match your environment before starting the Pubs service. -> Any changes to the Pubs configuration require a service restart in order to +> Any changes to the Pubs configuration requires a service restart in order to > take effect. ### Docker diff --git a/articles/enterprise/components/tasker.md b/articles/enterprise/components/tasker.md index 80d800f..706f048 100644 --- a/articles/enterprise/components/tasker.md +++ b/articles/enterprise/components/tasker.md @@ -161,7 +161,7 @@ The Tasker configuration is located at: Be sure to customize any variables as needed to match your environment before starting the Tasker service. -> Any changes to the Tasker configuration require a service restart in order to +> Any changes to the Tasker configuration requires a service restart in order to > take effect. ### Docker From 7ea3f3c53f52fa5dc15eb05908be1d519ae9ea64 Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Thu, 19 Apr 2018 10:59:45 -0500 Subject: [PATCH 27/30] bold before --- articles/enterprise/components/api.md | 4 ++-- articles/enterprise/components/app.md | 4 ++-- articles/enterprise/components/exporter.md | 4 ++-- articles/enterprise/components/prism.md | 4 ++-- articles/enterprise/components/pubs.md | 4 ++-- articles/enterprise/components/tasker.md | 4 ++-- 6 files changed, 12 insertions(+), 12 deletions(-) diff --git a/articles/enterprise/components/api.md b/articles/enterprise/components/api.md index 0ff1f29..90ed2ca 100644 --- a/articles/enterprise/components/api.md +++ b/articles/enterprise/components/api.md @@ -219,8 +219,8 @@ The Stoplight API configuration file is located at the path: /etc/stoplight-api/stoplight-api.cfg ``` -Be sure to customize any variables as needed to match your environment before -starting the API service. +Be sure to customize any variables as needed to match your environment +**before** starting the API service. > Any changes to the API configuration requires a service restart in order to > take effect. diff --git a/articles/enterprise/components/app.md b/articles/enterprise/components/app.md index 1db5ceb..3658728 100644 --- a/articles/enterprise/components/app.md +++ b/articles/enterprise/components/app.md @@ -176,8 +176,8 @@ The Stoplight App configuration is located at the location: /etc/stoplight-app/stoplight-app.cfg ``` -Be sure to customize any variables as needed to match your environment before -starting the API service. +Be sure to customize any variables as needed to match your environment +**before** starting the API service. > Any changes to the API configuration requires a service restart in order to > take effect. diff --git a/articles/enterprise/components/exporter.md b/articles/enterprise/components/exporter.md index 6d70dc8..b951f81 100644 --- a/articles/enterprise/components/exporter.md +++ b/articles/enterprise/components/exporter.md @@ -142,8 +142,8 @@ The Stoplight Exporter configuration is located at the location: /etc/stoplight-exporter/stoplight-exporter.cfg ``` -Be sure to customize any variables as needed to match your environment before -starting the Exporter service. +Be sure to customize any variables as needed to match your environment +**before** starting the Exporter service. > Any changes to the Exporter configuration requires a service restart in order > to take effect. diff --git a/articles/enterprise/components/prism.md b/articles/enterprise/components/prism.md index f564ba0..7ddfe1f 100644 --- a/articles/enterprise/components/prism.md +++ b/articles/enterprise/components/prism.md @@ -179,8 +179,8 @@ The Prism configuration file is located at the location: /etc/prism/prism.cfg ``` -Be sure to customize any variables as needed to match your environment before -starting the Prism service. +Be sure to customize any variables as needed to match your environment +**before** starting the Prism service. > Any changes to the Prism configuration requires a service restart in order to > take effect. diff --git a/articles/enterprise/components/pubs.md b/articles/enterprise/components/pubs.md index fd33bc6..80067ed 100644 --- a/articles/enterprise/components/pubs.md +++ b/articles/enterprise/components/pubs.md @@ -198,8 +198,8 @@ The Pubs default configuration is located at the path: /etc/pubs/pubs.yml ``` -Be sure to customize any variables as needed to match your environment before -starting the Pubs service. +Be sure to customize any variables as needed to match your environment +**before** starting the Pubs service. > Any changes to the Pubs configuration requires a service restart in order to > take effect. diff --git a/articles/enterprise/components/tasker.md b/articles/enterprise/components/tasker.md index 706f048..45ca56c 100644 --- a/articles/enterprise/components/tasker.md +++ b/articles/enterprise/components/tasker.md @@ -158,8 +158,8 @@ The Tasker configuration is located at: /etc/tasker/tasker.cfg ``` -Be sure to customize any variables as needed to match your environment before -starting the Tasker service. +Be sure to customize any variables as needed to match your environment +**before** starting the Tasker service. > Any changes to the Tasker configuration requires a service restart in order to > take effect. From 19c9f170223fdb2c89d1885960e09eaebd32aa80 Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Thu, 19 Apr 2018 11:09:08 -0500 Subject: [PATCH 28/30] Fix typos. Clarify tasker configuration. --- articles/enterprise/components/exporter.md | 2 +- articles/enterprise/components/tasker.md | 11 ++++++----- 2 files changed, 7 insertions(+), 6 deletions(-) diff --git a/articles/enterprise/components/exporter.md b/articles/enterprise/components/exporter.md index b951f81..113319e 100644 --- a/articles/enterprise/components/exporter.md +++ b/articles/enterprise/components/exporter.md @@ -209,4 +209,4 @@ successful issuing an `HTTP GET` request to the root (`/`) endpoint: curl -v http://localhost:3031/ ``` -If the Exporter was installed and configured properly, you will receive an `HTTP 200` reponse back. +If the Exporter was installed and configured properly, you will receive an `HTTP 200` response back. diff --git a/articles/enterprise/components/tasker.md b/articles/enterprise/components/tasker.md index 45ca56c..a97a9a1 100644 --- a/articles/enterprise/components/tasker.md +++ b/articles/enterprise/components/tasker.md @@ -5,7 +5,7 @@ The **Tasker** component runs scheduled and on-demand tasks for the Stoplight pl > #### Networking Details > > The default port for the Tasker component is TCP port **9432**. This port can -> be customzied via configuration variable. +> be customized via configuration. > > Tasker must be able to receive incoming connections from the following components: > @@ -105,7 +105,8 @@ TASKER_MODE="shell" #### CORE_ROOT -The `CORE_ROOT` denotes the absolutel path to stoplight-hub-builder package root. +The `CORE_ROOT` denotes the absolute path to the stoplight-hub-builder package +root. ``` CORE_ROOT="/opt/stoplight-hub-builder" @@ -166,8 +167,8 @@ Be sure to customize any variables as needed to match your environment ### Docker -To expose these to the Docker runtime, either write them to a file and use the -`--env-file` argument: +To expose configuration variables to the Docker runtime, either write them to a +file and use the `--env-file` argument: ```bash cat <tasker-env-vars @@ -227,4 +228,4 @@ curl -v http://localhost:9432/health ``` If Tasker was installed and configured properly, you will receive an `HTTP 200` -reponse back. +response back. From dfb3d58357b0e3a1a9569991e3cbbb6330725d9a Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Thu, 19 Apr 2018 11:10:51 -0500 Subject: [PATCH 29/30] production-facing -> production --- articles/enterprise/overview.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/articles/enterprise/overview.md b/articles/enterprise/overview.md index 8ebd62a..47c63fb 100644 --- a/articles/enterprise/overview.md +++ b/articles/enterprise/overview.md @@ -33,8 +33,7 @@ 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-facing -installations. +Stoplight recommends multi-server deployments for all production installations. ### Native vs. Container-based Deployments From d8029b3a47711ecc6f56bf9bded54b4887b8a667 Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Thu, 19 Apr 2018 12:43:00 -0500 Subject: [PATCH 30/30] Add callout --- articles/enterprise/overview.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/articles/enterprise/overview.md b/articles/enterprise/overview.md index 47c63fb..005b6dc 100644 --- a/articles/enterprise/overview.md +++ b/articles/enterprise/overview.md @@ -95,5 +95,5 @@ applications: * [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. +> Please note that the above recommendations are entirely optional if your +> organization already has a monitoring and alerting solution in place.