diff --git a/articles/enterprise/authentication/saml.md b/articles/enterprise/authentication/saml.md new file mode 100644 index 0000000..cd4c713 --- /dev/null +++ b/articles/enterprise/authentication/saml.md @@ -0,0 +1,48 @@ +# 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. + +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.md b/articles/enterprise/components/api.md new file mode 100644 index 0000000..90ed2ca --- /dev/null +++ b/articles/enterprise/components/api.md @@ -0,0 +1,292 @@ +# 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` configuration variable. +> +> 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 + +The Stoplight API can be installed with Docker or 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, 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`, contact Stoplight support for assistance. + +#### 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 +REPO_USERNAME="myusername" +REPO_PASSWORD="mypassword" + +# write credentials to repo file +cat < Make sure that the repository credentials are set before issuing the `cat` command above. + +#### 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 + +To install the API component with Docker, run the command below: + +```bash +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. + +## Configuration + +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 the configuration file or through the +environment. + +> The same configuration variables can be used regardless of installation type +> (container or package-based). + +### 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. + +> 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. + +### RPM Package + +The Stoplight API configuration file is located at the path: + +```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 requires 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 + +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 + +To start the API container, run the command: + +```bash +docker run \ + --restart on-failure \ + -p 3030:3030 \ + quay.io/stoplight/api:latest +``` + +> 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: + +```bash +# 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. diff --git a/articles/enterprise/components/app.md b/articles/enterprise/components/app.md new file mode 100644 index 0000000..3658728 --- /dev/null +++ b/articles/enterprise/components/app.md @@ -0,0 +1,253 @@ +# The Stoplight App + +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 +> +> The default port for the App component is TCP port **3100**. The port can be +> customized using the `PORT` configuration variable. +> +> The App must be able to receive **incoming** connections from the following components: +> +> * User Clients (web browser or desktop application) +> +> The App must be able to make **outgoing** connections to the following components: +> +> * 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 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, 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`, 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 < Make sure that the repository credentials are set before issuing the `cat` command above. + +#### 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 + +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 + +## Configuration + +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 the configuration file or through the environment. + +> The same configuration variables can be used regardless of installation type +> (container or package-based). + +### 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 + +The `SL_API_HOST` is the URL to the Stoplight API. + +``` +SL_API_HOST="https://stoplight-api.internal.example.com:3030" +``` + +#### 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 + +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 + +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 + +The `SL_PUBS_HOST` variable is the top-level domain used for documentation: + +``` +SL_PUBS_HOST="docs.example.com" +``` + +#### 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" +``` + +### 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 requires 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 + +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 + +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!' +``` + +> Remember to replace 'example.com' above with the domain used to install the +> Stoplight application diff --git a/articles/enterprise/components/exporter.md b/articles/enterprise/components/exporter.md new file mode 100644 index 0000000..113319e --- /dev/null +++ b/articles/enterprise/components/exporter.md @@ -0,0 +1,212 @@ +# 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 Exporter component is TCP port **3031**. The port can +> be customized using the `PORT` configuration variable. +> +> 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 + +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, 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`, 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 < Make sure that the repository credentials are set before issuing the `cat` command above. + +#### 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 + +To install the Exporter 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 + +## Configuration + +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 the configuration file or through the +environment. + +> The same configuration variables can be used regardless of installation type +> (container or package-based). + +### Variables + +#### 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" +``` + +### 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 requires 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 Exporter 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 +``` + +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 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` response back. diff --git a/articles/enterprise/components/gitlab.md b/articles/enterprise/components/gitlab.md new file mode 100644 index 0000000..d0f0ecc --- /dev/null +++ b/articles/enterprise/components/gitlab.md @@ -0,0 +1,215 @@ +# 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 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). + +> #### Storage Requirements +> +> GitLab requires persistent storage in order to store Stoplight file data (in +> Git), and optionally PostgreSQL data (when using the omnibus package). + +> #### Networking Details +> +> The default GitLab ports are 80 (HTTP) and 443 (HTTPS). These ports can be +> customized via the `gitlab.rb` configuration file (discussed below). +> +> GitLab must be able to receive incoming connections from the following components: +> +> * App +> +> 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 + +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 < 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: + +```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, 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. 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, 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: + +```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, 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 new file mode 100644 index 0000000..0797dfd --- /dev/null +++ b/articles/enterprise/components/hub-builder.md @@ -0,0 +1,111 @@ +# The Stoplight Hub Builder + +The **Hub Builder** component converts a Stoplight Hub into a standalone static HTML website, suitable for viewing and distribution. + +> #### 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. + +### 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, 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`, 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 < Make sure that the repository credentials are set before issuing the `cat` command above. + +#### 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 + +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 + +## Configuration + +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). + +## Running + +## RPM Package + +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 + +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. diff --git a/articles/enterprise/components/prism.md b/articles/enterprise/components/prism.md new file mode 100644 index 0000000..7ddfe1f --- /dev/null +++ b/articles/enterprise/components/prism.md @@ -0,0 +1,256 @@ +# 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 +> +> 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 +> +> Make sure the following components are available **before** starting the API +> service: +> +> * PostgreSQL +> * Redis +> * Gitlab + +## 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. + +#### 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 +REPO_USERNAME="myusername" +REPO_PASSWORD="mypassword" + +# write credentials to repo file +cat < Make sure that the repository credentials are set before issuing the `cat` command above. + +#### 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 + +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. + +## Configuration + +To configure the Prism component, you will need to provide runtime settings and +connection details to the Stoplight App, API, and Exporter. + +### Variables + +#### SL_API_HOST + +The `SL_API_HOST` variable is the full URL to the Stoplight API. + +``` +SL_API_HOST="http://localhost:3030" +``` + +#### 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" +``` + +> `PRISM_LOG_LEVEL` should be left as `ERROR` unless instructed otherwise by the +> Stoplight Support staff. + +### RPM Package + +The Prism configuration file is located at the location: + +```bash +/etc/prism/prism.cfg +``` + +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. + +### Docker + +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 ... +``` + +## 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 +``` + +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 by issuing an `HTTP GET` request to the `/health` endpoint: + +```bash +curl -v localhost:4050/health +``` + +> 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. diff --git a/articles/enterprise/components/pubs.md b/articles/enterprise/components/pubs.md new file mode 100644 index 0000000..80067ed --- /dev/null +++ b/articles/enterprise/components/pubs.md @@ -0,0 +1,269 @@ +# Pubs (Hubs Server) + +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 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) +> * Tasker (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 + +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. + +#### 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 +REPO_USERNAME="myusername" +REPO_PASSWORD="mypassword" + +# write credentials to repo file +cat < Make sure that the repository credentials are set before issuing the `cat` command above. + +#### 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 +``` + +### 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 + +## Configuration + +To configure the Pubs component, you will need to provide connection details and +runtime settings. + +### Variables + +#### http_bind + +The `http_bind` variable denotes the bind address/port to use when serving HTTP +traffic. + +```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 +``` + +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. + +### 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 +/data/pubs.yml +``` + +This file can be mounted into the running Pubs container using the `-v` argument. + +```bash +docker run -v /data/pubs.yml:/etc/pubs/pubs.yml ... +``` + +## Running + +### RPM Package + +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 + +To start the Pubs container, use the command: + +```bash +docker run \ + --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. + +## Post-install Validations + +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 +``` + +> 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. diff --git a/articles/enterprise/components/tasker.md b/articles/enterprise/components/tasker.md new file mode 100644 index 0000000..a97a9a1 --- /dev/null +++ b/articles/enterprise/components/tasker.md @@ -0,0 +1,231 @@ +# Tasker (Jobs Server) + +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**. This port can +> be customized via configuration. +> +> 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 +> * Pubs + +> #### 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. + +#### 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 +REPO_USERNAME="myusername" +REPO_PASSWORD="mypassword" + +# write credentials to repo file +cat < Make sure that the repository credentials are set before issuing the `cat` command above. + +#### 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 + +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. + +## Configuration + +To configure the Tasker component, you will need to provide runtime settings and +connection details for a running Redis instance. + +### Variables + +#### 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 absolute path to the 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: + +```bash +/etc/tasker/tasker.cfg +``` + +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. + +### Docker + +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 +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 ... +``` + +## 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 +``` + +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 +# 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` +response back. diff --git a/articles/enterprise/maintenance/backups.md b/articles/enterprise/maintenance/backups.md new file mode 100644 index 0000000..68d3819 --- /dev/null +++ b/articles/enterprise/maintenance/backups.md @@ -0,0 +1,58 @@ +# Backups + +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: + +```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. + +> 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. + +For more information, please see the official GitLab backup documentation +[here](https://docs.gitlab.com/ce/raketasks/backup_restore.html). + +## 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 +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. To ensure you have a recent backup available at all times, +Stoplight recommends taking a backup daily. diff --git a/articles/enterprise/overview.md b/articles/enterprise/overview.md new file mode 100644 index 0000000..005b6dc --- /dev/null +++ b/articles/enterprise/overview.md @@ -0,0 +1,99 @@ +# 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 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/robbins.md b/articles/robbins.md deleted file mode 100644 index 8b13789..0000000 --- a/articles/robbins.md +++ /dev/null @@ -1 +0,0 @@ -