Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Document origin configuration and improve user guide. #106

Merged
merged 14 commits into from
Mar 13, 2018
Merged

Document origin configuration and improve user guide. #106

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
14 commits
Select commit Hold shift + click to select a range
cb109de
#100 Backend configuration was missing from the user guide.
a-dlatorre Mar 5, 2018
356087b
#100 Changed references in the quickstart to existing files in the di…
a-dlatorre Mar 5, 2018
623e62a
Standard codes moved out to their own page. Additional pages revised.
a-dlatorre Mar 7, 2018
2c71302
#100 Rest of documents reviewed.
a-dlatorre Mar 8, 2018
413d973
#100 Merged changes for the server error codes.
a-dlatorre Mar 8, 2018
fa4d62a
#100 Merged changes for the server error codes.
a-dlatorre Mar 8, 2018
5e18c02
#100 Small typos.
a-dlatorre Mar 8, 2018
2d6d908
Standard codes moved out to their own page. Additional pages revised.
a-dlatorre Mar 7, 2018
a350d45
#100 Documentation improvements.
a-dlatorre Mar 9, 2018
cfcedc4
#100 Documentation improvements.
a-dlatorre Mar 9, 2018
f475532
#100 Documentation improvements.
a-dlatorre Mar 9, 2018
ca86cc7
#100 Minor fixes to the documentation.
a-dlatorre Mar 12, 2018
e912e97
#100 Minor fixes to the documentation.
a-dlatorre Mar 12, 2018
681cb38
#100 Minor fixes to the documentation.
a-dlatorre Mar 13, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
11 changes: 8 additions & 3 deletions docs/user-guide.md
View file
Open in desktop
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
Open in desktop
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.
34 changes: 15 additions & 19 deletions docs/user-guide/basic-usage.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,34 +2,30 @@

## 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
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why is the remark about maven being removed?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The rest of the instructions were considering that we were downloading an already compiled binary, but here we were explaining how to build the app instead of how to run it.

Probably we can also add instructions to build from source code.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok. Makes sense.

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 +37,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
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 @@ -77,7 +73,7 @@ necessary before startup.
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.

Expand All @@ -90,7 +86,7 @@ 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:
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

There are some old formatting isssues with the page, such as -l and —logback above. Please address them too now as you are changing this file. Need to have a consistent formatting for this and the other pages.


$ ./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 +148,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