262 lines
6.0 KiB
Markdown
262 lines
6.0 KiB
Markdown
# 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 <<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 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_HOST
|
|
|
|
The `SL_HOST` variable is the full URL to the Prism instance.
|
|
|
|
```
|
|
SL_HOST="http://%sprism.example.com"
|
|
```
|
|
|
|
Where Prism is being served from the domain `prism.example.com`. Specifying a
|
|
port is optional.
|
|
|
|
> Note, the `%s` preceding the domain is **required**.
|
|
|
|
#### SL_API_HOST
|
|
|
|
The `SL_API_HOST` variable is the full URL to the Stoplight API.
|
|
|
|
```
|
|
SL_API_HOST="http://api.example.com:3030"
|
|
```
|
|
|
|
#### SL_EXPORTER_HOST
|
|
|
|
The `SL_EXPORTER_HOST` variable is the URL to the Stoplight Exporter.
|
|
|
|
```
|
|
SL_EXPORTER_HOST="http://exporter.example.com: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 <<EOF>prism-env-vars
|
|
SL_API_HOST="..."
|
|
...
|
|
EOF
|
|
|
|
docker run --env-file prism-env-vars ...
|
|
```
|
|
|
|
Alternatively, you can expose them one at a time with the `-e` flag:
|
|
|
|
```bash
|
|
docker run -e SL_API_HOST=api.stoplight.example.com ...
|
|
```
|
|
|
|
## 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.
|