{"id":17545,"library":"configurable-http-proxy","title":"Configurable HTTP Proxy","description":"`configurable-http-proxy` (CHP) is a robust HTTP proxy designed to dynamically manage routing tables via either a command-line interface or a REST API. Built as a wrapper around `node-http-proxy`, it extends the underlying library's capabilities to include WebSocket support, making it suitable for reverse proxies and load balancers. The package is a core component in JupyterHub deployments, enabling flexible routing for multi-user environments. The current stable version is 5.2.0, requiring Node.js 20 or newer. Releases typically align with JupyterHub's development cycle, focusing on stability, security, and integration within the Jupyter ecosystem. Its key differentiator is the on-the-fly reconfigurability of routes and its robust API for programmatic control, allowing for complex, dynamic proxying scenarios. It operates with distinct public-facing and inward-facing REST API servers, each with configurable IPs and ports.","status":"active","version":"5.2.0","language":"javascript","source_language":"en","source_url":"https://github.com/jupyterhub/configurable-http-proxy","tags":["javascript"],"install":[{"cmd":"npm install configurable-http-proxy","lang":"bash","label":"npm"},{"cmd":"yarn add configurable-http-proxy","lang":"bash","label":"yarn"},{"cmd":"pnpm add configurable-http-proxy","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core proxying library that configurable-http-proxy wraps and extends.","package":"node-http-proxy","optional":false},{"reason":"Used for command-line interface parsing.","package":"node-commander","optional":false},{"reason":"Used for logging within the proxy.","package":"node-winston","optional":false}],"imports":[{"note":"The package primarily exposes the ConfigurableProxy class as a default export for programmatic use. It is predominantly used as a standalone CLI tool or service, with direct programmatic instantiation being less common.","wrong":"import { ConfigurableProxy } from 'configurable-http-proxy';\nconst ConfigurableProxy = require('configurable-http-proxy').ConfigurableProxy;","symbol":"ConfigurableProxy","correct":"import ConfigurableProxy from 'configurable-http-proxy';"}],"quickstart":{"code":"#!/usr/bin/env bash\n\n# Set a token for API authentication (important for security)\nexport CONFIGPROXY_AUTH_TOKEN=\"$(head /dev/urandom | tr -dc A-Za-z0-9_ | head -c 32)\"\n\n# Install globally if not already installed\n# npm install -g configurable-http-proxy\n\n# Start the configurable-http-proxy with a default target\n# and distinct public/API ports.\n# The public-facing proxy listens on port 8080.\n# The REST API for configuration listens on port 8001.\n# All traffic not matching a route will be forwarded to http://localhost:8000.\nconfigurable-http-proxy \\\n  --default-target=http://localhost:8000 \\\n  --api-ip=127.0.0.1 \\\n  --api-port=8001 \\\n  --port=8080 \\\n  --ip=0.0.0.0 \\\n  --log-level=debug\n\necho \"Proxy started. Public interface on http://localhost:8080. API on http://127.0.0.1:8001.\"\necho \"Use CONFIGPROXY_AUTH_TOKEN for API requests: $CONFIGPROXY_AUTH_TOKEN\"","lang":"bash","description":"This script demonstrates how to start `configurable-http-proxy` as a standalone service, setting up a default routing target and configuring both the public-facing and REST API interfaces with a security token."},"warnings":[{"fix":"Upgrade your Node.js environment to version 20 or newer. Consider using a Node Version Manager (nvm) for easy switching between versions.","message":"configurable-http-proxy version 5.x and newer requires Node.js version 20 or greater. Attempting to run on older Node.js versions will result in a runtime error.","severity":"breaking","affected_versions":">=5.0.0"},{"fix":"Ensure the `CONFIGPROXY_AUTH_TOKEN` environment variable is set with a strong, secret token before starting the proxy. For API calls, include this token in the `Authorization` header as `token <YOUR_TOKEN>`.","message":"The REST API for `configurable-http-proxy` requires a security token for authentication, set via the `CONFIGPROXY_AUTH_TOKEN` environment variable. Failing to set this token or providing an incorrect one will prevent API access and route management.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always bind the API to a restricted IP address (e.g., `127.0.0.1` or a private network interface) and ensure network firewalls restrict access to the API port. Only expose the public-facing proxy as needed.","message":"By default, `configurable-http-proxy` runs two distinct HTTP(S) servers: a public-facing interface (--ip, --port) and an inward-facing REST API (--api-ip, --api-port). The API defaults to listening on localhost. Exposing the API publicly (e.g., `--api-ip=0.0.0.0`) without proper network-level access control is a significant security risk, especially with an improperly managed token.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"Always specify a `--default-target` when starting the proxy, pointing to a fallback service (e.g., a JupyterHub instance or an error page server) to gracefully handle unrouted requests.","message":"When no specific route matches an incoming request, `configurable-http-proxy` uses a `--default-target`. If no default target is set and no route matches, the proxy will return a 404 error. This can be problematic if you expect all traffic to be handled or redirected.","severity":"gotcha","affected_versions":">=1.0.0"},{"fix":"For project-specific deployments, consider installing `configurable-http-proxy` as a development dependency (`npm install --save-dev configurable-http-proxy`) and running it via `npx` or a script defined in `package.json` to ensure version isolation.","message":"The README suggests global installation via `npm install -g configurable-http-proxy`. While convenient, global Node.js packages can lead to version conflicts and inconsistencies across different projects or environments.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-23T00:00:00.000Z","next_check":"2026-07-22T00:00:00.000Z","problems":[{"fix":"Choose an available port or terminate the process currently using the port. You can find processes using a port with `lsof -i :[port]` (Linux/macOS) or `netstat -ano | findstr :[port]` (Windows).","cause":"The specified public-facing port (--port) or API port (--api-port) is already in use by another process on the system.","error":"Error: listen EADDRINUSE :::[port]"},{"fix":"Ensure the `CONFIGPROXY_AUTH_TOKEN` environment variable is correctly set when starting the proxy. For API calls, include the `Authorization` header with the correct token: `curl -H \"Authorization: token $CONFIGPROXY_AUTH_TOKEN\" http://localhost:8001/api/routes`.","cause":"An API request was made to `configurable-http-proxy` without a valid `Authorization: token <TOKEN>` header, or the provided token does not match `CONFIGPROXY_AUTH_TOKEN`.","error":"Error: HTTP 401 Unauthorized"},{"fix":"Upgrade your Node.js installation to version 20 or newer. Use a Node Version Manager like `nvm install 20 && nvm use 20` to manage versions.","cause":"Running `configurable-http-proxy` on an incompatible Node.js version, especially one older than 20, leading to syntax errors from newer JavaScript features.","error":"SyntaxError: Unexpected token 'catch' (or similar Node.js engine error)"},{"fix":"Restart the proxy with a `--default-target` option, e.g., `configurable-http-proxy --default-target=http://localhost:8000 ...` to direct unrouted traffic to a fallback service.","cause":"The proxy received a request for a path that does not have an explicit route configured, and no `--default-target` was specified when the proxy was started.","error":"Error: No default target configured and no route found for /"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}