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

Update app with latest changes.

Browse Source
This commit is contained in:
Ross McDonald
2018-04-18 11:30:08 -05:00
parent 2c75bdb1bb
commit fc9bcb0551
2 changed files with 116 additions and 88 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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

@@ -32,9 +32,7 @@ datastore and other miscellaneous Stoplight services.
## Installation
The Stoplight API can be installed with Docker or via RPM package.
> Before starting, be sure to complete the GitLab installation.
The Stoplight API can be installed with Docker or RPM package.
### RPM Package

200
articles/enterprise/components/app-overview.md
View File

@@ -1,24 +1,32 @@
# 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
> #### Networking Details
>
> #### Storage
> The default port for the App component is TCP port **3100**. The port can be
> customized using the `PORT` configuration variable.
>
> There are no storage requirements for this component.
> The App must be able to receive **incoming** connections from the following components:
>
> #### Networking
> * User Clients (web browser or desktop application)
>
> The default port for the app component is TCP port **3100**. The port can be customized using the `PORT` environment variable.
> The App must be able to make **outgoing** connections to the following components:
>
> _Be sure that both API and GitLab components are available **before** starting the app service_
> * API
> * Prism
> * Exporter
> #### Component Dependencies
>
> Make sure the following components are available **before** starting the App
> service:
>
> * API
## Installation
The Stoplight app can be installed with Docker or via RPM package.
> Before starting, be sure to complete the GitLab and API installations.
The Stoplight App can be installed with Docker or RPM package.
### RPM Package
@@ -80,7 +88,7 @@ Once the repository is configured properly, you can install the app component us
sudo yum install stoplight-app -y
```
### Docker Installation
### Docker
To install the app component with Docker, run the command below:
@@ -90,50 +98,112 @@ docker pull quay.io/stoplight/app
> Note, if you have not already authenticated with the Stoplight container registry, you will be prompted for credentials
## Configuring and Running
## Configuration
To configure the Stoplight app component, you will need to provide connection details to the other necessary Stoplight components.
To configure the Stoplight App component, you will need to provide 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 app configuration is located at the location:
The Stoplight App configuration is located at the location:
```bash
/etc/stoplight-app/stoplight-app.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
# SL_APP_HOST is the public-facing URL for the stoplight application
cat <<EOF>app-env-vars
SL_API_HOST="..."
...
EOF
docker run --env-file app-env-vars ...
```
Or you can expose them one at a time with the `-e` flag:
```bash
docker run -e SL_API_HOST=https://stoplight-api.example.com ...
```
### Variables
#### SL_APP_HOST
The `SL_APP_HOST` is the public-facing URL for the stoplight application.
```
SL_APP_HOST="https://stoplight.example.com"
```
# SL_API_HOST is the URL to the Stoplight API
#### SL_API_HOST
The `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
The `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
The `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
#### SL_PRISM_HOST
The `SL_PRISM_HOST` is the full URL to the Stoplight Prism instance
```
SL_PRISM_HOST="https://stoplight-prism.internal.example.com"
```
# SL_PUBS_HOST is the top-level domain used for documentation
#### SL_PUBS_HOST
The `SL_PUBS_HOST` variable is the top-level domain used for documentation:
```
SL_PUBS_HOST="docs.example.com"
```
# SL_PUBS_INGRESS is the URL to the Stoplight Pubs instance admin API
#### SL_PUBS_INGRESS
The `SL_PUBS_INGRESS` variable is the URL to the Stoplight Pubs instance admin API:
```
SL_PUBS_INGRESS="https://pubs.example.com:9098"
```
Be sure to customize any of the variables above as needed.
## Running
#### Starting the Service
### RPM Package
To start the app server, run the command:
To start the App server, run the command:
```bash
sudo systemctl start stoplight-app
@@ -145,76 +215,36 @@ Once started, you can see the status of the service using the command:
sudo systemctl status stoplight-app
```
### Docker Installations
### Docker
#### Configuring the Container
The Stoplight app container requires the following environment variables be exposed to the running instance:
```bash
# SL_APP_HOST is the public-facing URL for the stoplight application
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="https://gitlab.internal.example.com:8080"
# 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
SL_PRISM_HOST="https://stoplight-prism.internal.example.com"
# SL_PUBS_HOST is the top-level domain used for documentation
SL_PUBS_HOST="docs.example.com"
# SL_PUBS_INGRESS is the URL to the Stoplight Pubs instance admin API
SL_PUBS_INGRESS="https://pubs.example.com:9098"
```
To expose these to the Docker runtime, either write them to a file and use the `--env-file` argument:
```bash
cat <<EOF>app-env-vars
SL_APP_HOST="..."
...
EOF
docker run --env-file app-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
To start the app container, run the command:
To start the App container, run the command:
```bash
docker run \
--restart on-failure \
--env-file app-env \
-p 1234:3100 \
quay.io/stoplight/app:latest
--restart on-failure \
--env-file app-env \
-p 1234:3100 \
quay.io/stoplight/app: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.
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 app component is running, you can verify the installation was successful by visiting the app hostname and port in a web browser. If the web page loads properly (what you see when visiting the [hosted site](https://next.stoplight.io/login)), then you should be greeted with a login screen, complete with images and styling.
Once the App component is running, you can verify the installation was
successful by visiting the app hostname and port in a web browser. If the web
page loads properly (what you see when visiting the [hosted
site](https://next.stoplight.io/login)), then you should be greeted with a login
screen, complete with images and styling.
If you would like to verify the app installation from the CLI, use `wget` to search for any broken links:
If you would like to verify the app installation from the CLI, use `wget` to
search for any broken links:
```
wget -r -l2 –spider -D example.com http://example.com 2>&1 | grep -B1 'broken link!'
```
> Be sure to replace 'example.com' above with the domain used to install the Stoplight application
No broken links reflects that the app was setup successfully.
> Remember to replace 'example.com' above with the domain used to install the
> Stoplight application