213 lines
5.0 KiB
Markdown
213 lines
5.0 KiB
Markdown
# 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 <<EOF | sudo tee /etc/yum.repos.d/stoplight.repo
|
|
[stoplight]
|
|
name=Stoplight Package Repository
|
|
baseurl=https://$REPO_USERNAME:$REPO_PASSWORD@pkg.stoplight.io/rpm
|
|
enabled=1
|
|
gpgcheck=1
|
|
repo_gpgcheck=1
|
|
gpgkey=https://pkg.stoplight.io/stoplight.key
|
|
EOF
|
|
```
|
|
|
|
> 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 <<EOF>exporter-env-vars
|
|
SL_APP_HOST="..."
|
|
...
|
|
EOF
|
|
|
|
docker run --env-file exporter-env-vars ...
|
|
```
|
|
|
|
Alternatively, you can expose them one at a time with the `-e` flag:
|
|
|
|
```bash
|
|
docker run -e SL_APP_HOST=https://stoplight.example.com ...
|
|
```
|
|
|
|
## 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.
|