Merge pull request #1269 from willingc/network-docs

Streamline networking and using REST API Docs

docs/source/configuration-guide.rst

@@ -6,9 +6,9 @@ Configuration Reference
 
    technical-overview
    websecurity
-   rest
    authenticators
    spawners
    services
+   rest
    upgrading
    config-examples

docs/source/index.rst

@@ -51,10 +51,10 @@ Contents
 
 * :doc:`technical-overview`
 * :doc:`websecurity`
-* :doc:`rest`
 * :doc:`authenticators`
 * :doc:`spawners`
 * :doc:`services`
+* :doc:`rest`
 * :doc:`upgrading`
 * :doc:`config-examples`
 

docs/source/networking-basics.md

@@ -1,39 +1,59 @@
 # Networking basics
 
-## Configuring the Proxy's IP address and port
+This section will help you with basic proxy and network configuration to:
+
+- set the proxy's IP address and port
+- set the proxy's REST API URL
+- configure the Hub if the Proxy or Spawners are remote or isolated
+- set the `hub_connect_ip` which services will use to communicate with the hub
+
+## Set the Proxy's IP address and port
+
 The Proxy's main IP address setting determines where JupyterHub is available to users.
 By default, JupyterHub is configured to be available on all network interfaces
-(`''`) on port 8000. **Note**: Use of `'*'` is discouraged for IP configuration;
+(`''`) on port 8000. *Note*: Use of `'*'` is discouraged for IP configuration;
 instead, use of `'0.0.0.0'` is preferred.
 
-Changing the IP address and port can be done with the following command line
+Changing the Proxy's main IP address and port can be done with the following
-arguments:
+JupyterHub **command line options**:
 
 ```bash
 jupyterhub --ip=192.168.1.2 --port=443
 ```
 
-Or by placing the following lines in a configuration file:
+Or by placing the following lines in a **configuration file**,
+`jupyterhub_config.py`:
 
 ```python
 c.JupyterHub.ip = '192.168.1.2'
 c.JupyterHub.port = 443
 ```
 
-Port 443 is used as an example since 443 is the default port for SSL/HTTPS.
+Port 443 is used in the examples since 443 is the default port for SSL/HTTPS.
 
-Configuring only the main IP and port of JupyterHub should be sufficient for most deployments of JupyterHub.
+Configuring only the main IP and port of JupyterHub should be sufficient for
-However, more customized scenarios may need additional networking details to
+most deployments of JupyterHub. However, more customized scenarios may need
-be configured.
+additional networking details to be configured.
 
+## Set the Proxy's REST API communication URL (optional)
 
-## Configuring the Proxy's REST API communication IP address and port (optional)
+By default, this REST API listens on port 8081 of `localhost` only.
-The Hub service talks to the proxy via a REST API on a secondary port,
+The Hub service talks to the proxy via a REST API on a secondary port. The
-whose network interface and port can be configured separately.
+API URL can be configured separately and override the default settings.
-By default, this REST API listens on port 8081 of localhost only.
 
-If running the Proxy separate from the Hub,
+### Set api_url
-configure the REST API communication IP address and port with:
+
+The URL to access the API, `c.configurableHTTPProxy.api_url`, is configurable.
+An example entry to set the proxy's API URL in `jupyterhub_config.py` is:
+
+```python
+c.ConfigurableHTTPProxy.api_url = 'http://10.0.1.4:5432'
+```
+
+### proxy_api_ip and proxy_api_port (Deprecated in 0.8)
+
+If running the Proxy separate from the Hub, configure the REST API communication
+IP address and port by adding this to the `jupyterhub_config.py` file:
 
 ```python
 # ideally a private network address
@@ -41,10 +61,15 @@ c.JupyterHub.proxy_api_ip = '10.0.1.4'
 c.JupyterHub.proxy_api_port = 5432
 ```
 
-## Configuring the Hub if Spawners or Proxy are remote or isolated in containers
+We recommend using the proxy's `api_url` setting instead of the deprecated
-The Hub service also listens only on localhost (port 8080) by default.
+settings, `proxy_api_ip` and `proxy_api_port`.
-The Hub needs needs to be accessible from both the proxy and all Spawners.
+
-When spawning local servers, an IP address setting of localhost is fine.
+## Configure the Hub if the Proxy or Spawners are remote or isolated
+
+The Hub service listens only on `localhost` (port 8080) by default.
+The Hub needs to be accessible from both the proxy and all Spawners.
+When spawning local servers, an IP address setting of `localhost` is fine.
+
 If *either* the Proxy *or* (more likely) the Spawners will be remote or
 isolated in containers, the Hub must listen on an IP that is accessible.
 
@@ -52,3 +77,12 @@ isolated in containers, the Hub must listen on an IP that is accessible.
 c.JupyterHub.hub_ip = '10.0.1.4'
 c.JupyterHub.hub_port = 54321
 ```
+
+**Added in 0.8:** The `c.JupyterHub.hub_connect_ip` setting is the ip address or
+hostname that other services should use to connect to the Hub. A common
+configuration for, e.g. docker, is:
+
+```python
+c.JupyterHub.hub_ip = '0.0.0.0'  # listen on all interfaces
+c.JupyterHub.hub_connect_ip = '10.0.1.4'  # ip as seen on the docker network. Can also be a hostname.
+```

docs/source/rest.md

@@ -1,5 +1,15 @@
 # Using JupyterHub's REST API
 
+This section will give you information on:
+
+- what you can do with the API
+- create an API token
+- add API tokens to the config files
+- make an API request programmatically using the requests library
+- learn more about JupyterHub's API
+
+## What you can do with the API
+
 Using the [JupyterHub REST API][], you can perform actions on the Hub,
 such as:
 
@@ -12,16 +22,16 @@ A [REST](https://en.wikipedia.org/wiki/Representational_state_transfer)
 API provides a standard way for users to get and send information to the
 Hub.
 
+## Create an API token
 
-## Creating an API token
 To send requests using JupyterHub API, you must pass an API token with the
 request. You can create a token for an individual user using the following
 command:
 
     jupyterhub token USERNAME
 
+## Add API tokens to the config file
 
-## Adding tokens to the config file
 You may also add a dictionary of API tokens and usernames to the hub's
 configuration file, `jupyterhub_config.py`:
 
@@ -31,16 +41,17 @@ c.JupyterHub.api_tokens = {
 }
 ```
 
-
+## Make an API request
-## Making an API request
 
 To authenticate your requests, pass the API token in the request's
 Authorization header.
 
-**Example: List the hub's users**
+### Use requests
 
-Using the popular Python requests library, the following code sends an API
+Using the popular Python [requests](http://docs.python-requests.org/en/master/)
-request and an API token for authorization:
+library, here's example code to make an API request for the users of a JupyterHub
+deployment. An API GET request is made, and the request sends an API token for
+authorization. The response contains information about the users:
 
 ```python
 import requests
@@ -57,18 +68,19 @@ r.raise_for_status()
 users = r.json()
 ```
 
-Note that the token authorizes JupyterHub REST API requests. The same token
+Note that the API token authorizes **JupyterHub** REST API requests. The same
-does **not** authorize access to the [Jupyter Notebook REST API][] provided
+token does **not** authorize access to the [Jupyter Notebook REST API][]
-by notebook servers managed by JupyterHub.
+provided by notebook servers managed by JupyterHub. A different token is used
+to access the **Jupyter Notebook** API.
 
-## Learning more about the API
+## Learn more about the API
 
-You can see the full [JupyterHub REST API][] for details.
+You can see the full [JupyterHub REST API][] for details. This REST API Spec can
-The same REST API Spec can be viewed in a more interactive style [on swagger's petstore][].
+be viewed in a more [interactive style on swagger's petstore][].
 Both resources contain the same information and differ only in its display.
 Note: The Swagger specification is being renamed the [OpenAPI Initiative][].
 
-[on swagger's petstore]: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#!/default
+[interactive style on swagger's petstore]: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyterhub/jupyterhub/master/docs/rest-api.yml#!/default
 [OpenAPI Initiative]: https://www.openapis.org/
 [JupyterHub REST API]: ./_static/rest-api/index.html
 [Jupyter Notebook REST API]: http://petstore.swagger.io/?url=https://raw.githubusercontent.com/jupyter/notebook/master/notebook/services/api/api.yaml