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

```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 do this 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 App Package

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

```bash
sudo yum install stoplight-app -y
```

### Docker

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

```bash
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:

```bash
/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:

```bash
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 ...
```

## Running

### RPM Package

To start the App server, run the command:

```bash
sudo systemctl start stoplight-app
```

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

```bash
sudo systemctl status stoplight-app
```

### Docker

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
```

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.

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
