Merge pull request backstage#28529 from backstage/freben/proxy-doc

update the corp proxy doc too

contrib/docs/tutorials/help-im-behind-a-corporate-proxy.md

@@ -22,43 +22,27 @@ There are however some ways to get this to work without too much effort.
 
    `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 top:
+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, ProxyAgent } from 'undici';
-
-   const proxyEnv =
-     process.env.GLOBAL_AGENT_HTTP_PROXY ||
-     process.env.GLOBAL_AGENT_HTTPS_PROXY;
-
-   if (proxyEnv) {
-     const proxyUrl = new URL(proxyEnv);
-     setGlobalDispatcher(
-       new ProxyAgent({
-         uri: proxyUrl.protocol + proxyUrl.host,
-         token:
-           proxyUrl.username && proxyUrl.password
-             ? `Basic ${Buffer.from(
-                 `${proxyUrl.username}:${proxyUrl.password}`,
-               ).toString('base64')}`
-             : undefined,
-       }),
-     );
-   }
-   ```
+   import { setGlobalDispatcher, EnvHttpProxyAgent } from 'undici';
 
-   The first import automatically bootstraps `global-agent`, which addresses `node-fetch` proxying. The lines of code below that peeks into the same environment variables as `global-agent` uses, and also leverages them to set up the `undici` package which affects native `fetch`. Does that seem weird? Yes, we think so too. But in the current state of the Node.js ecosystem, that's how it works.
+   setGlobalDispatcher(new EnvHttpProxyAgent());
+   ```
 
-   This code is kept brief for illustrative purposes. You may want to adjust it slightly if you need support for [no-proxy excludes](https://gist.github.com/zicklag/1bb50db6c5138de347c224fda14286da) or only do proxying in local development etc. Also see [the `global-agent` docs](https://github.com/gajus/global-agent) for information about its configuration options.
+   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 GLOBAL_AGENT_HTTP_PROXY=http://username:[email protected]:8888
+   export HTTP_PROXY=http://username:[email protected]: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.
+
 ## 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.

docs/getting-started/keeping-backstage-updated.md

@@ -141,19 +141,22 @@ down the number of duplicate packages.
 
 ## Proxy
 
-The Backstage CLI uses [global-agent](https://www.npmjs.com/package/global-agent) to configure HTTP/HTTPS proxy settings using environment variables. 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 uses [global-agent](https://www.npmjs.com/package/global-agent) and `undici` to configure HTTP/HTTPS proxy settings using environment variables. This allows you to route the CLI’s network traffic through a proxy server, which can be useful in environments with restricted internet access.
 
-Additionally, yarn needs a proxy too (sometimes), when in environments with restricted internet access. It uses different settings than the global-agent module. If you decide to use the backstage yarn plugin [mentioned above](#plugin), you will need to set additional proxy values.
+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.
 
 **If you plan to use the backstage yarn plugin, you will need these extra yarn proxy settings to both install the plugin and run the `versions:bump` command**. If you do not plan to use the backstage yarn plugin, it seems like the global agent proxy settings alone are sufficient.
 
 ### Example Configuration
 
 ```bash
-export GLOBAL_AGENT_HTTP_PROXY=http://proxy.company.com:8080
-export GLOBAL_AGENT_HTTPS_PROXY=https://secure-proxy.company.com:8080
-export GLOBAL_AGENT_NO_PROXY=localhost,internal.company.com
-export YARN_HTTP_PROXY=http://proxy.company.com:8080                      # optional
-export YARN_HTTPS_PROXY=https://secure-proxy.company.com:8080             # optional
+export HTTP_PROXY=http://proxy.company.com:8080
+export HTTPS_PROXY=https://secure-proxy.company.com:8080
+export NO_PROXY=localhost,internal.company.com
+export GLOBAL_AGENT_HTTP_PROXY=${HTTP_PROXY}
+export GLOBAL_AGENT_HTTPS_PROXY=${HTTPS_PROXY}
+export GLOBAL_AGENT_NO_PROXY=${NO_PROXY}
+export YARN_HTTP_PROXY=${HTTP_PROXY}                          # optional
+export YARN_HTTPS_PROXY=${HTTPS_PROXY}                        # optional
 ```

packages/techdocs-cli/README.md

@@ -44,7 +44,8 @@ yarn techdocs-cli:dev [...options]
 
 ```sh
 # Prior to executing the techdocs-cli command
-export GLOBAL_AGENT_HTTPS_PROXY=${HTTP_PROXY}
+export GLOBAL_AGENT_HTTP_PROXY=${HTTP_PROXY}
+export GLOBAL_AGENT_HTTPS_PROXY=${HTTPS_PROXY}
 export GLOBAL_AGENT_NO_PROXY=${NO_PROXY}
 ```