Skip to content

Commit

Permalink
Document origin configuration and improve user guide. (ExpediaGroup#106)
Browse files Browse the repository at this point in the history 
Address issue  ExpediaGroup#100 
* Add backend services configuration page to the user manual.
* Styx HTTP response codes moved out to their own page.
* Tidy up and improve language.
  • Loading branch information
@dvlato @mikkokar
dvlato authored and mikkokar committed Mar 13, 2018
1 parent 0f4d68f commit 2613993
Show file tree
Hide file tree
Showing 16 changed files with 449 additions and 233 deletions.
2 changes: 1 addition & 1 deletion docs/developer-guide/plugins-scenarios.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -97,7 +97,7 @@ chain.proceed(request). Otherwise a FORBIDDEN response is returned.
}
}

###Asynchronously transform response object
### Asynchronously transform response object

Processing a HTTP response asynchronously is very similar to processing response synchronously. Instead of Rx map()
operator, you'll use a flatMap(). In this example, we assume asyncOperation() makes a network call, performs I/O,
Expand Down
11 changes: 8 additions & 3 deletions docs/user-guide.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,12 +2,17 @@
# User Manual

Welcome to Styx user manual.
- [Reverse Proxying](user-guide/reverse-proxying.md) - Overview of Styx proxy functionality.


- [Basic Usage](user-guide/basic-usage.md) - Installing, Starting, and basic configuration of Styx.


- [Styx Reverse Proxy and Routing](user-guide/reverse-proxying.md) - Overview of Styx proxy functionality.

- [Styx response codes](user-guide/response-codes.md) - List of possible response codes.

- [Configuration Overview](user-guide/configure-overview.md) - Overview of Styx configuration.

- [Backend services and origins](user-guide/configure-origins.md) - Configuration of a backend service and its origins.

- [Transport Layer Security](user-guide/configure-tls.md) - Configure TLS for Styx proxying.

- [Load Balancing](user-guide/configure-load-balancing.md) - Configure load balancing.
Expand Down
48 changes: 25 additions & 23 deletions docs/user-guide/admin-interface.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,6 +2,7 @@

One of main features of the Styx server available for users is an admin interface available "out of the box".
It provides an HTTP interface with functionality that ease quick adaptation of the library.
Note that this endpoint must be externally secured.

