From 57a481ed6de7f3beece8fae943c75b31ac9b5352 Mon Sep 17 00:00:00 2001 From: Carol Willing Date: Mon, 19 Sep 2016 15:18:10 -0700 Subject: [PATCH] Edit documentation for install and usage --- README.md | 89 +++++++++++++++++++++++++++++++++++++++++-------------- 1 file changed, 66 insertions(+), 23 deletions(-) diff --git a/README.md b/README.md index 2614018c..9a4cd0c5 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,9 @@ +**[Install](#install)** | +**[Using configurable-http-proxy](#using-configurable-http-proxy)** | +**[Using the REST API](#using-the-rest-api)** | +**[Custom error pages](#custom-error-pages)** | +**[Host-based routing](#host-based-routing)** + # configurable-http-proxy [![Build Status](https://travis-ci.org/jupyterhub/configurable-http-proxy.svg?branch=master)](https://travis-ci.org/jupyterhub/configurable-http-proxy) @@ -19,11 +25,14 @@ node-http-proxy to provide this functionality to JupyterHub. ## Install -To install `configurable-http-proxy` globally using the npm package manager: +Prerequisite: [Node.js](https://nodejs.org/en/download/) + +To install globally from the `configurable-http-proxy` package release +using the npm package manager: npm install -g configurable-http-proxy -To install from source found in this GitHub repo: +To install from the source code found in this GitHub repo: git clone https://github.com/jupyterhub/configurable-http-proxy.git cd configurable-http-proxy @@ -41,10 +50,13 @@ The configurable proxy runs two HTTP(S) servers: localhost by default. The REST API uses token authorization, set by the `CONFIGPROXY_AUTH_TOKEN` environment variable. -When you start the proxy, you can set a default target to be used when no +### Setting a default target + +When you start the proxy from the command line, you can set a +default target (`--default-target` option) to be used when no matching route is found in the proxy table: - $ configurable-http-proxy --default-target=http://localhost:8888 + configurable-http-proxy --default-target=http://localhost:8888 ### Command-line options @@ -57,6 +69,7 @@ matching route is found in the proxy table: -V, --version output the version number --ip Public-facing IP of the proxy --port (defaults to 8000) Public-facing port of the proxy + --ssl-key SSL key to use, if any --ssl-cert SSL certificate to use, if any --ssl-ca SSL certificate authority, if any @@ -66,6 +79,7 @@ matching route is found in the proxy table: --ssl-ciphers `:`-separated ssl cipher list. Default excludes RC4 --ssl-allow-rc4 Allow RC4 cipher for SSL (disabled by default) --ssl-dhparam SSL Diffie-Helman Parameters pem file, if any + --api-ip Inward-facing IP for API requests --api-port Inward-facing port for API requests (defaults to --port=value+1) --api-ssl-key SSL key to use, if any, for API requests @@ -73,6 +87,7 @@ matching route is found in the proxy table: --api-ssl-ca SSL certificate authority, if any, for API requests --api-ssl-request-cert Request SSL certs to authenticate clients for API requests --api-ssl-reject-unauthorized Reject unauthorized SSL connections (only meaningful if --api-ssl-request-cert is given) + --default-target Default proxy target (proto://host[:port]) --error-target Alternate server for handling proxy errors (proto://host[:port]) --error-path Alternate server for handling proxy errors (proto://host[:port]) @@ -89,19 +104,29 @@ matching route is found in the proxy table: --log-level Log level (debug, info, warn, error) ``` + ## Using the REST API -The REST API is authenticated via a token in the `Authorization` header. -The API is served under the `/api/routes` base URL. For example: +The configurable-http-proxy API is documented and available at the +interactive swagger site, [petstore](http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/configurable-http-proxy/master/doc/rest-api.yml#/default) +or as a [swagger specification file in this repo](https://github.com/jupyterhub/configurable-http-proxy/blob/master/doc/rest-api.yml). + +### Authenticating via passing a token - $> curl -H "Authorization: token $CONFIGPROXY_AUTH_TOKEN" http://localhost:8001/api/routes +The REST API is authenticated via passing a token in the `Authorization` header. +The API is served under the `/api/routes` base URL. For example, execute +this `curl` command in the terminal to authenticate and retrieve the +current routing table: + curl -H "Authorization: token $CONFIGPROXY_AUTH_TOKEN" http://localhost:8001/api/routes ### Getting the current routing table +**Request** + GET /api/routes[?inactive_since=ISO8601-timestamp] -Returns a JSON dictionary of the current routing table. +The GET request returns a JSON dictionary of the current routing table. This JSON dictionary *excludes* the default route. If the `inactive_since` URL parameter is given as an [ISO8601](http://en.wikipedia.org/wiki/ISO_8601) @@ -110,8 +135,11 @@ will be returned. **Response** +Status code: + status: 200 OK +Returned JSON dictionary of current routing table: ```json { @@ -129,15 +157,16 @@ will be returned. The `last_activity` timestamp is updated whenever the proxy passes data to or from the proxy target. - ### Adding new routes POST requests create new routes. The body of the request should be a JSON dictionary with at least one key: `target`, the target host to be proxied. +**Request** + POST /api/routes/[:path] -**Input** +*Input - request body* `target`: The host URL @@ -145,25 +174,32 @@ dictionary with at least one key: `target`, the target host to be proxied. status: 201 Created -Any request to `/path/prefix` on the proxy's public interface will be proxied -to `target`. +After adding the new route, any request to `/path/prefix` on the proxy's +public interface will be proxied to `target`. ### Deleting routes +**Request** + DELETE /api/routes/[:path] **Response** status: 204 No Content +Removes a route from the proxy's routing table. + + ## Custom error pages With version 0.5, configurable-host-proxy (CHP) adds two ways to provide custom error pages when the proxy encounters an error, and has no proxy target -to handle a request. There are two typical errors that CHP can hit: +to handle a request. There are two typical errors that CHP can hit, along +with their status code: - 404: a client has requested a URL for which there is no routing target. - This is impossible if a default target has been specified. + This can be prevented if a `default target` is specified when starting + the configurable-http-proxy. - 503: a route exists, but the upstream server isn't responding. This is more common, and can be due to any number of reasons, @@ -171,27 +207,34 @@ to handle a request. There are two typical errors that CHP can hit: ### error-path -If you specify `--error-path /usr/share/chp-errors`, then when a proxy error -occurs, CHP will look in `/usr/share/chp-errors/CODE.html` for an html page -to serve, e.g. `404.html` or `503.html`. +If you specify an error path `--error-path /usr/share/chp-errors` when +starting the CHP: + + configurable-http-proxy --error-path /usr/share/chp-errors + +then when a proxy error occurs, CHP will look in +`/usr/share/chp-errors/.html` (where CODE is the status code number) +for an html page to serve, e.g. `404.html` or `503.html`. If no file exists for the error code, `error.html` file will be used. -If you use this approach, make sure you have created `error.html`. +If you specify an error path, make sure you also create `error.html`. ### error-target +When starting the CHP, you can pass a command line option for `--error-target`. If you specify `--error-target http://localhost:1234`, -then when the proxy encounters an error, it will make a GET request to this -server, with URL `/CODE`, and the URL of the failing request escaped in a URL -parameter, e.g.: +then when the proxy encounters an error, it will make a GET request to +this server, with URL `/CODE`, and the URL of the failing request +escaped in a URL parameter, e.g.: GET /404?url=%2Fescaped%2Fpath ## Host-based routing -If `--host-routing` is given, the proxy will pick a target based on the host -of the incoming request, instead of the URL prefix. +If the CHP is started with the `--host-routing` option, the proxy will +pick a target based on the host of the incoming request, instead of the +URL prefix. The API when using host-based routes is the same as if the hostname were the first part of the URL path, e.g.: