• Stars
    star
    243
  • Rank 166,489 (Top 4 %)
  • Language
    JavaScript
  • License
    BSD 3-Clause "New...
  • Created about 10 years ago
  • Updated about 1 month ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

node-http-proxy plus a REST API

configurable-http-proxy

npm Docker Build status GitHub Workflow Status - Test GitHub Discourse Gitter

configurable-http-proxy (CHP) provides you with a way to update and manage a proxy table using a command line interface or REST API. It is a simple wrapper around node-http-proxy. node-http-proxy is an HTTP programmable proxying library that supports websockets and is suitable for implementing components such as reverse proxies and load balancers. By wrapping node-http-proxy, configurable-http-proxy extends this functionality to JupyterHub deployments.

Table of Contents

Install

Prerequisite: Node.js ≥ 10

If you're installing configurable-http-proxy in Linux, you can follow the instruction of nodesource to install arbitrary version of Node.js.

To install the configurable-http-proxy package globally using npm:

npm install -g configurable-http-proxy

To install from the source code found in this GitHub repo:

git clone https://github.com/jupyterhub/configurable-http-proxy
cd configurable-http-proxy
npm install  # Use 'npm install -g' for global install

Return to top

Usage

The configurable proxy runs two HTTP(S) servers:

  • The public-facing interface to your application (controlled by --ip, --port)
    • listens on all interfaces by default.
  • The inward-facing REST API (--api-ip, --api-port)
    • listens on localhost by default
    • The REST API uses token authorization, where the token is set in the CONFIGPROXY_AUTH_TOKEN environment variable.

Return to top

Starting the proxy

configurable-http-proxy [options]

where [options] are the command-line options described below.

Return to top

Setting a default target

The default target is used when a client has requested a URL for which there is no routing target found in the proxy table. To set a default target, pass the command line option, --default-target, when starting the configurable proxy:

configurable-http-proxy --default-target=proto://host[:port]

For example:

configurable-http-proxy --default-target=http://localhost:8888

Return to top

Command-line options

Usage: configurable-http-proxy [options]