## Endpoints available in the admin module
* POST interface with set of predefined admin commands (see [section below](#postinterface)).
Expand Down Expand Up @@ -33,19 +34,20 @@ All endpoints are available from the admin menu:
`http://<STYX_SERVER_URL>/admin/`

##### NOTE:
Endpoints that return `JSON` documents are compressed by default. To display documents prettified
Endpoints that return `JSON` documents are compressed by default. To display documents prettified, the
`?pretty` option as an additional query parameter should be used:

* `http://<STYX_SERVER_URL>/admin/metrics?pretty`

## POST interface <a name="postinterface"></a>

Following commands can be sent to the Styx admin interface with HTTP POST requests.
The following commands can be sent to the Styx admin interface with HTTP POST requests.

### Reload Origins

This command will cause Styx to reload the origins if the file has meaningfully changed. If the file has not changed,
or the changes are purely cosmetic (such as adding comments), no action will be taken.
This command will cause Styx to reload the origins if the file has meaningfully changed.
If the file has not changed,or the changes are purely cosmetic (such as adding comments),
no action will be taken.

#### Syntax:

Expand All @@ -63,7 +65,6 @@ So if Styx was on port 8080 on localhost:

`curl -X POST http://localhost:8080/admin/tasks/origins/reload`


### Origin Toggle

#### Enable Origin
Expand All @@ -79,14 +80,14 @@ active immediately.
##### Parameters:

* `STYX_SERVER_URL`: The host and port of the Styx Admin Interface
* `APP_ID`: The application the origin belongs to
* `APP_ID`: The backend service the origin belongs to
* `ORIGIN_ID`: An origin to enable

##### How to execute command using curl:

`curl -X POST http://<STYX_SERVER_URL>/admin/tasks/origins?cmd=enable_origin&appId=<APP_ID>&originId=<ORIGIN_ID>`

So if Styx was on port 8080 on localhost and you wanted to enable an origin called "hwa1" for an app called "hwa":
So if Styx was on port 8080 on localhost and you wanted to enable an origin called "hwa1" for a backend service called "hwa":

`curl -X POST http://localhost:8080/admin/tasks/origins?cmd=enable_origin&appId=hwa&originId=hwa1`

Expand All @@ -101,14 +102,14 @@ The `disable_origin` command will disable an enabled origin.
##### Parameters:

* `STYX_SERVER_URL`: The host and port of the Styx Admin Interface
* `APP_ID`: The application the origin belongs to
* `APP_ID`: The backend service the origin belongs to
* `ORIGIN_ID`: An origin to disable

##### How to execute command using curl:

`curl -X POST http://<STYX_SERVER_URL>/admin/tasks/origins?cmd=disable_origin&appId=<APP_ID>&originId=<ORIGIN_ID>`

So if Styx was on port 8080 on localhost and you wanted to disable an origin called "hwa1" for an app called "hwa":
So if Styx was on port 8080 on localhost and you wanted to disable an origin called "hwa1" for a backend service called "hwa":

`curl -X POST http://localhost:8080/admin/tasks/origins?cmd=disable_origin&appId=hwa&originId=hwa1`

Expand Down Expand Up @@ -146,9 +147,9 @@ refer to [Plugins](../developer-guide/plugins.md)
#### Syntax
`http://<STYX_SERVER_URL>/admin/dashboard/index.html`

Dashboard provides a visual representation of origins health. It lists all configured origins providing
Dashboard provides a visual representation of the origins health. It lists all configured origins providing
information about the status of the underlying connection to each origin. Using this dashboard you can quickly
observe whether the origin is reachable, what is a quality of a connection etc.
observe whether the origin is reachable, what is the quality of a connection, etc.

It also provides summarized information about error codes in current server uptime, both for the response
from origins and from Styx.
Expand All @@ -159,8 +160,9 @@ from origins and from Styx.

`http://<STYX_SERVER_URL>/admin/metrics`

Returns JSON document with server codahale metrics gathered in-memory by server instance. For more information on the concrete
metrics, please refer to [Metrics](metrics.md) and [Metrics Reference](metrics-reference.md) documents.
Returns JSON document with server metrics (from Dropwizard Metrics) gathered in-memory by server instance.
For more information on the concrete metrics, please refer to [Metrics](metrics.md)
and [Metrics Reference](metrics-reference.md) documents.

## JVM metrics

Expand All @@ -175,8 +177,8 @@ Subset of metrics exposed by JVM that is running the Styx server instance.

`http://<STYX_SERVER_URL>/admin/configuration`

Provides settings document that presents what exact values are used to configure the running server instance.
For more details about content of this document please refer to [Configure overview](configure-overview.md).
This endpoint returns a textual representation of the settings configured in the running server instance.
For more details about the content of this document please refer to [Configure overview](configure-overview.md).

## Origin services configuration

Expand All @@ -190,9 +192,9 @@ For more details about content of this document please refer to [Configure overv

`http://<STYX_SERVER_URL>/admin/origins/status`

This endpoint provides a similar information about as a GUI dashboard in a document form. It contains
a list of configured origin services and a status of underlying servers, which one are inactive and which ones were
disabled.
This endpoint provides similar information to the GUI dashboard but in document form. It contains
a list of configured backend services and the status of their underlying servers, stating which one are inactive
and which ones are disabled.

## Logging configuration

Expand All @@ -208,25 +210,25 @@ The document returned by this endpoint presents the configuration used to setup

`http://<STYX_SERVER_URL>/admin/healthcheck`

Easy to query endpoint that returns a document with the health status of origins based on `500` errors rate.
Easy to query endpoint that returns a document with the health status of origins based on the rate of `500` errors.

#### Syntax

`http://<STYX_SERVER_URL>/admin/status`

Deprecated endpoint, it returns short `OK` / `NOT_OK` based on an information that is also returned
by previous health-check endpoint.
Deprecated endpoint, it returns a short `OK` / `NOT_OK` based on the information returned
by the health-check endpoint.

#### Syntax

`http://<STYX_SERVER_URL>/admin/ping`

This endpoint doesn't perform any checks, it only returns `pong` when the server is running.
This endpoint returns `pong` when the server is running, without performing any checks regarding the status.

## Running threads

#### Syntax

`http://<STYX_SERVER_URL>/admin/threads`

For detailed monitoring this endpoint reports threads and their statuses running on the server.
This endpoint reports threads and their statuses running on the server.
57 changes: 34 additions & 23 deletions docs/user-guide/basic-usage.md
View file
Original file line number Diff line number Diff line change
@@ -1,35 +1,46 @@
# Starting Styx

## Building Styx from source code

In order to build styx from source code, Java 8 (1.8.0_45 or later) is required.
The build system requires Apache Maven. The Styx CI pipeline uses Maven version 3.2.1
for the automated continuous integration builds. On Mac OSX, a version installed
by HomeBrew is satisfactory.

The instructions are:
1. Download the code from github
2. Generate the artifact using maven.
```
git clone https://github.com/HotelsDotCom/styx.git
cd styx && mvn package
```

## System Requirements

Building Styx requires Java 1.8. It can be built with 1.8.0_45. Earlier maintenance
releases may work, but are not guaranteed to.

The build system requires Apache Maven. The Styx team uses Maven version 3.2.1
for automated continuous integration builds. On Mac OSX, a version installed
by HomeBrew is satisfactory.
Running Styx requires Java 1.8. It can be run with 1.8.0_45 or later versions. Earlier maintenance
releases or Java 1.9 may work, but are not guaranteed to.


## Step 1: Installing Styx:

Styx comes pre-packaged in a zip file. Extract the zip file to a directory of choice:

$ unzip styx.zip
$ unzip styx-<VERSION>-<OS>-<PLATFORM>.zip

This creates a subdirectory called `styx` that contains Styx binaries and a set
of configuration examples. Example configuration files can be found in `styx/conf`
This creates a subdirectory called `styx-<VERSION>` that contains Styx binaries and a set
of configuration examples. Example configuration files can be found in `styx-<VERSION>/conf`
subdirectory. There are some files worth noticing:

* `default.yml` - A Styx server configuration file. It specifies the Styx server
port numbers and other application configuration.

* `styx/conf/origins` subdirectory containing examples of Styx origins configuration
* `conf/origins` subdirectory containing examples of Styx origins configuration
files. A styx origins configuration file specifies the backend services for Styx.
Especially, have a look at `origins-configuration-documentation.yml`. It explains
all aspects of origins configuration settings.
all aspects of origins configuration settings (you can see more details in [Backend services and origins](configure-origins.md)).

* `logback.xml` - Logging configuration file. There are more examples in the `styx/conf/logback`
* `logback.xml` - Logging configuration file. There are more examples in the `conf/logback`
subdirectory.

* `styx-env.sh` - JVM settings file. See <TODO> section below.
Expand All @@ -41,17 +52,17 @@ This creates a subdirectory called `styx` that contains Styx binaries and a set
To start Styx, run the startup script from *bin/* directory, passing in the
configuration file as an argument:

$ ./styx/bin/startup ~/configs/staging.yml
$ ./bin/startup conf/env-development/styx-config.yml

This starts Styx according to a configuration specified in *staging.yml* file.
This starts Styx according to the configuration specified in *staging.yml* file.

You also can specify the configuration via *STYX_CONFIG* environment
You also can specify the configuration via the `STYX_CONFIG` environment
variable. For example:

STYX_CONFIG=~/configs/production.yml ./styx/bin/startup
STYX_CONFIG=conf/env-development/styx-config.yml ./bin/startup

If the configuration file is not specified as a command line argument or as an environment
variable, Styx by default attempts to load configuration from *$STYX_HOME/conf/default.yaml*.
variable, Styx by default attempts to load its configuration from *$STYX_HOME/conf/default.yaml*.

Once Styx has started up, it displays the Styx logo banner, followed by information
about the port numbers it is listening on.
Expand All @@ -74,12 +85,12 @@ script runs. Use this file as a "startup hook" to initialise Styx before it gets
You can configure JVM settings, system properties, and any other installation that may be
necessary before startup.

The styx startup script accepts an {-e} or {--env} command line option for specifying an alternative
The styx startup script accepts an `-e` or `--env` command line option for specifying an alternative
Styx environment file:

$ ./bin/startup -e ~/configs/custom-env.sh
$ ./bin/startup -e conf/env-development/styx-env.sh

The custom environment file can also be specified via *STYX_ENV_FILE* environment variable.
The custom environment file can also be specified via the *STYX_ENV_FILE* environment variable.


# Configuring Logging
Expand All @@ -88,9 +99,9 @@ Styx uses [Logback style](https://logback.qos.ch/manual/index.html) configuratio
configuration.

By default, the logback file is loaded from *$STYX_HOME/conf/logback.xml*. You can specify an alternative
logging configuration file using {-l} or {--logback} command line options:
logging configuration file using `-l` or `--logback` command line options:

$ ./bin/startup --logback ~/configs/logback-custom.xml
$ ./bin/startup --logback conf/env-development/logback.xml

You can also specify this via environment: *STYX_LOG_CONFIG*.

Expand Down Expand Up @@ -152,7 +163,7 @@ Command line options are:
Any environment variable starting with <JVM_> declares a command line
option for the underlying Java Virtual Machine.
The startup throws away the JVM_<SETTING> part, and passes the
<VALUE>, verbatim, for the JVM as a command line option.
<VALUE>, verbatim, as a command line option for the JVM.

Loading

0 comments on commit 2613993

Please sign in to comment.