Move installation-overview out of components directory. Minor updates and formatting fixes based on feedback.
This commit is contained in:
Ross McDonald
@@ -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.
|
||||
If the API was installed and configured properly, you will receive an HTTP 200 response back.
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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.
|
||||
If the Exporter was installed and configured properly, you will receive an HTTP 200 reponse back.
|
||||
|
||||
@@ -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).
|
||||
|
||||
@@ -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.
|
||||
@@ -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.
|
||||
If Prism was installed and configured properly, you will receive an HTTP 200 response back.
|
||||
|
||||
@@ -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.
|
||||
If Pubs was installed and configured properly, you will receive an HTTP 200 response back.
|
||||
|
||||
@@ -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.
|
||||
If Tasker was installed and configured properly, you will receive an HTTP 200 reponse back.
|
||||
|
||||
44
articles/enterprise/installation-overview.md
Normal file
44
articles/enterprise/installation-overview.md
Normal file
@@ -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.
|
||||
@@ -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.
|
||||
Once the backup is completed, the tarball output can be stored on redundant or
|
||||
cloud storage.
|
||||
|
||||
@@ -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.
|
||||
|
||||
Reference in New Issue
Block a user