293 lines
6.7 KiB
Markdown
293 lines
6.7 KiB
Markdown
# 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 <<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 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 <<EOF>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.
|