TerribleDev/docs
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Restructure API component documentation.

Browse Source
This commit is contained in:
Ross McDonald
2018-04-18 11:16:50 -05:00
parent 631f64e175
commit 2c75bdb1bb
1 changed files with 169 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

287
articles/enterprise/components/api-overview.md
View File

@@ -1,12 +1,34 @@
# 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.
> The default port for the API component is TCP port **3030**. The port can be
> customized using the `PORT` configuration variable.
>
> Make sure that the GitLab component is available **before** starting the API service.
> 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
@@ -45,7 +67,8 @@ If you do not see a version starting `v8.9`, please contact Stoplight support fo
#### Setting up the Package Repository
You can do this by copying-and-pasting the contents below into a terminal:
You can setup the Stoplight package repo by copying-and-pasting the contents
below into a terminal:
```bash
# expose credentials to environment first
@@ -68,13 +91,14 @@ EOF
#### Installing the API Package
Once the repository is configured properly, you can install the API component using the command:
Once the repository is configured properly, you can install the API component
using the command:
```bash
sudo yum install stoplight-api -y
```
### Docker Installation
### Docker
To install the API component with Docker, run the command below:
@@ -83,57 +107,148 @@ 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
> Stoplight container registry, you will be prompted for credentials.
## Configuring and Running
## Configuration
To configure the Stoplight API component, you will need to provide connection details to the other necessary Stoplight components.
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 configuration file or through the environment.
### Package-based Installations
> The same configuration variables can be used regardless of installation type
> (container or package-based).
#### Configuring the Service
### RPM Package
The Stoplight API configuration is located at the location:
The Stoplight API configuration file is located at the location:
```bash
/etc/stoplight-api/stoplight-api.cfg
```
The above file should contain the following entries:
Be sure to customize any variables as needed to match your environment before
starting the API service.
> Any changes to the API configuration require 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
# Secret used to encrypt cookies and other secrets used by the Stoplight API.
SIGN_SECRET="CHANGE_ME_TO_SOMETHING_RANDOM"
cat <<EOF>api-env-vars
SL_APP_HOST="..."
...
EOF
# 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
# Stoplight is being served from 'stoplight.example.com', set
# this to 'example.com'.
SL_COOKIE_DOMAIN="example.com"
# SL_APP_HOST is the full URL to the Stoplight app component.
SL_APP_HOST="http://localhost:3030"
# SL_API_HOST is the full URL to this (the Stoplight API) component.
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="http://localhost:8080"
# SL_REDIS_URL is the full URL to a Redis instance.
SL_REDIS_URL="redis://:password@exampl.com:6379"
docker run --env-file api-env-vars ...
```
> Please note that the `SIGN_SECRET` environment variable must remain static between service restarts
Or you can expose them one at a time with the `-e` flag:
Be sure to customize any of the variables above as needed.
```bash
docker run -e SL_APP_HOST=https://stoplight.example.com ...
```
#### Starting the Service
### 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.
> Please 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.
## Running
### RPM Package
To start the API server, run the command:
@@ -147,96 +262,32 @@ Once started, you can see the status of the service using the command:
sudo systemctl status stoplight-api
```
### Docker Installations
#### Configuring the Container
The Stoplight API container requires the following environment variables be exposed to the running instance:
```bash
# 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.
POSTGRES_URL="postgres://username:password@example.com:5432"
# Domain that Stoplight is being served from. For example, if
# Stoplight is being served from 'stoplight.example.com', set
# this to 'example.com'.
SL_COOKIE_DOMAIN="example.com"
# SL_APP_HOST is the full URL to the Stoplight app component.
SL_APP_HOST="http://localhost:3030"
# SL_API_HOST is the full URL to this (the Stoplight API) component.
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="http://localhost:8080"
# SL_REDIS_URL is the full URL to a Redis instance.
SL_REDIS_URL="redis://:password@exampl.com:6379"
```
> Please note that the `SIGN_SECRET` environment variable must remain static between service restarts
To expose these 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 ...
```
Alternatively, you can expose them one at a time with the `-e` flag:
```bash
docker run -e SL_APP_HOST=https://stoplight.example.com ...
```
#### Starting the Container
### Docker
To start the API container, run the command:
```bash
docker run \
--restart on-failure \
--env-file api-env \
-p 2345:3030 \
quay.io/stoplight/api:latest
--restart on-failure \
-p 3030:3030 \
quay.io/stoplight/api: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.
> 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:
Once the API component is running, you can verify the installation was
successful issuing an `HTTP GET` request to the `/health` endpoint:
```bash
# be sure to update the port here to match the installation port
# 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.
## Other Configuration Options
### Disabling Registration
New users can be prevented from registering with Stoplight by exposing a
`DISABLE_REGISTRATION=true` variable either through the environment or
configuration.
If this option is enabled, new user registration requests will receive the
following error when attempting to register:
> User registration has been temporarily disabled. Please contact your administrator.
_Please note_, enabling this feature does not prevent existing users from
inviting new users.
If the API was installed and configured properly, you will receive an `HTTP 200`
response back.