From 980b7f56323664936e4afee8c6fc5f6d2d86f76f Mon Sep 17 00:00:00 2001 From: Jon Koops Date: Thu, 19 Mar 2026 11:35:17 +0100 Subject: [PATCH] docs: remove legacy corporate proxy documentation All Node.js versions in Backstage's support matrix (v22 and v24 LTS) include built-in proxy support via NODE_USE_ENV_PROXY, making the legacy global-agent/undici workarounds unnecessary. Remove the legacy proxy guide from contrib/ and all references to the legacy approach across the docs. Signed-off-by: Jon Koops --- .../remove-legacy-proxy-techdocs-cli.md | 5 + .../help-im-behind-a-corporate-proxy.md | 104 ------------------ docs/features/techdocs/cli.md | 10 +- .../keeping-backstage-updated.md | 11 +- .../create-app/keeping-backstage-updated.md | 11 +- docs/tutorials/corporate-proxy.md | 4 - packages/techdocs-cli/README.md | 7 +- 7 files changed, 16 insertions(+), 136 deletions(-) create mode 100644 .changeset/remove-legacy-proxy-techdocs-cli.md delete mode 100644 contrib/docs/tutorials/help-im-behind-a-corporate-proxy.md diff --git a/.changeset/remove-legacy-proxy-techdocs-cli.md b/.changeset/remove-legacy-proxy-techdocs-cli.md new file mode 100644 index 0000000000..f99fe0f429 --- /dev/null +++ b/.changeset/remove-legacy-proxy-techdocs-cli.md @@ -0,0 +1,5 @@ +--- +'@techdocs/cli': patch +--- + +Updated proxy documentation to recommend Node.js built-in proxy support via `NODE_USE_ENV_PROXY` instead of `global-agent`. diff --git a/contrib/docs/tutorials/help-im-behind-a-corporate-proxy.md b/contrib/docs/tutorials/help-im-behind-a-corporate-proxy.md deleted file mode 100644 index 4a7e0ad233..0000000000 --- a/contrib/docs/tutorials/help-im-behind-a-corporate-proxy.md +++ /dev/null @@ -1,104 +0,0 @@ -# Legacy: Running the backend behind a Corporate Proxy - -> [!NOTE] -> On Node.js 22.21.0 or later, you can use Node.js's built-in proxy support instead of the workarounds described here. See the [recommended proxy setup guide](../../../docs/tutorials/corporate-proxy.md) for details. - -This article helps you get your backend installation up and running making calls through corporate proxies. - -## Background - -Let's admit it, we've all been there. Sometimes you have to run stuff with no way out to the public internet, except via the smallest of corporate proxy tunnels. It's most likely that you're going to run into these issues from the backend part of Backstage as that's the part that isn't helped by your browser or OS settings for the corporate proxy. - -Unfortunately, neither the Node.js native `fetch` nor the other frequently used library `node-fetch` (see [ADR013](https://backstage.io/docs/architecture-decisions/adrs-adr013)) respect `HTTP(S)_PROXY` environment variables by default. As an additional complication, there is no single solution for configuring both native `fetch` and `node-fetch` at once, uniformly. - -There are however some ways to get this to work without too much effort. - -## Installation - -**Note:** You're going to want to be in your backend working directory for these solutions as that's where the requests come from that don't go through this proxy. - -1. Install the required packages in your backend, by running the following command inside your backend directory (typically `packages/backend` under your repository root). - - ```bash - yarn add undici global-agent - ``` - - `undici` exposes the settings for native `fetch`, and `global-agent` can set things up for `node-fetch`. - -1. Go to the entry file for the backend (typically `packages/backend/src/index.ts`), and add the following at the VERY top, before all other imports etc: - - ```ts - import 'global-agent/bootstrap'; - import { setGlobalDispatcher, EnvHttpProxyAgent } from 'undici'; - - setGlobalDispatcher(new EnvHttpProxyAgent()); - ``` - - The first import automatically bootstraps `global-agent`, which addresses `node-fetch` proxying. The lines below that set up the `undici` package which affects native `fetch`. - -1. Start the backend with the correct environment variables set. For example: - - ```sh - export HTTP_PROXY=http://username:password@proxy.example.net:8888 - export GLOBAL_AGENT_HTTP_PROXY=${HTTP_PROXY} - yarn start - ``` - - The default for `global-agent` is to have a prefix on the variable names, hence the need for specifying it twice. For further information about `HTTP(S)_PROXY` and `NO_PROXY` excludes, see [the global-agent documentation](https://github.com/gajus/global-agent) and [undici documentation](https://github.com/nodejs/undici). - -## Configuration - -If your development environment is in the cloud (like with [AWS Cloud9](https://aws.amazon.com/cloud9/) or an instance of [Theia](https://theia-ide.org/)), you will need to update your configuration. - -You will probably need to make some changes in `app-config.yaml` (or another config file like `app-config.local.yaml` if you've created it, see the [configuration doc](https://backstage.io/docs/conf/#supplying-configuration)). -The exact values will depend on your setup but for instance, if your public URL is `https://your-public-url.com` and the port `3000` and `8080` are open: - -```yaml -app: - baseUrl: https://your-public-url.com:3000 - listen: - host: 0.0.0.0 # This makes the dev server bind to all IPv4 interfaces and not just the baseUrl hostname - -backend: - baseUrl: https://your-public-url.com:8080 - listen: - port: 8080 - cors: - origin: https://your-public-url.com:3000 -``` - -The app port must proxy web socket connections in order to make hot reloading work. - -## Alternatives to `global-agent` - -The `proxy-agent` package can be used as an alternative to `global-agent` (do not install both!), and also ensures that the `node-fetch` library correctly respects proxy settings, but [does NOT work](https://github.com/TooTallNate/proxy-agents/issues/239) for modern `undici` based native Node.js `fetch`, so you'll still have to also do the `undici` steps in the section above in addition to this. - -`proxy-agent` is a library that you can use to override the `globalAgents` of `node` land with a tunnel to use for each request. - -1. Install `proxy-agent` using `yarn add proxy-agent` -2. Go to the entry file for the backend (`src/index.ts`) -3. At the top of the file paste the following: - - ```ts - import ProxyAgent from 'proxy-agent'; - import http from 'http'; - import https from 'https'; - - /* - Something to note here, this might need different configuration depending on your own setup. - If you only have an http_proxy then you'll need to set that as both the http and https globalAgent instead. - */ - if (process.env.HTTP_PROXY) { - http.globalAgent = new ProxyAgent(process.env.HTTP_PROXY); - } - - if (process.env.HTTPS_PROXY) { - https.globalAgent = new ProxyAgent(process.env.HTTPS_PROXY); - } - ``` - -4. Start the backend with `yarn start` - -## Backstage CLI - -The Backstage CLI [versions:bump](https://backstage.io/docs/tooling/cli/commands#versionsbump) command also supports proxies via `global-agent` environment variable configuration. See the [keeping Backstage updated](https://backstage.io/docs/getting-started/keeping-backstage-updated/#proxy) docs for more information. diff --git a/docs/features/techdocs/cli.md b/docs/features/techdocs/cli.md index fa3d9148e2..7d3e0c209c 100644 --- a/docs/features/techdocs/cli.md +++ b/docs/features/techdocs/cli.md @@ -208,15 +208,7 @@ Options: #### Publishing from behind a proxy -On Node.js 22.21.0+, set `NODE_USE_ENV_PROXY=1` along with `HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY` to route TechDocs publishing through a proxy. See the [corporate proxy guide](../../tutorials/corporate-proxy.md) for details. - -On older Node.js versions, the TechDocs CLI leverages `global-agent` to navigate the proxy. To enable `global-agent`, the following variables need to be set prior to running the techdocs-cli command: - -```bash -export GLOBAL_AGENT_HTTP_PROXY=${HTTP_PROXY} -export GLOBAL_AGENT_HTTPS_PROXY=${HTTPS_PROXY} -export GLOBAL_AGENT_NO_PROXY=${NO_PROXY} -``` +Set `NODE_USE_ENV_PROXY=1` along with `HTTP_PROXY`/`HTTPS_PROXY`/`NO_PROXY` to route TechDocs publishing through a proxy. See the [corporate proxy guide](../../tutorials/corporate-proxy.md) for details. ### Migrate content for case-insensitive access diff --git a/docs/getting-started/keeping-backstage-updated.md b/docs/getting-started/keeping-backstage-updated.md index a55f872f53..ce2f4a477c 100644 --- a/docs/getting-started/keeping-backstage-updated.md +++ b/docs/getting-started/keeping-backstage-updated.md @@ -151,9 +151,7 @@ down the number of duplicate packages. ## Proxy -On Node.js 22.21.0+, the Backstage CLI respects the standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables when `NODE_USE_ENV_PROXY=1` is set. See the [corporate proxy guide](../tutorials/corporate-proxy.md) for full details. - -On older Node.js versions, the CLI falls back to [global-agent](https://www.npmjs.com/package/global-agent) and `undici` for proxy support, which require their own environment variables (prefixed with `GLOBAL_AGENT_`). This allows you to route the CLI’s network traffic through a proxy server, which can be useful in environments with restricted internet access. +The Backstage CLI respects the standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables when `NODE_USE_ENV_PROXY=1` is set. See the [corporate proxy guide](../tutorials/corporate-proxy.md) for full details. Additionally, yarn needs a proxy too (sometimes), when in environments with restricted internet access. It uses different settings than the other modules. If you decide to use the backstage yarn plugin [mentioned above](#plugin), you will need to set additional proxy values. If you will always need proxy settings in all environments and situations, you can add `httpProxy` and `httpsProxy` values to [the yarnrc.yml file](https://yarnpkg.com/configuration/yarnrc). If some environments need it (say a developer workstation) but other environments do not (perhaps a CI build server running on AWS), then you may not want to update the yarnrc.yml file but just set environment variables `YARN_HTTP_PROXY` and `YARN_HTTPS_PROXY` in the environments/situations where you need to proxy. @@ -164,12 +162,9 @@ If you will always need proxy settings in all environments and situations, you c ```bash export HTTP_PROXY=http://proxy.company.com:8080 -export HTTPS_PROXY=https://secure-proxy.company.com:8080 +export HTTPS_PROXY=http://proxy.company.com:8080 export NO_PROXY=localhost,internal.company.com -export NODE_USE_ENV_PROXY=1 # Node.js 22.21.0+ -export GLOBAL_AGENT_HTTP_PROXY=${HTTP_PROXY} # Node.js < 22.21.0 -export GLOBAL_AGENT_HTTPS_PROXY=${HTTPS_PROXY} # Node.js < 22.21.0 -export GLOBAL_AGENT_NO_PROXY=${NO_PROXY} # Node.js < 22.21.0 +export NODE_USE_ENV_PROXY=1 export YARN_HTTP_PROXY=${HTTP_PROXY} # optional export YARN_HTTPS_PROXY=${HTTPS_PROXY} # optional ``` diff --git a/docs/golden-path/create-app/keeping-backstage-updated.md b/docs/golden-path/create-app/keeping-backstage-updated.md index b0561e5304..9663ed6690 100644 --- a/docs/golden-path/create-app/keeping-backstage-updated.md +++ b/docs/golden-path/create-app/keeping-backstage-updated.md @@ -142,9 +142,7 @@ down the number of duplicate packages. ## Proxy -On Node.js 22.21.0+, the Backstage CLI respects the standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables when `NODE_USE_ENV_PROXY=1` is set. See the [corporate proxy guide](../../tutorials/corporate-proxy.md) for full details. - -On older Node.js versions, the CLI falls back to [global-agent](https://www.npmjs.com/package/global-agent) and `undici` for proxy support, which require their own environment variables (prefixed with `GLOBAL_AGENT_`). This allows you to route the CLI’s network traffic through a proxy server, which can be useful in environments with restricted internet access. +The Backstage CLI respects the standard `HTTP_PROXY`, `HTTPS_PROXY`, and `NO_PROXY` environment variables when `NODE_USE_ENV_PROXY=1` is set. See the [corporate proxy guide](../../tutorials/corporate-proxy.md) for full details. Additionally, `yarn` needs a proxy too (sometimes), when in environments with restricted internet access. It uses different settings than the other modules. If you decide to use the backstage yarn plugin [mentioned above](#plugin), you will need to set additional proxy values. If you will always need proxy settings in all environments and situations, you can add `httpProxy` and `httpsProxy` values to [the yarnrc.yml file](https://yarnpkg.com/configuration/yarnrc). If some environments need it (say a developer workstation) but other environments do not (perhaps a CI build server running on AWS), then you may not want to update the yarnrc.yml file but just set environment variables `YARN_HTTP_PROXY` and `YARN_HTTPS_PROXY` in the environments/situations where you need to proxy. @@ -155,12 +153,9 @@ If you will always need proxy settings in all environments and situations, you c ```bash export HTTP_PROXY=http://proxy.company.com:8080 -export HTTPS_PROXY=https://secure-proxy.company.com:8080 +export HTTPS_PROXY=http://proxy.company.com:8080 export NO_PROXY=localhost,internal.company.com -export NODE_USE_ENV_PROXY=1 # Node.js 22.21.0+ -export GLOBAL_AGENT_HTTP_PROXY=${HTTP_PROXY} # Node.js < 22.21.0 -export GLOBAL_AGENT_HTTPS_PROXY=${HTTPS_PROXY} # Node.js < 22.21.0 -export GLOBAL_AGENT_NO_PROXY=${NO_PROXY} # Node.js < 22.21.0 +export NODE_USE_ENV_PROXY=1 export YARN_HTTP_PROXY=${HTTP_PROXY} # optional export YARN_HTTPS_PROXY=${HTTPS_PROXY} # optional ``` diff --git a/docs/tutorials/corporate-proxy.md b/docs/tutorials/corporate-proxy.md index e4346e4f94..ad03a436cf 100644 --- a/docs/tutorials/corporate-proxy.md +++ b/docs/tutorials/corporate-proxy.md @@ -27,7 +27,3 @@ yarn start Per [ADR014](../architecture-decisions/adr014-use-fetch.md), Backstage backend code should use native `fetch()`, which works with Node.js's proxy out of the box. Some core packages and many [community plugins](https://github.com/backstage/community-plugins/) still use `node-fetch` (see [ADR013](../architecture-decisions/adr013-use-node-fetch.md)) or `cross-fetch` (for isomorphic packages). Both libraries delegate to `node:http`/`node:https` internally and do **not** set a custom HTTP agent by default, which means Node.js's proxy works for them as well. The exception is code that explicitly passes a custom `agent` to its fetch calls (e.g. the Kubernetes plugins, which use `new https.Agent(...)` for TLS client certificates). In those cases, the custom agent takes precedence and the built-in proxy is bypassed. This is generally the desired behavior, since those agents are configured for direct connections to specific endpoints like cluster APIs. - -## Legacy approach - -If you are on a Node.js version older than 22.21.0, you can use third-party packages to add proxy support. See the [legacy proxy setup guide](https://github.com/backstage/backstage/blob/master/contrib/docs/tutorials/help-im-behind-a-corporate-proxy.md) for instructions using `undici`, `global-agent`, and `proxy-agent`. diff --git a/packages/techdocs-cli/README.md b/packages/techdocs-cli/README.md index 22f0093067..82dd0911cf 100644 --- a/packages/techdocs-cli/README.md +++ b/packages/techdocs-cli/README.md @@ -44,9 +44,10 @@ yarn techdocs-cli:dev [...options] ```sh # Prior to executing the techdocs-cli command -export GLOBAL_AGENT_HTTP_PROXY=${HTTP_PROXY} -export GLOBAL_AGENT_HTTPS_PROXY=${HTTPS_PROXY} -export GLOBAL_AGENT_NO_PROXY=${NO_PROXY} +export HTTP_PROXY=http://proxy.company.com:8080 +export HTTPS_PROXY=http://proxy.company.com:8080 +export NO_PROXY=localhost,internal.company.com +export NODE_USE_ENV_PROXY=1 ``` ### Using an example docs project