docs/articles/enterprise/components/app.md

The Stoplight App

The App component powers the Stoplight user interface by connecting users to the Stoplight API and other services. This is the primary point of ingress for most users using Stoplight. It is what they will load in their web browser, and connect the desktop app to.

Networking Details

The default port for the App component is TCP port 3100. The port can be customized using the PORT configuration variable.

The App must be able to receive incoming connections from the following components:

• User Clients (web browser or desktop application)

The App must be able to make outgoing connections to the following components:

• 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 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:

# 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:

$ 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 do this by copying-and-pasting the contents below into a terminal:

# 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 App Package

Once the repository is configured properly, you can install the app component using the command:

sudo yum install stoplight-app -y

Docker

To install the app component with Docker, run the command below:

docker pull quay.io/stoplight/app

Note, if you have not already authenticated with the Stoplight container registry, you will be prompted for credentials

Configuration

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 the configuration file or through the environment.

The same configuration variables can be used regardless of installation type (container or package-based).

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

The SL_API_HOST is the URL to the Stoplight API.

SL_API_HOST="https://stoplight-api.internal.example.com:3030"

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

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

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

The SL_PUBS_HOST variable is the top-level domain used for documentation:

SL_PUBS_HOST="docs.example.com"

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"

RPM Package

The Stoplight App configuration is located at the location:

/etc/stoplight-app/stoplight-app.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:

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:

docker run -e SL_API_HOST=https://stoplight-api.example.com ...

Running

RPM Package

To start the App server, run the command:

sudo systemctl start stoplight-app

Once started, you can see the status of the service using the command:

sudo systemctl status stoplight-app

Docker

To start the App container, run the command:

docker run \
	--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.

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), 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:

wget -r -l2 –spider -D example.com http://example.com 2>&1 | grep -B1 'broken link!'

Remember to replace 'example.com' above with the domain used to install the Stoplight application