Options:
  -V, --version                      output the version number
  --ip <ip-address>                  Public-facing IP of the proxy
  --port <n> (defaults to 8000)      Public-facing port of the proxy
  --ssl-key <keyfile>                SSL key to use, if any
  --ssl-cert <certfile>              SSL certificate to use, if any
  --ssl-ca <ca-file>                 SSL certificate authority, if any
  --ssl-request-cert                 Request SSL certs to authenticate clients
  --ssl-reject-unauthorized          Reject unauthorized SSL connections (only meaningful if --ssl-request-cert is given)
  --ssl-protocol <ssl-protocol>      Set specific SSL protocol, e.g. TLSv1_2, SSLv3
  --ssl-ciphers <ciphers>            `:`-separated ssl cipher list. Default excludes RC4
  --ssl-allow-rc4                    Allow RC4 cipher for SSL (disabled by default)
  --ssl-dhparam <dhparam-file>       SSL Diffie-Helman Parameters pem file, if any
  --api-ip <ip>                      Inward-facing IP for API requests (default: "localhost")
  --api-port <n>                     Inward-facing port for API requests (defaults to --port=value+1)
  --api-ssl-key <keyfile>            SSL key to use, if any, for API requests
  --api-ssl-cert <certfile>          SSL certificate to use, if any, for API requests
  --api-ssl-ca <ca-file>             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)
  --client-ssl-key <keyfile>         SSL key to use, if any, for proxy to client requests
  --client-ssl-cert <certfile>       SSL certificate to use, if any, for proxy to client requests
  --client-ssl-ca <ca-file>          SSL certificate authority, if any, for proxy to client requests
  --client-ssl-request-cert          Request SSL certs to authenticate clients for API requests
  --client-ssl-reject-unauthorized   Reject unauthorized SSL connections (only meaningful if --client-ssl-request-cert is given)
  --default-target <host>            Default proxy target (proto://host[:port])
  --error-target <host>              Alternate server for handling proxy errors (proto://host[:port])
  --error-path <path>                Alternate server for handling proxy errors (proto://host[:port])
  --redirect-port <redirect-port>    Redirect HTTP requests on this port to the server on HTTPS
  --redirect-to <port>               Redirect HTTP requests from --redirect-port to this port
  --pid-file <pid-file>              Write our PID to a file
  --no-x-forward                     Don't add 'X-forward-' headers to proxied requests
  --no-prepend-path                  Avoid prepending target paths to proxied requests
  --no-include-prefix                Don't include the routing prefix in proxied requests
  --auto-rewrite                     Rewrite the Location header host/port in redirect responses
  --change-origin                    Changes the origin of the host header to the target URL
  --protocol-rewrite <proto>         Rewrite the Location header protocol in redirect responses to the specified protocol
  --custom-header <header>           Custom header to add to proxied requests. Use same option for multiple headers (--custom-header k1:v1 --custom-header k2:v2) (default: {})
  --insecure                         Disable SSL cert verification
  --host-routing                     Use host routing (host as first level of path)
  --metrics-ip <ip>                  IP for metrics server (default: "0.0.0.0")
  --metrics-port <n>                 Port of metrics server. Defaults to no metrics server
  --log-level <loglevel>             Log level (debug, info, warn, error) (default: "info")
  --timeout <n>                      Timeout (in millis) when proxy drops connection for a request.
  --proxy-timeout <n>                Timeout (in millis) when proxy receives no response from target.
  --storage-backend <storage-class>  Define an external storage class. Defaults to in-MemoryStore.
  -h, --help                         display help for command

Return to top

Using the REST API

The configurable-http-proxy REST API is documented and available as:

Return to top

REST API Basics

API Root

HTTP method Endpoint Function
GET /api/ API Root

Routes

HTTP method Endpoint Function
GET /api/routes Get all routes in routing table
POST /api/routes/{route_spec} Add a new route
DELETE /api/routes/{route_spec} Remove the given route

Return to top

Authenticating via passing a token

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, this curl command entered in the terminal passes this header "Authorization: token $CONFIGPROXY_AUTH_TOKEN" for authentication and retrieves the current routing table from this endpoint, http://localhost:8001/api/routes:

curl -H "Authorization: token $CONFIGPROXY_AUTH_TOKEN" http://localhost:8001/api/routes

Return to top

Getting the routing table

Request:

GET /api/routes[?inactive_since=ISO8601-timestamp]

Parameters:

inactive_since: If the inactive_since URL parameter is given as an ISO8601 timestamp, only routes whose last_activity is earlier than the timestamp will be returned. The last_activity timestamp is updated whenever the proxy passes data to or from the proxy target.

Response:

Status code

status: 200 OK

Response body

A JSON dictionary of the current routing table. This JSON dictionary excludes the default route.

Behavior:

The current routing table is returned to the user if the request is successful.

Return to top

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]

Required input:

target: The host URL

Example request body:

{
  "target": "http://localhost:8002"
}

Response:

status: 201 Created

Behavior:

After adding the new route, any request to /path/prefix on the proxy's public interface will be proxied to target.

Return to top

Deleting routes

Request:

DELETE /api/routes/[:path]

Response:

status: 204 No Content

Behavior:

Removes a route from the proxy's routing table.

Return to top

Custom error pages

Custom error pages can be provided when the proxy encounters an error and has no proxy target to handle a request. There are two typical errors that CHP may hit, along with their status code:

  • 404 error: Returned when a client has requested a URL for which there is no routing target. This error can be prevented by setting a default target before starting the configurable-http-proxy.

  • 503 error: Returned when a route exists, but the upstream server isn't responding. This is more common, and can be due to any number of reasons, including the target service having died, not finished starting, or network instability.

Return to top

Setting the path for custom error pages

When starting the CHP, specify an error path --error-path /usr/share/chp-errors to the location of the error page:

configurable-http-proxy --error-path /usr/share/chp-errors

When a proxy error occurs, CHP will look in the following location for a custom html error page to serve:

/usr/share/chp-errors/{CODE}.html

where {CODE} is a status code number for an html page to serve. If there is a 503 error, CHP will look for a custom error page in this location /usr/share/chp-errors/503.html.

If no custom error html file exists for the error code, CHP will use the default error.html. If you specify an error path, make sure you also create a default error.html file.

Return to top

Setting a target for custom error handling

You can specify a target URL to use when errors occur by setting --error-target {URL} when starting the CHP.

If, for example, CHP starts with --error-target http://localhost:1234, and the proxy encounters an error, the proxy will make a GET request to the error-target server. The GET request will be sent to the error-target server URL, http://localhost:1234, appending the status code /{CODE}, and passing the failing request's URL escaped in a URL parameter:

GET /404?url=%2Fescaped%2Fpath

Return to top

Host-based routing

If the CHP is started with the --host-routing option, the proxy will use the hostname of the incoming request to select a target.

When using host-based routes, the API uses the target in the same way as if the hostname were the first part of the URL path, e.g.:

{
  "/example.com": "https://localhost:1234",
  "/otherdomain.biz": "http://10.0.1.4:5555",
}

Return to top

Troubleshooting

Q: My proxy is not starting. What could be happening?

  • If this occurs on Ubuntu/Debian, check that the you are using a recent version of node. Some versions of Ubuntu/Debian come with a version of node that is very old, and it is necessary to update node to a recent or LTS version.

Return to top

More Repositories

1

jupyterhub

Multi-user server for Jupyter notebooks
Python
7,778
star
2

binderhub

Run your code in the cloud, with technology so advanced, it feels like magic!
Python
2,557
star
3

repo2docker

Turn repositories into Jupyter-enabled Docker images
Python
1,621
star
4

zero-to-jupyterhub-k8s

Helm Chart & Documentation for deploying JupyterHub on Kubernetes
Python
1,551
star
5

the-littlest-jupyterhub

Simple JupyterHub distribution for 1-100 users on a single server
Python
1,038
star
6

jupyterhub-deploy-docker

Reference deployment of JupyterHub with docker
Python
699
star
7

kubespawner

Kubernetes spawner for JupyterHub
Python
546
star
8

dockerspawner

Spawns JupyterHub single user servers in Docker containers
Python
489
star
9

oauthenticator

OAuth + JupyterHub Authenticator = OAuthenticator
Python
413
star
10

jupyter-server-proxy

Jupyter notebook server extension to proxy web services.
Python
351
star
11

jupyterhub-deploy-teaching

Reference deployment of JupyterHub and nbgrader on a single server
Jinja
247
star
12

nbgitpuller

Jupyter server extension to sync a git repository one-way to a local path
Python
212
star
13

ldapauthenticator

LDAP Authenticator Plugin for Jupyter
Python
206
star
14

jupyterhub-tutorial

Tutorial materials for deploying JupyterHub
Shell
196
star
15

batchspawner

Custom Spawner for Jupyterhub to start servers in batch scheduled systems
Python
188
star
16

helm-chart

A store of Helm chart tarballs for deploying JupyterHub and BinderHub on a Kubernetes cluster
187
star
17

jupyterlab-hub

Deprecated: JupyterLab extension for running JupyterLab with JupyterHub
TypeScript
181
star
18

mybinder.org-user-guide

Turn a Git repo into a collection of interactive notebooks. This is Binder's user documentation repository.
Python
158
star
19

repo2docker-action

A GitHub action to build data science environment images with repo2docker and push them to registries.
Shell
142
star
20

jupyter-rsession-proxy

Jupyter extensions for running an RStudio rsession proxy
Python
119
star
21

jupyter-remote-desktop-proxy

Run a Linux Desktop on a JupyterHub
Python
113
star
22

jupyterhub-idle-culler

JupyterHub service to cull idle servers and users
Python
101
star
23

systemdspawner

Spawn JupyterHub single-user notebook servers with systemd
Python
92
star
24

jupyterhub-the-hard-way

Understanding JupyterHub by deploying it step by step
81
star
25

mybinder.org-deploy

Deployment config files for mybinder.org
Jupyter Notebook
76
star
26

nativeauthenticator

JupyterHub-native User Authenticator
Python
72
star
27

ltiauthenticator

A JupyterHub authenticator for LTI
Python
68
star
28

team-compass

A repository for team interaction, syncing, and handling meeting notes across the JupyterHub ecosystem.
Jupyter Notebook
62
star
29

wrapspawner

Mechanism for runtime configuration of spawners for JupyterHub
Python
60
star
30

hubshare

A directory sharing service for JupyterHub
Python
57
star
31

chartpress

automate building and publishing images for helm charts
Python
55
star
32

grafana-dashboards

Grafana Dashboards useful for k8s + JupyterHub
Jsonnet
55
star
33

traefik-proxy

JupyterHub proxy implementation with traefik
Jupyter Notebook
54
star
34

sudospawner

Spawn JupyterHub single-user servers with sudo
Python
50
star
35

firstuseauthenticator

JupyterHub Authenticator that lets users set passwords when they first log in
Python
48
star
36

jupyterhub-deploy-hpc

Documented examples of Jupyterhub deployment in HPC settings
Python
36
star
37

jupyterhub-example-kerberos

Example for experimenting with how JupyterHub can be configured to work with Kerberos
Python
33
star
38

outreachy

Tasks, management and documentation for Outreachy Internships in JupyterHub
Python
33
star
39

pebble-helm-chart

To deploy a server to replace Let's Encrypt in externally unreachable CI environment for testing purposes.
Shell
28
star
40

dummyauthenticator

A Dummy JupyterHub Authenticator to make testing easy
Python
28
star
41

gh-scoped-creds

Provide fine-grained push access to GitHub from a JupyterHub
Python
26
star
42

action-k3s-helm

A GitHub action to install K3S, Calico, and Helm.
25
star
43

tmpauthenticator

JupyterHub authenticator that hands out temporary accounts for everyone. For use in tmpnb.org
Python
22
star
44

yarnspawner

Spawn JupyterHub single user notebook servers in Hadoop/YARN containers.
Python
19
star
45

jupyterhub-on-hadoop

Documentation and resources for deploying JupyterHub on Hadoop
Shell
18
star
46

simpervisor

Simple Python3 Supervisor library
Python
12
star
47

kerberosauthenticator

A JupyterHub authenticator using Kerberos
Python
11
star
48

nullauthenticator

Null Authenticator for JupyterHub instances that should have no login mechanism
Python
9
star
49

binder-data

A place to store data for Binder
Jupyter Notebook
9
star
50

docker-image-cleaner

Python script to cleanup unused docker images
Python
9
star
51

action-k8s-await-workloads

A Github Action to await k8s workloads to become Ready
TypeScript
8
star
52

research-facilities

resources for developing, deploying, and using Jupyter at Research Facilities
8
star
53

simplespawner

A simple variant of LocalProcessSpawner for JupyterHub that doesn't require users exist on the system
Python
6
star
54

action-k8s-namespace-report

GitHub Action to report info and logs from the current namespace.
Shell
6
star
55

pytest-jupyterhub

Reusable pytest plugin for testing JupyterHub's components
Python
5
star
56

binder-billing

A repository to explore billing data for mybinder.org
Jupyter Notebook
3
star
57

autodoc-traits

Sphinx extension to autodocument traitlets
Python
3
star
58

action-major-minor-tag-calculator

GitHub action to calculate major and minor semver tags, e.g. for tagging containers
JavaScript
3
star
59

mybinder-tools

Some tools for munging and utilizing kubectl
Jupyter Notebook
2
star
60

jhub-proposals

Repo for collecting conference proposals, proceedings, &c.
2
star
61

design

A collection of design material for JupyterHub and related projects
2
star
62

alabaster-jupyterhub

A slight modification of the Alabaster theme for use with JupyterHub projects
CSS
2
star
63

katacoda-scenarios

https://katacoda.com/ is a playground for learning, and these are our learning scenarios
1
star
64

nbgitpuller-downloader-googledrive

Python
1
star
65

jupyterhub-python-repo-template

A template for generating Python repositories in the `jupyterhub` organization
Python
1
star
66

.github

1
star
67

nbgitpuller-downloader-plugins

jupyterhub/nbgitpuller allows for content provider plugins, this python package provides downloader plugins
Python
1
star