From fc9bcb0551e15cfae529a4347c8fc194c4972533 Mon Sep 17 00:00:00 2001 From: Ross McDonald Date: Wed, 18 Apr 2018 11:30:08 -0500 Subject: [PATCH] Update app with latest changes. --- .../enterprise/components/api-overview.md | 4 +- .../enterprise/components/app-overview.md | 200 ++++++++++-------- 2 files changed, 116 insertions(+), 88 deletions(-) diff --git a/articles/enterprise/components/api-overview.md b/articles/enterprise/components/api-overview.md index a1a171c..02bdf7d 100644 --- a/articles/enterprise/components/api-overview.md +++ b/articles/enterprise/components/api-overview.md @@ -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 diff --git a/articles/enterprise/components/app-overview.md b/articles/enterprise/components/app-overview.md index e64afee..2ada5cb 100644 --- a/articles/enterprise/components/app-overview.md +++ b/articles/enterprise/components/app-overview.md @@ -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 <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 <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